You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@camel.apache.org by Christian Schneider <ch...@die-schneider.net> on 2009/06/07 09:35:35 UTC
Re: Documenting the Camel DSL
Hi,
I have written a DSL page as a starting point for the DSL documentation.
The page currently shows the languages and the functions.
Then for each function there is a detail page. I have written
documentation for the from, convertBodyTo and a template page for functions.
Could you have a look on the pages and give some feedback?
I am not yet sure about several things:
- How to write the syntax for java and spring? I have experimented with
[] for optionality and <> for symbolic names.
- Should for describe the parameters separately for java and spring?
Normally I think the parameters are the same but sometimes you have to
use them differently.
- Should we show the next possible set of functions in the builder
pattern. So for example in the configure of Routebuilder you have a set
of functions. Inside a route you have a different set. We could
structure the functions in the dsl page by this. Then for each function
page there could be a link to a page that lists the set that is possible
after thiss function
Any suggestions?
Greetings
Christian
Claus Ibsen schrieb:
> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com> wrote:
>
>> Hi Christian,
>>
>> You have a point there :).
>>
>> I personally like the wiki as a documentation tool and I like even more your
>> offer to help :). You have enough karma to start this on the wiki.
>>
> Yeah there is a DSL page that can be used as starting point. Or create
> a new wiki page.
>
> Basically most of the DSL is in the ProcessorDefiniton class, that
> covers 80+% of the DSL we have.
> Then there are some specific DSL per type that is on the xxxDefinition.
>
>
>
Re: Documenting the Camel DSL
Posted by Charles Moulliard <cm...@gmail.com>.
Hi,
I agree on your remarks Christian. It is better to have a single point of
entry for syntax about camel DSL language with examples than using google to
find out where the info has been defined in the wiki pages of camel. Such a
documentation (I will participate to enrich it) is absolutely necessary to
simplify job of developers working on a project and avoid that they spend
too much time to find info.
Regards,
Charles Moulliard
Senior Enterprise Architect
Apache Camel Committer
*****************************
blog : http://cmoulliard.blogspot.com
On Fri, Jun 12, 2009 at 1:00 PM, Christian Schneider <
chris@die-schneider.net> wrote:
> Claus Ibsen schrieb:
>
>> So I doubt its possible to cover all languages in all DSLs. I suggest
>> to focus solely on Spring and Java DSL.
>>
>>
> Yes .. Spring and Java DSL are the focues for me too.
>
>> They are used the most. And we do not absolutely need to have samples
>> for both. Often its possible to translate
>> from one to another. There are some special cases where its not that
>> easy, for instance all related to error handling
>> where the spring DSL is much more different than Java DSL.
>>
>>
> I sometimes had the problem that I knew how to do it in Java but not in
> Spring. Though I think these were exactly the cases where spring and Java
> DSL are different.
> So my suggestion is to do examples mainly in Spring DSL and in Java DSL
> only if it is different.
>
> By micro management I mean that instead of writing 2-3 sections about
>> what it does and provide a few samples over
>> having to provide a strict format for syntax (with and without
>> optional parameters), tables for each and every option, with defaults.
>> And what not.
>>
>>
> I think examples only help to a degree. There are many great examples in
> the Camel Web but I had many cases where I just could not find what I
> intended to do. In these cases a solid reference docuementation would have
> helped me greatly. Of course writing a reference is no fun but it is
> necessary. Though I hope that at some point the documentation can be written
> once (for example in the java doc) and the web and xsd documentation are
> generated automatically. I only think that we should not wait till the
> technology for this is in place as many users of camel are struggling to
> find a good reference.
>
>> Often an example speaks 1000 words.
>>
>>
> Yes. A reference alone would not be enough. Good examples are key to a fast
> understanding. Often it is a little difficult to find the on the camel web
> as they are quite scattered.
> Perhaps there should be two kinds of examples. First the reference based
> examples. These start with e.g. a function and show several usages. Second
> are the use case based examples that start with higher level business use
> case and show how it can be done in camel. I think some of the Cookbook
> pages go into that direction.
>
> And for the EIP I do suggest to improve the existing documentation
>> instead of creating new pages for them. If one of them need a table
>> with options please go ahead and add it.
>>
>>
>>
> Yes.. absolutely. It would be a shame to not use the fine work that has
> been done documenting the EIP.
>
> Please continue the good intentions and dont stop just because I fear
>> of micro managment and documentation being stalled
>> and out-dated. Either we do it or we dont.
>>
>>
> I also fear of out dated documentations but at least with the wiki I hope
> that people from the community help with identifying out dated documentation
> and even help improving it.
> Though I do not have too much illusions about it ;-)
>
> Greetings
>
> Christian
>
>
Re: Documenting the Camel DSL
Posted by Christian Schneider <ch...@die-schneider.net>.
Claus Ibsen schrieb:
> So I doubt its possible to cover all languages in all DSLs. I suggest
> to focus solely on Spring and Java DSL.
>
Yes .. Spring and Java DSL are the focues for me too.
> They are used the most. And we do not absolutely need to have samples
> for both. Often its possible to translate
> from one to another. There are some special cases where its not that
> easy, for instance all related to error handling
> where the spring DSL is much more different than Java DSL.
>
I sometimes had the problem that I knew how to do it in Java but not in
Spring. Though I think these were exactly the cases where spring and
Java DSL are different.
So my suggestion is to do examples mainly in Spring DSL and in Java DSL
only if it is different.
> By micro management I mean that instead of writing 2-3 sections about
> what it does and provide a few samples over
> having to provide a strict format for syntax (with and without
> optional parameters), tables for each and every option, with defaults.
> And what not.
>
I think examples only help to a degree. There are many great examples in
the Camel Web but I had many cases where I just could not find what I
intended to do. In these cases a solid reference docuementation would
have helped me greatly. Of course writing a reference is no fun but it
is necessary. Though I hope that at some point the documentation can be
written once (for example in the java doc) and the web and xsd
documentation are generated automatically. I only think that we should
not wait till the technology for this is in place as many users of camel
are struggling to find a good reference.
> Often an example speaks 1000 words.
>
Yes. A reference alone would not be enough. Good examples are key to a
fast understanding. Often it is a little difficult to find the on the
camel web as they are quite scattered.
Perhaps there should be two kinds of examples. First the reference based
examples. These start with e.g. a function and show several usages.
Second are the use case based examples that start with higher level
business use case and show how it can be done in camel. I think some of
the Cookbook pages go into that direction.
> And for the EIP I do suggest to improve the existing documentation
> instead of creating new pages for them. If one of them need a table
> with options please go ahead and add it.
>
>
Yes.. absolutely. It would be a shame to not use the fine work that has
been done documenting the EIP.
> Please continue the good intentions and dont stop just because I fear
> of micro managment and documentation being stalled
> and out-dated. Either we do it or we dont.
>
I also fear of out dated documentations but at least with the wiki I
hope that people from the community help with identifying out dated
documentation and even help improving it.
Though I do not have too much illusions about it ;-)
Greetings
Christian
Re: Documenting the Camel DSL
Posted by Claus Ibsen <cl...@gmail.com>.
On Tue, Jun 9, 2009 at 12:09 AM, Christian
Schneider<ch...@die-schneider.net> wrote:
> Hi Claus,
>
> I did not really understand your comment 1). Why do you think that we have
> to micro manage the documentation? Is it because both javadoc and wiki have
> to be written?
> This of course is an issue but I could imagine it can be kept in sync. Apart
> from this I do not see that much micro management in the approach. To add
> documentation to one function you simply add a page nothing else has to be
> done.
I really appreciate the effort of doing a full DSL documentation.
But we can barely keep up with Java DSL, Spring DSL and now Scala DSL.
And we also have POJO annotations.
So I doubt its possible to cover all languages in all DSLs. I suggest
to focus solely on Spring and Java DSL.
They are used the most. And we do not absolutely need to have samples
for both. Often its possible to translate
from one to another. There are some special cases where its not that
easy, for instance all related to error handling
where the spring DSL is much more different than Java DSL.
By micro management I mean that instead of writing 2-3 sections about
what it does and provide a few samples over
having to provide a strict format for syntax (with and without
optional parameters), tables for each and every option, with defaults.
And what not.
Often an example speaks 1000 words.
But that said I would also like all options to be listed in a table if
it makes sense. For the convertBodyTo it has no option. The type must
be provided and this its "core option" so I do not think a table is
needed there.
And for the EIP I do suggest to improve the existing documentation
instead of creating new pages for them. If one of them need a table
with options please go ahead and add it.
>
> About 2) you are right. My examples are not very good but they are mainly
> thought as a starting point. Every one with access to the wiki can add
> examples or refine the existing. I mainly wanted to show how the wiki
> template looks for two functions to give a better base for discussion. The
> wiki lives from people helping to improve it. But before we write many pages
> it is a good idea to reach some consensus about the structure as it is a lot
> of work to adapt the structure at a later point. It would be great if you
> could improve the examples to show more context.
Well it should be the community that shims in and improve the
documentation as well.
Not a single mans work. There are plenty of examples scattered in the
existing wiki pages,
that can be used as inspiration. Just use the google search box.
>
> About 4) yes. The EIP patterns are already explained very well though they
> lack a good reference. I think in some way they are the oposite of what you
> did not like in my approach. They have really good examples but no reference
> of the parameters. I think the best approach should have both. Each function
> should have a thorough refrence and good examples. Of course I do not intend
> to write new pages for the EIP patterns. Perhaps we can leave them
> completely untouched at the moment and concentrate on the rest of the
> functions. At a later point it could be a good idea to bring some more
> structure into the eip patterns.
>
> About 5). I am not sure if having only one sample is enough but it would
> surely safe us a lot of work writing the examples.
>
> Greetings
>
> Christian
Please continue the good intentions and dont stop just because I fear
of micro managment and documentation being stalled
and out-dated. Either we do it or we dont.
>
> Claus Ibsen schrieb:
>>
>> Hi
>>
>> We really appreciate the effort to document the DSL.
>>
>> Looking at the current pages done so far I have the following comments:
>>
>> 1)
>> Overall I do not think trying to structure the documentation so
>> rigiours is feasible.
>> It should be fast and easy to add the documentation. Having to micro
>> manage it is bound to people not wanting to do it.
>>
>> 2)
>> The examples is poor. What is needed is a good context where to use
>> it. What is there currently is just the single DSL, as a kind of
>> syntax example.
>> That dont bring much to the table.
>>
>> You dont get the clue that from DSL is used as input to a route as a
>> the event driven consumer.
>> And that the convert body to DSL is used in the middle of a route, for
>> instance to load the file content, or force convertions to a
>> particular type.
>> And there should be a link to the existing type converter page so
>> people can read more about it.
>>
>> And so on. Better examples is better than structure and tables.
>>
>> 3)
>> Also more details what and why we have this DSL.
>>
>> 4)
>> And for the EIP patterns we should of course just link directly to
>> their existing documentation, to avoid repeating yourself.
>>
>> 5)
>> Java vs. Spring. Often having a sample in either one is sufficient. It
>> only makes sense to document the Spring and Java when the Spring is
>> particual different such as the error handler. Or for some more
>> complex DSL such as the splitter, aggregator and whatnot.
>>
>>
>>
>>
>>
>>>
>>> Greetings
>>>
>>> Christian
>>>
>>> Claus Ibsen schrieb:
>>>
>>>>
>>>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>>>> wrote:
>>>>
>>>>
>>>>>
>>>>> Hi Christian,
>>>>>
>>>>> You have a point there :).
>>>>>
>>>>> I personally like the wiki as a documentation tool and I like even more
>>>>> your
>>>>> offer to help :). You have enough karma to start this on the wiki.
>>>>>
>>>>>
>>>>
>>>> Yeah there is a DSL page that can be used as starting point. Or create
>>>> a new wiki page.
>>>>
>>>> Basically most of the DSL is in the ProcessorDefiniton class, that
>>>> covers 80+% of the DSL we have.
>>>> Then there are some specific DSL per type that is on the xxxDefinition.
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>
>>
>>
>>
>
>
--
Claus Ibsen
Apache Camel Committer
Open Source Integration: http://fusesource.com
Blog: http://davsclaus.blogspot.com/
Twitter: http://twitter.com/davsclaus
Re: Documenting the Camel DSL
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Claus,
I did not really understand your comment 1). Why do you think that we
have to micro manage the documentation? Is it because both javadoc and
wiki have to be written?
This of course is an issue but I could imagine it can be kept in sync.
Apart from this I do not see that much micro management in the approach.
To add documentation to one function you simply add a page nothing else
has to be done.
About 2) you are right. My examples are not very good but they are
mainly thought as a starting point. Every one with access to the wiki
can add examples or refine the existing. I mainly wanted to show how the
wiki template looks for two functions to give a better base for
discussion. The wiki lives from people helping to improve it. But before
we write many pages it is a good idea to reach some consensus about the
structure as it is a lot of work to adapt the structure at a later
point. It would be great if you could improve the examples to show more
context.
About 4) yes. The EIP patterns are already explained very well though
they lack a good reference. I think in some way they are the oposite of
what you did not like in my approach. They have really good examples but
no reference of the parameters. I think the best approach should have
both. Each function should have a thorough refrence and good examples.
Of course I do not intend to write new pages for the EIP patterns.
Perhaps we can leave them completely untouched at the moment and
concentrate on the rest of the functions. At a later point it could be a
good idea to bring some more structure into the eip patterns.
About 5). I am not sure if having only one sample is enough but it would
surely safe us a lot of work writing the examples.
Greetings
Christian
Claus Ibsen schrieb:
>
> Hi
>
> We really appreciate the effort to document the DSL.
>
> Looking at the current pages done so far I have the following comments:
>
> 1)
> Overall I do not think trying to structure the documentation so
> rigiours is feasible.
> It should be fast and easy to add the documentation. Having to micro
> manage it is bound to people not wanting to do it.
>
> 2)
> The examples is poor. What is needed is a good context where to use
> it. What is there currently is just the single DSL, as a kind of
> syntax example.
> That dont bring much to the table.
>
> You dont get the clue that from DSL is used as input to a route as a
> the event driven consumer.
> And that the convert body to DSL is used in the middle of a route, for
> instance to load the file content, or force convertions to a
> particular type.
> And there should be a link to the existing type converter page so
> people can read more about it.
>
> And so on. Better examples is better than structure and tables.
>
> 3)
> Also more details what and why we have this DSL.
>
> 4)
> And for the EIP patterns we should of course just link directly to
> their existing documentation, to avoid repeating yourself.
>
> 5)
> Java vs. Spring. Often having a sample in either one is sufficient. It
> only makes sense to document the Spring and Java when the Spring is
> particual different such as the error handler. Or for some more
> complex DSL such as the splitter, aggregator and whatnot.
>
>
>
>
>
>> Greetings
>>
>> Christian
>>
>> Claus Ibsen schrieb:
>>
>>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>>> wrote:
>>>
>>>
>>>> Hi Christian,
>>>>
>>>> You have a point there :).
>>>>
>>>> I personally like the wiki as a documentation tool and I like even more
>>>> your
>>>> offer to help :). You have enough karma to start this on the wiki.
>>>>
>>>>
>>> Yeah there is a DSL page that can be used as starting point. Or create
>>> a new wiki page.
>>>
>>> Basically most of the DSL is in the ProcessorDefiniton class, that
>>> covers 80+% of the DSL we have.
>>> Then there are some specific DSL per type that is on the xxxDefinition.
>>>
>>>
>>>
>>>
>>
>
>
>
>
Re: Documenting the Camel DSL
Posted by Claus Ibsen <cl...@gmail.com>.
On Sun, Jun 7, 2009 at 9:35 AM, Christian
Schneider<ch...@die-schneider.net> wrote:
> Hi,
>
> I have written a DSL page as a starting point for the DSL documentation.
> The page currently shows the languages and the functions.
>
> Then for each function there is a detail page. I have written documentation
> for the from, convertBodyTo and a template page for functions.
> Could you have a look on the pages and give some feedback?
>
> I am not yet sure about several things:
>
> - How to write the syntax for java and spring? I have experimented with []
> for optionality and <> for symbolic names.
> - Should for describe the parameters separately for java and spring?
> Normally I think the parameters are the same but sometimes you have to use
> them differently.
> - Should we show the next possible set of functions in the builder pattern.
> So for example in the configure of Routebuilder you have a set of functions.
> Inside a route you have a different set. We could structure the functions in
> the dsl page by this. Then for each function page there could be a link to a
> page that lists the set that is possible after thiss function
>
> Any suggestions?
Hi
We really appreciate the effort to document the DSL.
Looking at the current pages done so far I have the following comments:
1)
Overall I do not think trying to structure the documentation so
rigiours is feasible.
It should be fast and easy to add the documentation. Having to micro
manage it is bound to people not wanting to do it.
2)
The examples is poor. What is needed is a good context where to use
it. What is there currently is just the single DSL, as a kind of
syntax example.
That dont bring much to the table.
You dont get the clue that from DSL is used as input to a route as a
the event driven consumer.
And that the convert body to DSL is used in the middle of a route, for
instance to load the file content, or force convertions to a
particular type.
And there should be a link to the existing type converter page so
people can read more about it.
And so on. Better examples is better than structure and tables.
3)
Also more details what and why we have this DSL.
4)
And for the EIP patterns we should of course just link directly to
their existing documentation, to avoid repeating yourself.
5)
Java vs. Spring. Often having a sample in either one is sufficient. It
only makes sense to document the Spring and Java when the Spring is
particual different such as the error handler. Or for some more
complex DSL such as the splitter, aggregator and whatnot.
>
> Greetings
>
> Christian
>
> Claus Ibsen schrieb:
>>
>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>> wrote:
>>
>>>
>>> Hi Christian,
>>>
>>> You have a point there :).
>>>
>>> I personally like the wiki as a documentation tool and I like even more
>>> your
>>> offer to help :). You have enough karma to start this on the wiki.
>>>
>>
>> Yeah there is a DSL page that can be used as starting point. Or create
>> a new wiki page.
>>
>> Basically most of the DSL is in the ProcessorDefiniton class, that
>> covers 80+% of the DSL we have.
>> Then there are some specific DSL per type that is on the xxxDefinition.
>>
>>
>>
>
>
--
Claus Ibsen
Apache Camel Committer
Open Source Integration: http://fusesource.com
Blog: http://davsclaus.blogspot.com/
Twitter: http://twitter.com/davsclaus
Re: Documenting the Camel DSL
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Charles,
I have changed the page to directly show the EIP patterns.
Greetings
Christian
Charles Moulliard schrieb:
> Hi Christian,
>
> I prefer to keep the links of the EIP in this page even if they point to the
> existing page for consistency reason.
>
> Regards,
>
> Charles Moulliard
> Senior Enterprise Architect
> Apache Camel Committer
>
> *****************************
> blog : http://cmoulliard.blogspot.com
>
>
> On Tue, Jun 9, 2009 at 12:12 AM, Christian Schneider <
> chris@die-schneider.net> wrote:
>
>
>> Hi Charles,
>>
>> we should really find a good word. I think macros would also be good. Is
>> there a common opinion among the developers how to name them?
>> Grouping functions is a good idea. I propose to first leave out the EIP
>> stuff at first as they are already quite well documented. For the start we
>> could link to the EIP page.
>>
>> Greetings
>>
>> Christian
>>
>> Charles Moulliard schrieb:
>>
>>
>>> Do you think name and excerpt could be enough if the class, examples and
>>>
>>> documentation are found in the detail page?
>>> yes.
>>>
>>> Nevertheless, I propose to group functions (Is it the right name ? -->
>>> could
>>> be macros, ) in the page :
>>> http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
>>>
>>> A. Global / General
>>> - bean
>>> - choice
>>> - from
>>> - to
>>> - convertBodyTo
>>> - marshal
>>> - unmarshal
>>> - try/catch/finally
>>> - transacted
>>> - when
>>>
>>> B. EIP related
>>> - aggregate
>>> - delayer
>>> - filter
>>> - multicast
>>> - splitter
>>> - throttler
>>>
>>> Regards,
>>>
>>> Charles Moulliard
>>> Senior Enterprise Architect
>>> Apache Camel Committer
>>>
>>> *****************************
>>> blog : http://cmoulliard.blogspot.com
>>>
>>>
>>> On Sun, Jun 7, 2009 at 11:45 AM, Christian Schneider <
>>> chris@die-schneider.net> wrote:
>>>
>>>
>>>
>>>
>> --
>>
>> Christian Schneider
>> ---
>> http://www.liquid-reality.de
>>
>>
>>
>
>
--
Christian Schneider
---
http://www.liquid-reality.de
Re: Documenting the Camel DSL
Posted by Charles Moulliard <cm...@gmail.com>.
Hi Christian,
I prefer to keep the links of the EIP in this page even if they point to the
existing page for consistency reason.
Regards,
Charles Moulliard
Senior Enterprise Architect
Apache Camel Committer
*****************************
blog : http://cmoulliard.blogspot.com
On Tue, Jun 9, 2009 at 12:12 AM, Christian Schneider <
chris@die-schneider.net> wrote:
> Hi Charles,
>
> we should really find a good word. I think macros would also be good. Is
> there a common opinion among the developers how to name them?
> Grouping functions is a good idea. I propose to first leave out the EIP
> stuff at first as they are already quite well documented. For the start we
> could link to the EIP page.
>
> Greetings
>
> Christian
>
> Charles Moulliard schrieb:
>
>> Do you think name and excerpt could be enough if the class, examples and
>>
>> documentation are found in the detail page?
>> yes.
>>
>> Nevertheless, I propose to group functions (Is it the right name ? -->
>> could
>> be macros, ) in the page :
>> http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
>>
>> A. Global / General
>> - bean
>> - choice
>> - from
>> - to
>> - convertBodyTo
>> - marshal
>> - unmarshal
>> - try/catch/finally
>> - transacted
>> - when
>>
>> B. EIP related
>> - aggregate
>> - delayer
>> - filter
>> - multicast
>> - splitter
>> - throttler
>>
>> Regards,
>>
>> Charles Moulliard
>> Senior Enterprise Architect
>> Apache Camel Committer
>>
>> *****************************
>> blog : http://cmoulliard.blogspot.com
>>
>>
>> On Sun, Jun 7, 2009 at 11:45 AM, Christian Schneider <
>> chris@die-schneider.net> wrote:
>>
>>
>>
>
>
> --
>
> Christian Schneider
> ---
> http://www.liquid-reality.de
>
>
Re: Documenting the Camel DSL
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Charles,
we should really find a good word. I think macros would also be good. Is
there a common opinion among the developers how to name them?
Grouping functions is a good idea. I propose to first leave out the EIP
stuff at first as they are already quite well documented. For the start
we could link to the EIP page.
Greetings
Christian
Charles Moulliard schrieb:
> Do you think name and excerpt could be enough if the class, examples and
> documentation are found in the detail page?
> yes.
>
> Nevertheless, I propose to group functions (Is it the right name ? --> could
> be macros, ) in the page :
> http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
>
> A. Global / General
> - bean
> - choice
> - from
> - to
> - convertBodyTo
> - marshal
> - unmarshal
> - try/catch/finally
> - transacted
> - when
>
> B. EIP related
> - aggregate
> - delayer
> - filter
> - multicast
> - splitter
> - throttler
>
> Regards,
>
> Charles Moulliard
> Senior Enterprise Architect
> Apache Camel Committer
>
> *****************************
> blog : http://cmoulliard.blogspot.com
>
>
> On Sun, Jun 7, 2009 at 11:45 AM, Christian Schneider <
> chris@die-schneider.net> wrote:
>
>
--
Christian Schneider
---
http://www.liquid-reality.de
Re: Documenting the Camel DSL
Posted by Charles Moulliard <cm...@gmail.com>.
Do you think name and excerpt could be enough if the class, examples and
documentation are found in the detail page?
yes.
Nevertheless, I propose to group functions (Is it the right name ? --> could
be macros, ) in the page :
http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
A. Global / General
- bean
- choice
- from
- to
- convertBodyTo
- marshal
- unmarshal
- try/catch/finally
- transacted
- when
B. EIP related
- aggregate
- delayer
- filter
- multicast
- splitter
- throttler
Regards,
Charles Moulliard
Senior Enterprise Architect
Apache Camel Committer
*****************************
blog : http://cmoulliard.blogspot.com
On Sun, Jun 7, 2009 at 11:45 AM, Christian Schneider <
chris@die-schneider.net> wrote:
> Hi Charles,
>
> I have added an excerpt to each page and show it in the list. I would not
> use a complete table as it would contain much redundant information that
> will also be shown in the detail page.
> I have used the children macro to list the functions this way you only have
> to create the page for the function and do not need to edit the list.
>
> Do you think name and excerpt could be enough if the class, examples and
> documentation are found in the detail page?
>
>
> Greetings
>
> Christian
>
> Charles Moulliard schrieb:
>
>> Hi Christian,
>>
>> Here is what I porpose some weeks ago :
>>
>> May I suggest to add a table in the DSL wiki page (
>> http://camel.apache.org/dsl.html) of Camel with the following info ?
>>
>> *Name | Description | Class | Java example | Spring example |
>> Documentation
>> link
>> from | starting endpoint of the a route | ???? |** from("direct:a") |
>> <from uri="activemq:SomeQueue"/> |`
>> http://camel.apache.org/pipes-and-filters.html*
>>
>> Where can we find the link between the tag name (ex : from()) and the
>> piece
>> of code implementing the DSL action ?
>>
>> Regards,
>>
>> Charles Moulliard
>> Senior Enterprise Architect
>> Apache Camel Committer
>>
>> *****************************
>> blog : http://cmoulliard.blogspot.com
>>
>>
>> On Sun, Jun 7, 2009 at 10:49 AM, Christian Schneider <
>> chris@die-schneider.net> wrote:
>>
>>
>>
>>> Hi Charles,
>>>
>>> sorry forgot the link:
>>>
>>> http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
>>>
>>> About the xsd doc. It is of course great for undertanding the xml syntax.
>>> But there is currently no further documentation in it which makes it
>>> difficult for people to understand. But of course we should link from the
>>> documentation of a function to the xsd doc and the javadoc of the builder
>>> and perhaps also the javadoc of the model and impl class.
>>>
>>> Greetings
>>>
>>> Christian
>>>
>>> Charles Moulliard schrieb:
>>>
>>> Where is the page ?
>>>
>>>
>>>> Have you already had a look to this javadoc page :
>>>>
>>>>
>>>> http://camel.apache.org/maven/camel-spring/xsddoc/http___activemq.apache.org_camel_schema_spring/complexType/outputType.html
>>>> ?
>>>> Maybe this could be helpful too ?
>>>>
>>>> Regards,
>>>>
>>>> Charles Moulliard
>>>> Senior Enterprise Architect
>>>> Apache Camel Committer
>>>>
>>>> *****************************
>>>> blog : http://cmoulliard.blogspot.com
>>>>
>>>>
>>>> On Sun, Jun 7, 2009 at 9:35 AM, Christian Schneider <
>>>> chris@die-schneider.net
>>>>
>>>>
>>>>
>>>>
>>>>> wrote:
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>>> Hi,
>>>>>
>>>>> I have written a DSL page as a starting point for the DSL
>>>>> documentation.
>>>>> The page currently shows the languages and the functions.
>>>>>
>>>>> Then for each function there is a detail page. I have written
>>>>> documentation
>>>>> for the from, convertBodyTo and a template page for functions.
>>>>> Could you have a look on the pages and give some feedback?
>>>>>
>>>>> I am not yet sure about several things:
>>>>>
>>>>> - How to write the syntax for java and spring? I have experimented with
>>>>> []
>>>>> for optionality and <> for symbolic names.
>>>>> - Should for describe the parameters separately for java and spring?
>>>>> Normally I think the parameters are the same but sometimes you have to
>>>>> use
>>>>> them differently.
>>>>> - Should we show the next possible set of functions in the builder
>>>>> pattern.
>>>>> So for example in the configure of Routebuilder you have a set of
>>>>> functions.
>>>>> Inside a route you have a different set. We could structure the
>>>>> functions
>>>>> in
>>>>> the dsl page by this. Then for each function page there could be a link
>>>>> to a
>>>>> page that lists the set that is possible after thiss function
>>>>>
>>>>> Any suggestions?
>>>>>
>>>>> Greetings
>>>>>
>>>>> Christian
>>>>>
>>>>> Claus Ibsen schrieb:
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>>>>>> wrote:
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>> Hi Christian,
>>>>>>>
>>>>>>> You have a point there :).
>>>>>>>
>>>>>>> I personally like the wiki as a documentation tool and I like even
>>>>>>> more
>>>>>>> your
>>>>>>> offer to help :). You have enough karma to start this on the wiki.
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>> Yeah there is a DSL page that can be used as starting point. Or create
>>>>>> a new wiki page.
>>>>>>
>>>>>> Basically most of the DSL is in the ProcessorDefiniton class, that
>>>>>> covers 80+% of the DSL we have.
>>>>>> Then there are some specific DSL per type that is on the
>>>>>> xxxDefinition.
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>> --
>>>
>>> Christian Schneider
>>> ---
>>> http://www.liquid-reality.de
>>>
>>>
>>>
>>>
>>
>>
>>
>
>
> --
>
> Christian Schneider
> ---
> http://www.liquid-reality.de
>
>
Re: Documenting the Camel DSL
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Charles,
I have added an excerpt to each page and show it in the list. I would
not use a complete table as it would contain much redundant information
that will also be shown in the detail page.
I have used the children macro to list the functions this way you only
have to create the page for the function and do not need to edit the list.
Do you think name and excerpt could be enough if the class, examples and
documentation are found in the detail page?
Greetings
Christian
Charles Moulliard schrieb:
> Hi Christian,
>
> Here is what I porpose some weeks ago :
>
> May I suggest to add a table in the DSL wiki page (
> http://camel.apache.org/dsl.html) of Camel with the following info ?
>
> *Name | Description | Class | Java example | Spring example | Documentation
> link
> from | starting endpoint of the a route | ???? |** from("direct:a") |
> <from uri="activemq:SomeQueue"/> |`
> http://camel.apache.org/pipes-and-filters.html*
>
> Where can we find the link between the tag name (ex : from()) and the piece
> of code implementing the DSL action ?
>
> Regards,
>
> Charles Moulliard
> Senior Enterprise Architect
> Apache Camel Committer
>
> *****************************
> blog : http://cmoulliard.blogspot.com
>
>
> On Sun, Jun 7, 2009 at 10:49 AM, Christian Schneider <
> chris@die-schneider.net> wrote:
>
>
>> Hi Charles,
>>
>> sorry forgot the link:
>>
>> http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
>>
>> About the xsd doc. It is of course great for undertanding the xml syntax.
>> But there is currently no further documentation in it which makes it
>> difficult for people to understand. But of course we should link from the
>> documentation of a function to the xsd doc and the javadoc of the builder
>> and perhaps also the javadoc of the model and impl class.
>>
>> Greetings
>>
>> Christian
>>
>> Charles Moulliard schrieb:
>>
>> Where is the page ?
>>
>>> Have you already had a look to this javadoc page :
>>>
>>> http://camel.apache.org/maven/camel-spring/xsddoc/http___activemq.apache.org_camel_schema_spring/complexType/outputType.html
>>> ?
>>> Maybe this could be helpful too ?
>>>
>>> Regards,
>>>
>>> Charles Moulliard
>>> Senior Enterprise Architect
>>> Apache Camel Committer
>>>
>>> *****************************
>>> blog : http://cmoulliard.blogspot.com
>>>
>>>
>>> On Sun, Jun 7, 2009 at 9:35 AM, Christian Schneider <
>>> chris@die-schneider.net
>>>
>>>
>>>
>>>> wrote:
>>>>
>>>>
>>>>
>>>
>>>
>>>> Hi,
>>>>
>>>> I have written a DSL page as a starting point for the DSL documentation.
>>>> The page currently shows the languages and the functions.
>>>>
>>>> Then for each function there is a detail page. I have written
>>>> documentation
>>>> for the from, convertBodyTo and a template page for functions.
>>>> Could you have a look on the pages and give some feedback?
>>>>
>>>> I am not yet sure about several things:
>>>>
>>>> - How to write the syntax for java and spring? I have experimented with
>>>> []
>>>> for optionality and <> for symbolic names.
>>>> - Should for describe the parameters separately for java and spring?
>>>> Normally I think the parameters are the same but sometimes you have to
>>>> use
>>>> them differently.
>>>> - Should we show the next possible set of functions in the builder
>>>> pattern.
>>>> So for example in the configure of Routebuilder you have a set of
>>>> functions.
>>>> Inside a route you have a different set. We could structure the functions
>>>> in
>>>> the dsl page by this. Then for each function page there could be a link
>>>> to a
>>>> page that lists the set that is possible after thiss function
>>>>
>>>> Any suggestions?
>>>>
>>>> Greetings
>>>>
>>>> Christian
>>>>
>>>> Claus Ibsen schrieb:
>>>>
>>>>
>>>>
>>>>
>>>>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>>>>> wrote:
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>> Hi Christian,
>>>>>>
>>>>>> You have a point there :).
>>>>>>
>>>>>> I personally like the wiki as a documentation tool and I like even more
>>>>>> your
>>>>>> offer to help :). You have enough karma to start this on the wiki.
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>> Yeah there is a DSL page that can be used as starting point. Or create
>>>>> a new wiki page.
>>>>>
>>>>> Basically most of the DSL is in the ProcessorDefiniton class, that
>>>>> covers 80+% of the DSL we have.
>>>>> Then there are some specific DSL per type that is on the xxxDefinition.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>> --
>>
>> Christian Schneider
>> ---
>> http://www.liquid-reality.de
>>
>>
>>
>
>
--
Christian Schneider
---
http://www.liquid-reality.de
Re: Documenting the Camel DSL
Posted by Charles Moulliard <cm...@gmail.com>.
Hi Christian,
Here is what I porpose some weeks ago :
May I suggest to add a table in the DSL wiki page (
http://camel.apache.org/dsl.html) of Camel with the following info ?
*Name | Description | Class | Java example | Spring example | Documentation
link
from | starting endpoint of the a route | ???? |** from("direct:a") |
<from uri="activemq:SomeQueue"/> |`
http://camel.apache.org/pipes-and-filters.html*
Where can we find the link between the tag name (ex : from()) and the piece
of code implementing the DSL action ?
Regards,
Charles Moulliard
Senior Enterprise Architect
Apache Camel Committer
*****************************
blog : http://cmoulliard.blogspot.com
On Sun, Jun 7, 2009 at 10:49 AM, Christian Schneider <
chris@die-schneider.net> wrote:
> Hi Charles,
>
> sorry forgot the link:
>
> http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
>
> About the xsd doc. It is of course great for undertanding the xml syntax.
> But there is currently no further documentation in it which makes it
> difficult for people to understand. But of course we should link from the
> documentation of a function to the xsd doc and the javadoc of the builder
> and perhaps also the javadoc of the model and impl class.
>
> Greetings
>
> Christian
>
> Charles Moulliard schrieb:
>
> Where is the page ?
>>
>> Have you already had a look to this javadoc page :
>>
>> http://camel.apache.org/maven/camel-spring/xsddoc/http___activemq.apache.org_camel_schema_spring/complexType/outputType.html
>> ?
>> Maybe this could be helpful too ?
>>
>> Regards,
>>
>> Charles Moulliard
>> Senior Enterprise Architect
>> Apache Camel Committer
>>
>> *****************************
>> blog : http://cmoulliard.blogspot.com
>>
>>
>> On Sun, Jun 7, 2009 at 9:35 AM, Christian Schneider <
>> chris@die-schneider.net
>>
>>
>>> wrote:
>>>
>>>
>>
>>
>>
>>> Hi,
>>>
>>> I have written a DSL page as a starting point for the DSL documentation.
>>> The page currently shows the languages and the functions.
>>>
>>> Then for each function there is a detail page. I have written
>>> documentation
>>> for the from, convertBodyTo and a template page for functions.
>>> Could you have a look on the pages and give some feedback?
>>>
>>> I am not yet sure about several things:
>>>
>>> - How to write the syntax for java and spring? I have experimented with
>>> []
>>> for optionality and <> for symbolic names.
>>> - Should for describe the parameters separately for java and spring?
>>> Normally I think the parameters are the same but sometimes you have to
>>> use
>>> them differently.
>>> - Should we show the next possible set of functions in the builder
>>> pattern.
>>> So for example in the configure of Routebuilder you have a set of
>>> functions.
>>> Inside a route you have a different set. We could structure the functions
>>> in
>>> the dsl page by this. Then for each function page there could be a link
>>> to a
>>> page that lists the set that is possible after thiss function
>>>
>>> Any suggestions?
>>>
>>> Greetings
>>>
>>> Christian
>>>
>>> Claus Ibsen schrieb:
>>>
>>>
>>>
>>>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>>>> wrote:
>>>>
>>>>
>>>>
>>>>
>>>>> Hi Christian,
>>>>>
>>>>> You have a point there :).
>>>>>
>>>>> I personally like the wiki as a documentation tool and I like even more
>>>>> your
>>>>> offer to help :). You have enough karma to start this on the wiki.
>>>>>
>>>>>
>>>>>
>>>>>
>>>> Yeah there is a DSL page that can be used as starting point. Or create
>>>> a new wiki page.
>>>>
>>>> Basically most of the DSL is in the ProcessorDefiniton class, that
>>>> covers 80+% of the DSL we have.
>>>> Then there are some specific DSL per type that is on the xxxDefinition.
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>
>>
>>
>
>
> --
>
> Christian Schneider
> ---
> http://www.liquid-reality.de
>
>
Re: Documenting the Camel DSL
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Charles,
sorry forgot the link:
http://cwiki.apache.org/confluence/display/CAMEL/Camel+DSL
About the xsd doc. It is of course great for undertanding the xml
syntax. But there is currently no further documentation in it which
makes it difficult for people to understand. But of course we should
link from the documentation of a function to the xsd doc and the javadoc
of the builder and perhaps also the javadoc of the model and impl class.
Greetings
Christian
Charles Moulliard schrieb:
> Where is the page ?
>
> Have you already had a look to this javadoc page :
> http://camel.apache.org/maven/camel-spring/xsddoc/http___activemq.apache.org_camel_schema_spring/complexType/outputType.html?
> Maybe this could be helpful too ?
>
> Regards,
>
> Charles Moulliard
> Senior Enterprise Architect
> Apache Camel Committer
>
> *****************************
> blog : http://cmoulliard.blogspot.com
>
>
> On Sun, Jun 7, 2009 at 9:35 AM, Christian Schneider <chris@die-schneider.net
>
>> wrote:
>>
>
>
>> Hi,
>>
>> I have written a DSL page as a starting point for the DSL documentation.
>> The page currently shows the languages and the functions.
>>
>> Then for each function there is a detail page. I have written documentation
>> for the from, convertBodyTo and a template page for functions.
>> Could you have a look on the pages and give some feedback?
>>
>> I am not yet sure about several things:
>>
>> - How to write the syntax for java and spring? I have experimented with []
>> for optionality and <> for symbolic names.
>> - Should for describe the parameters separately for java and spring?
>> Normally I think the parameters are the same but sometimes you have to use
>> them differently.
>> - Should we show the next possible set of functions in the builder pattern.
>> So for example in the configure of Routebuilder you have a set of functions.
>> Inside a route you have a different set. We could structure the functions in
>> the dsl page by this. Then for each function page there could be a link to a
>> page that lists the set that is possible after thiss function
>>
>> Any suggestions?
>>
>> Greetings
>>
>> Christian
>>
>> Claus Ibsen schrieb:
>>
>>
>>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>>> wrote:
>>>
>>>
>>>
>>>> Hi Christian,
>>>>
>>>> You have a point there :).
>>>>
>>>> I personally like the wiki as a documentation tool and I like even more
>>>> your
>>>> offer to help :). You have enough karma to start this on the wiki.
>>>>
>>>>
>>>>
>>> Yeah there is a DSL page that can be used as starting point. Or create
>>> a new wiki page.
>>>
>>> Basically most of the DSL is in the ProcessorDefiniton class, that
>>> covers 80+% of the DSL we have.
>>> Then there are some specific DSL per type that is on the xxxDefinition.
>>>
>>>
>>>
>>>
>>>
>>
>
>
--
Christian Schneider
---
http://www.liquid-reality.de
Re: Documenting the Camel DSL
Posted by Charles Moulliard <cm...@gmail.com>.
Where is the page ?
Have you already had a look to this javadoc page :
http://camel.apache.org/maven/camel-spring/xsddoc/http___activemq.apache.org_camel_schema_spring/complexType/outputType.html?
Maybe this could be helpful too ?
Regards,
Charles Moulliard
Senior Enterprise Architect
Apache Camel Committer
*****************************
blog : http://cmoulliard.blogspot.com
On Sun, Jun 7, 2009 at 9:35 AM, Christian Schneider <chris@die-schneider.net
> wrote:
> Hi,
>
> I have written a DSL page as a starting point for the DSL documentation.
> The page currently shows the languages and the functions.
>
> Then for each function there is a detail page. I have written documentation
> for the from, convertBodyTo and a template page for functions.
> Could you have a look on the pages and give some feedback?
>
> I am not yet sure about several things:
>
> - How to write the syntax for java and spring? I have experimented with []
> for optionality and <> for symbolic names.
> - Should for describe the parameters separately for java and spring?
> Normally I think the parameters are the same but sometimes you have to use
> them differently.
> - Should we show the next possible set of functions in the builder pattern.
> So for example in the configure of Routebuilder you have a set of functions.
> Inside a route you have a different set. We could structure the functions in
> the dsl page by this. Then for each function page there could be a link to a
> page that lists the set that is possible after thiss function
>
> Any suggestions?
>
> Greetings
>
> Christian
>
> Claus Ibsen schrieb:
>
>> On Tue, May 19, 2009 at 9:56 PM, Hadrian Zbarcea <hz...@gmail.com>
>> wrote:
>>
>>
>>> Hi Christian,
>>>
>>> You have a point there :).
>>>
>>> I personally like the wiki as a documentation tool and I like even more
>>> your
>>> offer to help :). You have enough karma to start this on the wiki.
>>>
>>>
>> Yeah there is a DSL page that can be used as starting point. Or create
>> a new wiki page.
>>
>> Basically most of the DSL is in the ProcessorDefiniton class, that
>> covers 80+% of the DSL we have.
>> Then there are some specific DSL per type that is on the xxxDefinition.
>>
>>
>>
>>
>
>