I've added a couple of wiki pages to help describe the new capabilities: the endpoint annotations: https://cwiki.apache.org/confluence/display/CAMEL/Endpoint+Annotations
the ComponentConfiguration API: https://cwiki.apache.org/confluence/display/CAMEL/ComponentConfiguration On 23 April 2013 09:47, James Strachan <james.strac...@gmail.com> wrote: > Endpoint documentation is manually created on the wiki which is quite > error prone; plus the wiki page has to then cope with every version of > Camel we release and is very easy to get stale and incorrect - and > with all the 'since version X' text its confusing for users. > > Additionally its hard for tool providers to create user interfaces to > let users create and edit endpoint parameters in IDEs and web > consoles. > > To help address this we now have: > > * a maven plugin which can automaticaly generate HTML documentation > for how to configure an endpoint as part of the maven site, if you add > a few annotations into your Endpoint code. > https://issues.apache.org/jira/browse/CAMEL-6304 > > If you grab the latest code, do a build, then run: > > cd camel-core > open target/classes/org/apache/camel/component/timer.html > > you'll see the generated HTML docuemtnation for the timer endpoint. > This is then included by default in the jar; so folks can easily get > the documentation for the components on their classpath. > > Or run: > > mvn site > > and you'll see the Camel Endpoints page generated in the maven site reports. > > To get an idea of the annotations, here's the Timer endpoint > https://github.com/apache/camel/blob/trunk/camel-core/src/main/java/org/apache/camel/component/timer/TimerEndpoint.java#L40 > > notice the use of @UriEndpoint on the endpoint (which links to the > consumer also) then the @UriParam for any URI parameter. (We could in > the future use @UriParam on setters too; for now only field annotation > is supported). > > > * a ComponentConfiguration API so that tools can introspect components > to discover the available parameters and their types and metadata; > then create/edit either URIs or Endpoints directly > https://issues.apache.org/jira/browse/CAMEL-6306 > > The nice thing about the new ComponentConfiguration API is that a tool > can start from scratch; you don't need to create an endpoint first > from a URI before you can configure things like with > EndpointConfiguration. Also the ComponentConfiguration API is > introspectable; you can ask for all the available > ParameterConfiguration objects (with the name and their types and any > associated metadata such as if Bean Validation API annotations are > used etc). > > So today all Camel components work nicely with the > ComponentConfiguration API out of the box; though for components which > don't use the @UriEndpoint annotations, you have to create an endpoint > first before you can introspect what parameters are available. However > for @UriEndpoint annotated endpoints you can immediately get all the > parameter names and types (and any associated metadata such as if bean > validation annotations are used etc). > > To get an idea for what tools can do with the ComponentConfiguration > API check out the test case: > https://github.com/apache/camel/blob/trunk/camel-core/src/test/java/org/apache/camel/impl/ComponentConfigurationTest.java#L69 > > Note the differences between UriEndpointComponents (i.e. components > annotated with @UriEndpoint) and with regular camel components with no > metadata. Also note how you can start with nothing; or start with an > existing endpoint or URI; then edit the configuration and finally > create or edit a URI or Endpoint. > > > Going forward: > ------------------- > > Ideally it would be good to annotate as many of the camel components > as possible and move the documentation from the wiki into the Java > source code as javadoc comments so we can more to a more code > generated model of endpoint documentation; we can then generate the > maven site for each release to make the docs a little easier to grok > (so when folks are looking at older releases they don't see loads of > new features all over the page that they can't use ;-). Annotating the > existing components is pretty trivial stuff and it doesn't change the > behaviour of the code at all; its purely for documentation generation. > > It would be good to get a CI job to run "mvn site:deploy" so that we > can view & browse the generated documentation and maybe eventually > link the wiki to the generated docs (or even include the generted docs > inside the wiki page). > > I guess now we should recommend folks start writing new endpoints with > the annotations as an easier way to start writing components; which > are then self-documenting and more easily used in tools. > > > For now I've not yet wired the EndpointConfiguration to the > ComponentConfiguration; we could then unify the two things together so > that EndpointConfiguration delegates to ComponentConfiguration maybe; > then folks could create a configuration from a Component (i.e. in an > empty command line / form in a tool) or could create a configuration > from an Endpoint (which can then be pre-populated with the parameters > and their types etc). > > What do folks think of the HTML reports? It might be nice to generate > an index site too (e.g. a bit like JavaDoc but with endpoint schemes > rather than packages/classes) so its easier to navigate all the camel > endpoint configuration? > > Plus adding in Bean Validation annotation support would be nice (so we > could highlight validation rules etc). > > Thoughts? > > -- > James > ------- > Red Hat > > Email: jstra...@redhat.com > Web: http://fusesource.com > Twitter: jstrachan, fusenews > Blog: http://macstrac.blogspot.com/ > > Open Source Integration -- James ------- Red Hat Email: jstra...@redhat.com Web: http://fusesource.com Twitter: jstrachan, fusenews Blog: http://macstrac.blogspot.com/ Open Source Integration
