You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by James Strachan <ja...@gmail.com> on 2013/04/23 10:47:35 UTC
improving Endpoint documentation and tooling
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: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by James Strachan <ja...@gmail.com>.
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 <ja...@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: jstracha@redhat.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration
--
James
-------
Red Hat
Email: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by AlanFoster <al...@alanfoster.me>.
Hi,
I've got a quick question about making use of this for tooling.
I wonder if there would be such a way of getting access to the endpoint
information without trying to instantiate the camel context and such? So
that the tooling can be somewhat agnostic of Camel's instantiation process.
Currently I have basic support for a plugin which can directly access the
Component class by searching for for the relevant META-INF/services file
with the component name. I wonder if it would be possible to then get access
to the endpoint information directly from this class without instantiating
core parts of Camel? IE would it be simple enough to attempt to statically
analyse this class, or will instantiating Camel objects be the least painful
way to do this?
I'm also imagining that the endpoints might need some additional type
information too, for instance if a String parameter should contain a FQCN or
a bean name, or in the case of direct/vm/seda that it will link to another
route. This kind of meta information would be great for performing
validation/renaming/intellisense within the IDE!
It would be great to hear any opinions about this :)
Cheers,
Alan
--
View this message in context: http://camel.465427.n5.nabble.com/improving-Endpoint-documentation-and-tooling-tp5731334p5733219.html
Sent from the Camel Development mailing list archive at Nabble.com.
Re: improving Endpoint documentation and tooling
Posted by Claus Ibsen <cl...@gmail.com>.
Hi
Yeah lets use JDK7 for building Camel 2.12, then we got the docs and
the built binaries is still version 1.6 compliant, as that's what we
have configured the Maven to use.
We did use JDK6 for Camel 2.11 which we just released.
Though I think its fine for moving on to JDK7. others do this as well,
eg such as Spring Framework
Manifest-Version: 1.0
Created-By: 1.7.0_10 (Oracle Corporation)
Implementation-Title: spring-core
Implementation-Version: 3.2.2.RELEASE
On Tue, Apr 30, 2013 at 9:58 AM, Babak Vahdat
<ba...@swissonline.ch> wrote:
> I did the following changes to make the CI build work again on JDK 1.6:
>
> https://github.com/apache/camel/blob/trunk/camel-core/pom.xml#L395
> https://github.com/apache/camel/blob/trunk/components/pom.xml#L214
>
> Makes sense?
>
> Also see my comment here:
>
> http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-tp5731673p5731743.html
>
> WDYT about my proposal there concerning using JDK 1.7 to build the upcoming
> 2.12 release?
>
> Babak
>
>
> jstrachan wrote
>> On 29 April 2013 09:01, Babak Vahdat <
>
>> babak.vahdat@
>
>> > wrote:
>>>
>>>
>>> Am 29.04.13 08:00 schrieb "James Strachan" unter
>>> <
>
>> james.strachan@
>
>> >:
>>>
>>>>On 28 April 2013 23:46, Babak Vahdat <
>
>> babak.vahdat@
>
>> > wrote:
>>>>> Hi James,
>>>>>
>>>>> Another awesome stuff of yours, Thanks!
>>>>>
>>>>> Though I've got three questions:
>>>>>
>>>>> 1) Following the instructions of yours above I don't see any generated
>>>>>html
>>>>> docs @
>>>>>
>>>>> camel-core/target/classes/org/apache/camel/component
>>>>>
>>>>> Is there any other steps I'm missing here?
>>>>
>>>>No - though I used JDK 1.7; which JDK & OS are you using?
>>>
>>> Normally I use JDK 1.6 on OS-X but now switching to JDK 1.7 now generates
>>> me the HTML docs as well:
>>>
>>> ~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
>>> mvn -v
>>> Apache Maven 3.0.4 (r1232337; 2012-01-17 09:44:56+0100)
>>> Maven home: /Users/bvahdat/dev/apache-maven-3.0.4
>>> Java version: 1.7.0_06-ea, vendor: Oracle Corporation
>>> Java home:
>>> /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk/Contents/Home/jre
>>> Default locale: de_DE, platform encoding: UTF-8
>>> OS name: "mac os x", version: "10.7.5", arch: "x86_64", family: "mac"
>>>
>>> ~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
>>> ls *.html
>>> bean.html file.html seda.html timer.html
>>
>> Ah great!
>>
>> Hopefully if you run "mvn site" you should see some nice HTML in the
>> maven site for the endpoint configurations too
>>
>>
>>> Yeah it seems under JDK 1.6, the annotation processing to be not that
>>> much
>>> stable but as long as we can make it to not break our builds then it's
>>> fine and we could mention this on Wiki that this documentation feature is
>>> only available using JDK 1.7+
>>>
>>> I've got a Windows box as well (hope you can believe me :-)) and will try
>>> to run the build both using JDK 1.6 & JDK 1.7 on that as well to see how
>>> that would go.
>>
>> Thanks! At least the CI builds seem to work fine on Java 1.6 now; so
>> maybe we don't have to exclude the apt module for Java 1.6?
>>
>> --
>> James
>> -------
>> Red Hat
>>
>> Email:
>
>> jstracha@
>
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration
>
>
>
>
>
> --
> View this message in context: http://camel.465427.n5.nabble.com/improving-Endpoint-documentation-and-tooling-tp5731334p5731774.html
> Sent from the Camel Development mailing list archive at Nabble.com.
--
Claus Ibsen
-----------------
Red Hat, Inc.
FuseSource is now part of Red Hat
Email: cibsen@redhat.com
Web: http://fusesource.com
Twitter: davsclaus
Blog: http://davsclaus.com
Author of Camel in Action: http://www.manning.com/ibsen
Re: improving Endpoint documentation and tooling
Posted by James Strachan <ja...@gmail.com>.
On 30 April 2013 08:58, Babak Vahdat <ba...@swissonline.ch> wrote:
> I did the following changes to make the CI build work again on JDK 1.6:
>
> https://github.com/apache/camel/blob/trunk/camel-core/pom.xml#L395
> https://github.com/apache/camel/blob/trunk/components/pom.xml#L214
>
> Makes sense?
Ah OK, thanks!
> Also see my comment here:
>
> http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-tp5731673p5731743.html
>
> WDYT about my proposal there concerning using JDK 1.7 to build the upcoming
> 2.12 release?
Sounds like a great idea to me.
--
James
-------
Red Hat
Email: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by Babak Vahdat <ba...@swissonline.ch>.
I did the following changes to make the CI build work again on JDK 1.6:
https://github.com/apache/camel/blob/trunk/camel-core/pom.xml#L395
https://github.com/apache/camel/blob/trunk/components/pom.xml#L214
Makes sense?
Also see my comment here:
http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-tp5731673p5731743.html
WDYT about my proposal there concerning using JDK 1.7 to build the upcoming
2.12 release?
Babak
jstrachan wrote
> On 29 April 2013 09:01, Babak Vahdat <
> babak.vahdat@
> > wrote:
>>
>>
>> Am 29.04.13 08:00 schrieb "James Strachan" unter
>> <
> james.strachan@
> >:
>>
>>>On 28 April 2013 23:46, Babak Vahdat <
> babak.vahdat@
> > wrote:
>>>> Hi James,
>>>>
>>>> Another awesome stuff of yours, Thanks!
>>>>
>>>> Though I've got three questions:
>>>>
>>>> 1) Following the instructions of yours above I don't see any generated
>>>>html
>>>> docs @
>>>>
>>>> camel-core/target/classes/org/apache/camel/component
>>>>
>>>> Is there any other steps I'm missing here?
>>>
>>>No - though I used JDK 1.7; which JDK & OS are you using?
>>
>> Normally I use JDK 1.6 on OS-X but now switching to JDK 1.7 now generates
>> me the HTML docs as well:
>>
>> ~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
>> mvn -v
>> Apache Maven 3.0.4 (r1232337; 2012-01-17 09:44:56+0100)
>> Maven home: /Users/bvahdat/dev/apache-maven-3.0.4
>> Java version: 1.7.0_06-ea, vendor: Oracle Corporation
>> Java home:
>> /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk/Contents/Home/jre
>> Default locale: de_DE, platform encoding: UTF-8
>> OS name: "mac os x", version: "10.7.5", arch: "x86_64", family: "mac"
>>
>> ~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
>> ls *.html
>> bean.html file.html seda.html timer.html
>
> Ah great!
>
> Hopefully if you run "mvn site" you should see some nice HTML in the
> maven site for the endpoint configurations too
>
>
>> Yeah it seems under JDK 1.6, the annotation processing to be not that
>> much
>> stable but as long as we can make it to not break our builds then it's
>> fine and we could mention this on Wiki that this documentation feature is
>> only available using JDK 1.7+
>>
>> I've got a Windows box as well (hope you can believe me :-)) and will try
>> to run the build both using JDK 1.6 & JDK 1.7 on that as well to see how
>> that would go.
>
> Thanks! At least the CI builds seem to work fine on Java 1.6 now; so
> maybe we don't have to exclude the apt module for Java 1.6?
>
> --
> James
> -------
> Red Hat
>
> Email:
> jstracha@
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration
--
View this message in context: http://camel.465427.n5.nabble.com/improving-Endpoint-documentation-and-tooling-tp5731334p5731774.html
Sent from the Camel Development mailing list archive at Nabble.com.
Re: improving Endpoint documentation and tooling
Posted by James Strachan <ja...@gmail.com>.
On 29 April 2013 09:01, Babak Vahdat <ba...@swissonline.ch> wrote:
>
>
> Am 29.04.13 08:00 schrieb "James Strachan" unter
> <ja...@gmail.com>:
>
>>On 28 April 2013 23:46, Babak Vahdat <ba...@swissonline.ch> wrote:
>>> Hi James,
>>>
>>> Another awesome stuff of yours, Thanks!
>>>
>>> Though I've got three questions:
>>>
>>> 1) Following the instructions of yours above I don't see any generated
>>>html
>>> docs @
>>>
>>> camel-core/target/classes/org/apache/camel/component
>>>
>>> Is there any other steps I'm missing here?
>>
>>No - though I used JDK 1.7; which JDK & OS are you using?
>
> Normally I use JDK 1.6 on OS-X but now switching to JDK 1.7 now generates
> me the HTML docs as well:
>
> ~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
> mvn -v
> Apache Maven 3.0.4 (r1232337; 2012-01-17 09:44:56+0100)
> Maven home: /Users/bvahdat/dev/apache-maven-3.0.4
> Java version: 1.7.0_06-ea, vendor: Oracle Corporation
> Java home:
> /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk/Contents/Home/jre
> Default locale: de_DE, platform encoding: UTF-8
> OS name: "mac os x", version: "10.7.5", arch: "x86_64", family: "mac"
>
> ~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
> ls *.html
> bean.html file.html seda.html timer.html
Ah great!
Hopefully if you run "mvn site" you should see some nice HTML in the
maven site for the endpoint configurations too
> Yeah it seems under JDK 1.6, the annotation processing to be not that much
> stable but as long as we can make it to not break our builds then it's
> fine and we could mention this on Wiki that this documentation feature is
> only available using JDK 1.7+
>
> I've got a Windows box as well (hope you can believe me :-)) and will try
> to run the build both using JDK 1.6 & JDK 1.7 on that as well to see how
> that would go.
Thanks! At least the CI builds seem to work fine on Java 1.6 now; so
maybe we don't have to exclude the apt module for Java 1.6?
--
James
-------
Red Hat
Email: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by James Strachan <ja...@gmail.com>.
On 29 April 2013 07:00, James Strachan <ja...@gmail.com> wrote:
> On 28 April 2013 23:46, Babak Vahdat <ba...@swissonline.ch> wrote:
>> Hi James,
>>
>> Another awesome stuff of yours, Thanks!
>>
>> Though I've got three questions:
>>
>> 1) Following the instructions of yours above I don't see any generated html
>> docs @
>>
>> camel-core/target/classes/org/apache/camel/component
>>
>> Is there any other steps I'm missing here?
>
> No - though I used JDK 1.7; which JDK & OS are you using?
FWIW I just tried JDK 1.6 then I got no HTML generated.
The build seems to work OK for me though.
>> 2) My suspicion is that the recent failed compilation by our
>> Camel.trunk.notest CI-Server profile is because of the new Maven module
>> (org.apache.camel.apt) as apparently JDK 6 annotation processing has known
>> bug(s). So my question is if there would be some easy way to disable
>> annotation processing (e.g using a profile) so that we could experiment this
>> on CI-Server to see if this would be really the root cause of the problem?
>
> Yeah, we could disable the apt dependency unless on JDK. Am on
> vacation today; will take a stab tomorrow if noone beats me to it. The
> apt is only for the doc generation; so its no biggie to only enable it
> on a profile or jdk basis.
>
>
>
>> And if we could provide a proper fix of this. More details here:
>>
>>
>> http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-td5731673.html
>>
>> 3) Would it make sense to restrict the EndpointAnnotationProcessor's
>> @SupportedAnnotationTypes to ONLY:
>>
>> @SupportedAnnotationTypes({"org.apache.camel.spi.*"})
>>
>> I think in this way we could skip the non relevant annotations we have like
>> "org.apache.camel.language.NamespacePrefix" which is currently causing
>> problem on CI-Server.
>
> Ah yeah, thats a good idea! Just committed; I also used Java 7 source
> format for the annotation processor in case that helps.
I just rolled that bit back; as the Java 7 source flag doesn't work on
JDK 1.6 :)
--
James
-------
Red Hat
Email: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by Babak Vahdat <ba...@swissonline.ch>.
Am 29.04.13 08:00 schrieb "James Strachan" unter
<ja...@gmail.com>:
>On 28 April 2013 23:46, Babak Vahdat <ba...@swissonline.ch> wrote:
>> Hi James,
>>
>> Another awesome stuff of yours, Thanks!
>>
>> Though I've got three questions:
>>
>> 1) Following the instructions of yours above I don't see any generated
>>html
>> docs @
>>
>> camel-core/target/classes/org/apache/camel/component
>>
>> Is there any other steps I'm missing here?
>
>No - though I used JDK 1.7; which JDK & OS are you using?
Normally I use JDK 1.6 on OS-X but now switching to JDK 1.7 now generates
me the HTML docs as well:
~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
mvn -v
Apache Maven 3.0.4 (r1232337; 2012-01-17 09:44:56+0100)
Maven home: /Users/bvahdat/dev/apache-maven-3.0.4
Java version: 1.7.0_06-ea, vendor: Oracle Corporation
Java home:
/Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk/Contents/Home/jre
Default locale: de_DE, platform encoding: UTF-8
OS name: "mac os x", version: "10.7.5", arch: "x86_64", family: "mac"
~/dev/workspace/camel/camel-core/target/classes/org/apache/camel/component>
ls *.html
bean.html file.html seda.html timer.html
Yeah it seems under JDK 1.6, the annotation processing to be not that much
stable but as long as we can make it to not break our builds then it's
fine and we could mention this on Wiki that this documentation feature is
only available using JDK 1.7+
I've got a Windows box as well (hope you can believe me :-)) and will try
to run the build both using JDK 1.6 & JDK 1.7 on that as well to see how
that would go.
Babak
>
>
>> 2) My suspicion is that the recent failed compilation by our
>> Camel.trunk.notest CI-Server profile is because of the new Maven module
>> (org.apache.camel.apt) as apparently JDK 6 annotation processing has
>>known
>> bug(s). So my question is if there would be some easy way to disable
>> annotation processing (e.g using a profile) so that we could experiment
>>this
>> on CI-Server to see if this would be really the root cause of the
>>problem?
>
>Yeah, we could disable the apt dependency unless on JDK. Am on
>vacation today; will take a stab tomorrow if noone beats me to it. The
>apt is only for the doc generation; so its no biggie to only enable it
>on a profile or jdk basis.
>
>
>
>> And if we could provide a proper fix of this. More details here:
>>
>>
>>
>>http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-td5731673.h
>>tml
>>
>> 3) Would it make sense to restrict the EndpointAnnotationProcessor's
>> @SupportedAnnotationTypes to ONLY:
>>
>> @SupportedAnnotationTypes({"org.apache.camel.spi.*"})
>>
>> I think in this way we could skip the non relevant annotations we have
>>like
>> "org.apache.camel.language.NamespacePrefix" which is currently causing
>> problem on CI-Server.
>
>Ah yeah, thats a good idea! Just committed; I also used Java 7 source
>format for the annotation processor in case that helps.
Thanks for committing that fix.
>
>--
>James
>-------
>Red Hat
>
>Email: jstracha@redhat.com
>Web: http://fusesource.com
>Twitter: jstrachan, fusenews
>Blog: http://macstrac.blogspot.com/
>
>Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by James Strachan <ja...@gmail.com>.
On 28 April 2013 23:46, Babak Vahdat <ba...@swissonline.ch> wrote:
> Hi James,
>
> Another awesome stuff of yours, Thanks!
>
> Though I've got three questions:
>
> 1) Following the instructions of yours above I don't see any generated html
> docs @
>
> camel-core/target/classes/org/apache/camel/component
>
> Is there any other steps I'm missing here?
No - though I used JDK 1.7; which JDK & OS are you using?
> 2) My suspicion is that the recent failed compilation by our
> Camel.trunk.notest CI-Server profile is because of the new Maven module
> (org.apache.camel.apt) as apparently JDK 6 annotation processing has known
> bug(s). So my question is if there would be some easy way to disable
> annotation processing (e.g using a profile) so that we could experiment this
> on CI-Server to see if this would be really the root cause of the problem?
Yeah, we could disable the apt dependency unless on JDK. Am on
vacation today; will take a stab tomorrow if noone beats me to it. The
apt is only for the doc generation; so its no biggie to only enable it
on a profile or jdk basis.
> And if we could provide a proper fix of this. More details here:
>
>
> http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-td5731673.html
>
> 3) Would it make sense to restrict the EndpointAnnotationProcessor's
> @SupportedAnnotationTypes to ONLY:
>
> @SupportedAnnotationTypes({"org.apache.camel.spi.*"})
>
> I think in this way we could skip the non relevant annotations we have like
> "org.apache.camel.language.NamespacePrefix" which is currently causing
> problem on CI-Server.
Ah yeah, thats a good idea! Just committed; I also used Java 7 source
format for the annotation processor in case that helps.
--
James
-------
Red Hat
Email: jstracha@redhat.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration
Re: improving Endpoint documentation and tooling
Posted by Babak Vahdat <ba...@swissonline.ch>.
Hi James,
Another awesome stuff of yours, Thanks!
Though I've got three questions:
1) Following the instructions of yours above I don't see any generated html
docs @
camel-core/target/classes/org/apache/camel/component
Is there any other steps I'm missing here?
2) My suspicion is that the recent failed compilation by our
Camel.trunk.notest CI-Server profile is because of the new Maven module
(org.apache.camel.apt) as apparently JDK 6 annotation processing has known
bug(s). So my question is if there would be some easy way to disable
annotation processing (e.g using a profile) so that we could experiment this
on CI-Server to see if this would be really the root cause of the problem?
And if we could provide a proper fix of this. More details here:
http://camel.465427.n5.nabble.com/Our-builds-looks-really-bad-td5731673.html
3) Would it make sense to restrict the EndpointAnnotationProcessor's
@SupportedAnnotationTypes to ONLY:
@SupportedAnnotationTypes({"org.apache.camel.spi.*"})
I think in this way we could skip the non relevant annotations we have like
"org.apache.camel.language.NamespacePrefix" which is currently causing
problem on CI-Server.
Babak
--
View this message in context: http://camel.465427.n5.nabble.com/improving-Endpoint-documentation-and-tooling-tp5731334p5731708.html
Sent from the Camel Development mailing list archive at Nabble.com.