You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@servicemix.apache.org by Jean-Baptiste Onofré <jb...@nanthrax.net> on 2010/08/13 11:41:16 UTC
[DISCUSS] Archetypes structure and content
Hi all,
After a first archetype release vote, some discussions have involved on IRC.
There is two points that have to be clarified:
1/ Archetypes and components
Currently, we have one archetype per endpoint type. For example, we have
one archetype to create a HTTP Consumer endpoint, one archetype to
create a HTTP Provider endpoint, etc.
I have homogenized all archetype in this way, splitting some like
servicemix-mail-service-unit in servicemix-mail-poller-service-unit and
servicemix-mail-sender-service-unit.
Using this solution:
- we have important number of archetypes (it's maybe not simple for user
to pick up the right one)
- each archetype provides a simple xbean corresponding exactly of the
expected behavior (for example, the user will have a HTTP consumer
endpoint and only this using servicemix-http-consumer-service-unit).
We have another way to see archetypes: one archetype per component.
In that case, we have only servicemix-http-service-unit.
The xbean.xml contains all possible endpoints configuration.
2/ XBean content and documentation
The archetypes provide a sample xbean with the endpoint configuration.
A comment should be present just before the endpoint snippet:
<!-- Endpoint description -->
<component:endpoint ... />
This comment could contain:
- the URL of the component wiki page
- a brief documentation on the endpoint: what the endpoint does, what
the endpoint attributes.
Another question is: should we have an endpoint sample or endpoints
commented to let the user uncomment what he wants.
For example, we can have:
<http:consumer .../>
<http:provider .../>
or
<!--
<http:consumer .../>
-->
<!--
<http:provider .../>
-->
and let the user uncomment and change the endpoint matching what he needs.
Any comment is welcome.
FYI, I will want some feedback to this discussion before resuming my
work on archetypes.
Regards
JB
Re: [DISCUSS] Archetypes structure and content
Posted by Corrado Campisano <co...@gmail.com>.
Hi,
from my point of view (SA developer), it's ok to have lesser archetypes to
maintain (1: no consumer/provider sub-archetypes) at the cost of having to
uncomment the consumer/provider elements in the xbean.xml before calling
mvn.
That's because I use a script to generate a SA skeleton and then do the
edits anyway on the xbean.xml.
Maybe those who'd like more automation (a mvn or eclipse plugin) would
prefer to have the sub-archetipes.
Regards,
Corrado Campisano
2010/8/13 Jean-Baptiste Onofré <jb...@nanthrax.net>
> Hi all,
>
> After a first archetype release vote, some discussions have involved on
> IRC.
>
> There is two points that have to be clarified:
>
> 1/ Archetypes and components
>
> Currently, we have one archetype per endpoint type. For example, we have
> one archetype to create a HTTP Consumer endpoint, one archetype to create a
> HTTP Provider endpoint, etc.
> I have homogenized all archetype in this way, splitting some like
> servicemix-mail-service-unit in servicemix-mail-poller-service-unit and
> servicemix-mail-sender-service-unit.
> Using this solution:
> - we have important number of archetypes (it's maybe not simple for user to
> pick up the right one)
> - each archetype provides a simple xbean corresponding exactly of the
> expected behavior (for example, the user will have a HTTP consumer endpoint
> and only this using servicemix-http-consumer-service-unit).
>
> We have another way to see archetypes: one archetype per component.
> In that case, we have only servicemix-http-service-unit.
> The xbean.xml contains all possible endpoints configuration.
>
> 2/ XBean content and documentation
>
> The archetypes provide a sample xbean with the endpoint configuration.
>
> A comment should be present just before the endpoint snippet:
>
> <!-- Endpoint description -->
> <component:endpoint ... />
>
> This comment could contain:
> - the URL of the component wiki page
> - a brief documentation on the endpoint: what the endpoint does, what the
> endpoint attributes.
>
> Another question is: should we have an endpoint sample or endpoints
> commented to let the user uncomment what he wants.
>
> For example, we can have:
>
> <http:consumer .../>
> <http:provider .../>
>
> or
>
> <!--
> <http:consumer .../>
> -->
> <!--
> <http:provider .../>
> -->
>
> and let the user uncomment and change the endpoint matching what he needs.
>
> Any comment is welcome.
>
> FYI, I will want some feedback to this discussion before resuming my work
> on archetypes.
>
> Regards
> JB
>
Re: [DISCUSS] Archetypes structure and content
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Hi Adrian,
Concerning the 2), +1 to remove the Apache License from the generated
project.
Regards
JB
On 08/13/2010 01:11 PM, Adrian Trenaman wrote:
> Nice one Lars.
>
> I remember when I was a beginner, and it's with these memories in mind
> that I have the following observations.
>
> 1) +1 on Archetypes that show how to do the common use-cases easily, and
> show all the options as well. However, if we're throwing in the optional
> stuff, then we *MUST* annotate with really clear comments that give the
> new user confidence to either (a) enable the feature or (b) confidently
> delete this fragment. I'm not kidding here: the number of times I've
> seen xbean files strewn with commented-out or left-in elements, which
> were left untouched because the developers weren't confident enough to
> do something about them. Let's encourage people to keep their
> configuration lean and mean and to the point.
>
> 2) I believe we should remove the Apache License from the
> archetype-generated files. The second somebody uses an archetype, they
> have created something for themselves, and consequently, they own the
> copyright and they own the license. Some users are afraid to take out
> the license (would that be legal?!), and then leave it in, which would
> errantly mean that they're releasing their code under ASL. I think it
> would be better to simply have a comment at the top of the file that
> says "This configuration file was generated by and Apache Licensed
> archetype. You can remove this comment if you like. Have fun.".
>
>
> Best,
> Ade.
>
> On 13/08/2010 11:33, Lars Heinemann wrote:
>> Hi,
>>
>> I think one archetype per component should be enough.
>> The selection of the archetype would be easy for users.
>>
>> Of course the documentation inside the xbean.xml should be more
>> complete that
>> users can decide which of the endpoint definitions inside that xbean
>> is the correct
>> one to use. Therefore we need to entend that a bit.
>>
>> Here is an example I would use for the servicemix-mail archetype. It
>> could be described
>> even more detailed but thats only a quickshot to get you an idea what
>> I am thinking of.
>>
>>
>> <?xml version="1.0" encoding="UTF-8"?>
>> <!--
>>
>> Licensed to the Apache Software Foundation (ASF) under one or more
>> contributor license agreements. See the NOTICE file distributed with
>> this work for additional information regarding copyright ownership.
>> The ASF licenses this file to You under the Apache License, Version
>> 2.0 (the "License"); you may not use this file except in compliance
>> with the License. You may obtain a copy of the License at
>>
>> http://www.apache.org/licenses/LICENSE-2.0 Unless required by
>> applicable law or agreed to in writing, software distributed under the
>> License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
>> CONDITIONS OF ANY KIND, either express or implied. See the License for
>> the specific language governing permissions and limitations under the
>> License.
>> -->
>> <beans xmlns="http://www.springframework.org/schema/beans"
>> xmlns:mail="http://servicemix.apache.org/mail/1.0"
>> xmlns:example="http://servicemix.apache.org/example"
>> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>> xsi:schemaLocation="http://servicemix.apache.org/mail/1.0
>> http://servicemix.apache.org/schema/servicemix-mail-2010.01.xsd
>> http://www.springframework.org/schema/beans
>> http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
>>
>> <!--
>>
>> This is a configuration for the servicemix-mail component. Below
>> you will find two sample endpoint definitions for polling and sending
>> emails. For a more complete documentation of both endpoint types
>> have a look at the servicemix.mail wiki page at:
>>
>> http://servicemix.apache.org/servicemix-mail
>> -->
>>
>> <!--
>> The following endpoint definition describes a polling process which
>> will connect to a specified email
>> account and polls emails in a specific polling interval. All
>> polled emails will be processed by the
>> default mail marshaler and sent to the specified target
>> service and endpoint. The debugging of the mail
>> api is currently switched off. If you experience problems with
>> the connection switch the debug mode on.
>> All polled messages are not deleted from the email account and
>> only new messages are processed.
>>
>> Attributes:
>> service : the service name of the mail poller
>> endpoint : the endpoint name of the mail poller
>> targetService : the name of the target service to send
>> messages to
>> targetEndpoint : the name of the target endpoint to
>> send messages to
>> period : the polling interval in millis
>> debugMode : switches the mail api debug mode on or off
>> connection : the connection string as
>> <protocol>://<username>@<mailserver>/<folder>?password=<password>
>> for more possibilities refer to the components wiki page at
>> http://servicemix.apache.org/servicemix-mail
>> deleteProcessedMessages : flag if processed messages
>> should be deleted from the mail server or not
>> processOnlyUnseenMessages : flag if only unread messages
>> should be processed (works only perfect with IMAP)
>>
>> It is also possible to define a custom marshaler which converts
>> the mails to a normalized message in a way you defined it. See the
>> components wiki page for how to do that.
>> -->
>>
>> <!--
>> <mail:poller service="example:serviceName"
>> endpoint="mail-poller"
>> targetService="example:targetServiceName"
>> targetEndpoint="targetEndpoint"
>> period="10000"
>> debugMode="false"
>> connection="imap://username@host/INBOX?password=mypass"
>> deleteProcessedMessages="false"
>> processOnlyUnseenMessages="true" />
>> -->
>>
>> <!--
>> The following endpoint definition describes a sender endpoint. All
>> incoming messages exchanges are converted to
>> mails via the default mail marshaler and sent using the
>> defined mail account. The sender of the email is specified
>> via the sender attribute but may be overridden by putting
>> specific properties to the normalized message. Same applies
>> for the receiver of the email specified by the receiver attribute.
>> The debugging of the mail api is currently
>> switched off. If you experience problems with the connection
>> switch the debug mode on.
>>
>> Attributes:
>> service : the service name of the mail poller
>> endpoint : the endpoint name of the mail poller
>> sender : the default sender of the mail
>> receiver : the default receiver of the mail
>> debugMode : switches the mail api debug mode on or off
>> connection : the connection string as
>> <protocol>://<username>@<mailserver>/<folder>?password=<password>
>> for more possibilities refer to the components wiki page at
>> http://servicemix.apache.org/servicemix-mail
>>
>> It is also possible to define a custom marshaler which converts
>> the mails to a normalized message in a way you defined it. See the
>> components wiki page for how to do that. There are also more
>> attributes described which are not that commonly used. Almost every
>> aspect of
>> the connection can be overridden by specifying special messages
>> properties. See the wiki for more information on that.
>> -->
>>
>> <!--
>> <mail:sender service="example:serviceName"
>> endpoint="mail-sender"
>> sender="no-reply@mycompany.com"
>> receiver="your-static-receiver-address@some-host.com"
>> debugMode="false"
>> connection="smtp://username@host?password=mypass" />
>> -->
>>
>> </beans>
>>
>>
>> Hope that helps in this discussion.
>> If I would be a new user I could very easy decide which endpoint to
>> use here and how to get started
>> with the most commons settings. For more unusual cases and more
>> complete docs the user can refer
>> to the links to the servicemix-mail wiki page. We could even link in
>> here some cookbook recipes for the
>> most common use cases. But thats an idea only for now.
>>
>> Regards
>> Lars
>>
>>
>>
>>
>> 2010/8/13 Ioannis Canellos<io...@gmail.com>:
>>> Here is a small analysis on why I believe that its better to keep
>>> archetypes
>>> per endpoint type.
>>>
>>> Below is a list of pros& cons for both cases *(archetypes per
>>> component and
>>> archetypes per endpoint type)*. This list is enriched with my personal
>>> experience as a newcomer.
>>> I hope you find this useful.
>>> *
>>> Archetype per Component Pros& Cons:*
>>> *
>>> Pros:*
>>>
>>> - Easier to maintain
>>> - Help the user realize that service units are per component and not per
>>> endpoint
>>> - Short archetype selection makes it easier for the newcomers to decide
>>> on what they need.
>>>
>>> *Cons:*
>>>
>>> - The output can intimidate newcomers.
>>> - The user will have to decide what he needs to remove from the
>>> generated
>>> xbean.xml.
>>> - The minimal required effort to create an endpoint is not clear
>>>
>>> *Archetype per Endpoint Type Pros& Cons:
>>>
>>> **Pros:*
>>>
>>> - Produce simpler output for newcomers.
>>> - The archetype clearly demonstrates how simple it is to create an
>>> endpoint *(with the minimal effort)*.
>>> - Promotes a development style which I consider a best practice *(spread
>>> the functionality in multiple SUs, I can provide further details on
>>> why)*
>>> .
>>>
>>> *Cons:*
>>>
>>> - Harder to maintain
>>> - The user has to decide what type of endpoint is required, before using
>>> the archetype.
>>>
>>> *Sharing my personal experience:*
>>> I have been using service mix for almost a year. I found the
>>> existence of
>>> archetypes per endpoint type to be useful. The first archetype I used
>>> was
>>> the archetype for the Http Consumer Endpoint. The output was the minimal
>>> possible and I was happy with it. Then I tried to use the EIP Service
>>> Unit
>>> archetype. The output was not that simple to understand *(it wasn't hard
>>> either but it required some reading)*, since I had to read all the
>>> comments
>>> in order to realize what I needed to keep and what I needed to discard.
>>>
>>> *Conclusion:*
>>> In my opinion, the only difference is "*what is more friendly to
>>> newcomers*".
>>> However, I believe that this is very important. Now days service mix is
>>> drawing attention and it draws users from different experience
>>> levels. This
>>> is why I believe that having archetypes per endpoint type serves best
>>> the
>>> interest of the community.
>>>
>>> On Fri, Aug 13, 2010 at 12:41 PM, Jean-Baptiste
>>> Onofré<jb...@nanthrax.net>wrote:
>>>
>>>> Hi all,
>>>>
>>>> After a first archetype release vote, some discussions have involved on
>>>> IRC.
>>>>
>>>> There is two points that have to be clarified:
>>>>
>>>> 1/ Archetypes and components
>>>>
>>>> Currently, we have one archetype per endpoint type. For example, we
>>>> have
>>>> one archetype to create a HTTP Consumer endpoint, one archetype to
>>>> create a
>>>> HTTP Provider endpoint, etc.
>>>> I have homogenized all archetype in this way, splitting some like
>>>> servicemix-mail-service-unit in servicemix-mail-poller-service-unit and
>>>> servicemix-mail-sender-service-unit.
>>>> Using this solution:
>>>> - we have important number of archetypes (it's maybe not simple for
>>>> user to
>>>> pick up the right one)
>>>> - each archetype provides a simple xbean corresponding exactly of the
>>>> expected behavior (for example, the user will have a HTTP consumer
>>>> endpoint
>>>> and only this using servicemix-http-consumer-service-unit).
>>>>
>>>> We have another way to see archetypes: one archetype per component.
>>>> In that case, we have only servicemix-http-service-unit.
>>>> The xbean.xml contains all possible endpoints configuration.
>>>>
>>>> 2/ XBean content and documentation
>>>>
>>>> The archetypes provide a sample xbean with the endpoint configuration.
>>>>
>>>> A comment should be present just before the endpoint snippet:
>>>>
>>>> <!-- Endpoint description -->
>>>> <component:endpoint ... />
>>>>
>>>> This comment could contain:
>>>> - the URL of the component wiki page
>>>> - a brief documentation on the endpoint: what the endpoint does,
>>>> what the
>>>> endpoint attributes.
>>>>
>>>> Another question is: should we have an endpoint sample or endpoints
>>>> commented to let the user uncomment what he wants.
>>>>
>>>> For example, we can have:
>>>>
>>>> <http:consumer .../>
>>>> <http:provider .../>
>>>>
>>>> or
>>>>
>>>> <!--
>>>> <http:consumer .../>
>>>> -->
>>>> <!--
>>>> <http:provider .../>
>>>> -->
>>>>
>>>> and let the user uncomment and change the endpoint matching what he
>>>> needs.
>>>>
>>>> Any comment is welcome.
>>>>
>>>> FYI, I will want some feedback to this discussion before resuming my
>>>> work
>>>> on archetypes.
>>>>
>>>> Regards
>>>> JB
>>>>
>>>
>>>
>>> --
>>> Ioannis D. Canellos
>>>
>>
>>
>> --
>> http://lhein.blogspot.com
Re: [DISCUSS] Archetypes structure and content
Posted by Geert Schuring <ge...@schuring.eu>.
+1 for removing the license. It's the first thing I remove every time I
use an archetype.
Geert.
> Nice one Lars.
>
> I remember when I was a beginner, and it's with these memories in mind
> that I have the following observations.
>
> 1) +1 on Archetypes that show how to do the common use-cases easily, and
> show all the options as well. However, if we're throwing in the optional
> stuff, then we *MUST* annotate with really clear comments that give the
> new user confidence to either (a) enable the feature or (b) confidently
> delete this fragment. I'm not kidding here: the number of times I've
> seen xbean files strewn with commented-out or left-in elements, which
> were left untouched because the developers weren't confident enough to
> do something about them. Let's encourage people to keep their
> configuration lean and mean and to the point.
>
> 2) I believe we should remove the Apache License from the
> archetype-generated files. The second somebody uses an archetype, they
> have created something for themselves, and consequently, they own the
> copyright and they own the license. Some users are afraid to take out
> the license (would that be legal?!), and then leave it in, which would
> errantly mean that they're releasing their code under ASL. I think it
> would be better to simply have a comment at the top of the file that
> says "This configuration file was generated by and Apache Licensed
> archetype. You can remove this comment if you like. Have fun.".
>
>
> Best,
> Ade.
>
> On 13/08/2010 11:33, Lars Heinemann wrote:
>> Hi,
>>
>> I think one archetype per component should be enough.
>> The selection of the archetype would be easy for users.
>>
>> Of course the documentation inside the xbean.xml should be more complete
>> that
>> users can decide which of the endpoint definitions inside that xbean
>> is the correct
>> one to use. Therefore we need to entend that a bit.
>>
>> Here is an example I would use for the servicemix-mail archetype. It
>> could be described
>> even more detailed but thats only a quickshot to get you an idea what
>> I am thinking of.
>>
>>
>> <?xml version="1.0" encoding="UTF-8"?>
>> <!--
>>
>> Licensed to the Apache Software Foundation (ASF) under one or
>> more
>> contributor license agreements. See the NOTICE file distributed
>> with
>> this work for additional information regarding copyright
>> ownership.
>> The ASF licenses this file to You under the Apache License,
>> Version
>> 2.0 (the "License"); you may not use this file except in
>> compliance
>> with the License. You may obtain a copy of the License at
>>
>> http://www.apache.org/licenses/LICENSE-2.0 Unless required by
>> applicable law or agreed to in writing, software distributed
>> under the
>> License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
>> OR
>> CONDITIONS OF ANY KIND, either express or implied. See the
>> License for
>> the specific language governing permissions and limitations
>> under the
>> License.
>> -->
>> <beans xmlns="http://www.springframework.org/schema/beans"
>> xmlns:mail="http://servicemix.apache.org/mail/1.0"
>> xmlns:example="http://servicemix.apache.org/example"
>> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>> xsi:schemaLocation="http://servicemix.apache.org/mail/1.0
>> http://servicemix.apache.org/schema/servicemix-mail-2010.01.xsd
>> http://www.springframework.org/schema/beans
>> http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
>>
>> <!--
>>
>> This is a configuration for the servicemix-mail component. Below
>> you will find two sample endpoint definitions for polling and sending
>> emails. For a more complete documentation of both endpoint types
>> have a look at the servicemix.mail wiki page at:
>>
>> http://servicemix.apache.org/servicemix-mail
>> -->
>>
>> <!--
>> The following endpoint definition describes a polling process
>> which
>> will connect to a specified email
>> account and polls emails in a specific polling interval. All
>> polled emails will be processed by the
>> default mail marshaler and sent to the specified target
>> service and endpoint. The debugging of the mail
>> api is currently switched off. If you experience problems with
>> the connection switch the debug mode on.
>> All polled messages are not deleted from the email account and
>> only new messages are processed.
>>
>> Attributes:
>> service : the service name of the mail
>> poller
>> endpoint : the endpoint name of the mail
>> poller
>> targetService : the name of the target
>> service to send
>> messages to
>> targetEndpoint : the name of the target
>> endpoint to
>> send messages to
>> period : the polling interval in
>> millis
>> debugMode : switches the mail api debug
>> mode on or off
>> connection : the connection string as
>> <protocol>://<username>@<mailserver>/<folder>?password=<password>
>> for more possibilities refer
>> to the components wiki page
>> at
>> http://servicemix.apache.org/servicemix-mail
>> deleteProcessedMessages : flag if processed messages
>> should be deleted from the mail server or not
>> processOnlyUnseenMessages : flag if only unread messages
>> should be processed (works only perfect with IMAP)
>>
>> It is also possible to define a custom marshaler which converts
>> the mails to a normalized message in a way you defined it. See the
>> components wiki page for how to do that.
>> -->
>>
>> <!--
>> <mail:poller service="example:serviceName"
>> endpoint="mail-poller"
>> targetService="example:targetServiceName"
>> targetEndpoint="targetEndpoint"
>> period="10000"
>> debugMode="false"
>> connection="imap://username@host/INBOX?password=mypass"
>> deleteProcessedMessages="false"
>> processOnlyUnseenMessages="true" />
>> -->
>>
>> <!--
>> The following endpoint definition describes a sender endpoint.
>> All
>> incoming messages exchanges are converted to
>> mails via the default mail marshaler and sent using the
>> defined mail account. The sender of the email is specified
>> via the sender attribute but may be overridden by putting
>> specific properties to the normalized message. Same applies
>> for the receiver of the email specified by the receiver
>> attribute.
>> The debugging of the mail api is currently
>> switched off. If you experience problems with the connection
>> switch the debug mode on.
>>
>> Attributes:
>> service : the service name of the mail
>> poller
>> endpoint : the endpoint name of the mail
>> poller
>> sender : the default sender of the
>> mail
>> receiver : the default receiver of the
>> mail
>> debugMode : switches the mail api debug
>> mode on or off
>> connection : the connection string as
>> <protocol>://<username>@<mailserver>/<folder>?password=<password>
>> for more possibilities refer
>> to the components wiki page
>> at
>> http://servicemix.apache.org/servicemix-mail
>>
>> It is also possible to define a custom marshaler which converts
>> the mails to a normalized message in a way you defined it. See the
>> components wiki page for how to do that. There are also more
>> attributes described which are not that commonly used. Almost every
>> aspect of
>> the connection can be overridden by specifying special messages
>> properties. See the wiki for more information on that.
>> -->
>>
>> <!--
>> <mail:sender service="example:serviceName"
>> endpoint="mail-sender"
>> sender="no-reply@mycompany.com"
>> receiver="your-static-receiver-address@some-host.com"
>> debugMode="false"
>> connection="smtp://username@host?password=mypass"
>> />
>> -->
>>
>> </beans>
>>
>>
>> Hope that helps in this discussion.
>> If I would be a new user I could very easy decide which endpoint to
>> use here and how to get started
>> with the most commons settings. For more unusual cases and more
>> complete docs the user can refer
>> to the links to the servicemix-mail wiki page. We could even link in
>> here some cookbook recipes for the
>> most common use cases. But thats an idea only for now.
>>
>> Regards
>> Lars
>>
>>
>>
>>
>> 2010/8/13 Ioannis Canellos<io...@gmail.com>:
>>
>>> Here is a small analysis on why I believe that its better to keep
>>> archetypes
>>> per endpoint type.
>>>
>>> Below is a list of pros& cons for both cases *(archetypes per
>>> component and
>>> archetypes per endpoint type)*. This list is enriched with my personal
>>> experience as a newcomer.
>>> I hope you find this useful.
>>> *
>>> Archetype per Component Pros& Cons:*
>>> *
>>> Pros:*
>>>
>>> - Easier to maintain
>>> - Help the user realize that service units are per component and not
>>> per
>>> endpoint
>>> - Short archetype selection makes it easier for the newcomers to
>>> decide
>>> on what they need.
>>>
>>> *Cons:*
>>>
>>> - The output can intimidate newcomers.
>>> - The user will have to decide what he needs to remove from the
>>> generated
>>> xbean.xml.
>>> - The minimal required effort to create an endpoint is not clear
>>>
>>> *Archetype per Endpoint Type Pros& Cons:
>>>
>>> **Pros:*
>>>
>>> - Produce simpler output for newcomers.
>>> - The archetype clearly demonstrates how simple it is to create an
>>> endpoint *(with the minimal effort)*.
>>> - Promotes a development style which I consider a best practice
>>> *(spread
>>> the functionality in multiple SUs, I can provide further details on
>>> why)*
>>> .
>>>
>>> *Cons:*
>>>
>>> - Harder to maintain
>>> - The user has to decide what type of endpoint is required, before
>>> using
>>> the archetype.
>>>
>>> *Sharing my personal experience:*
>>> I have been using service mix for almost a year. I found the existence
>>> of
>>> archetypes per endpoint type to be useful. The first archetype I used
>>> was
>>> the archetype for the Http Consumer Endpoint. The output was the
>>> minimal
>>> possible and I was happy with it. Then I tried to use the EIP Service
>>> Unit
>>> archetype. The output was not that simple to understand *(it wasn't
>>> hard
>>> either but it required some reading)*, since I had to read all the
>>> comments
>>> in order to realize what I needed to keep and what I needed to discard.
>>>
>>> *Conclusion:*
>>> In my opinion, the only difference is "*what is more friendly to
>>> newcomers*".
>>> However, I believe that this is very important. Now days service mix is
>>> drawing attention and it draws users from different experience levels.
>>> This
>>> is why I believe that having archetypes per endpoint type serves best
>>> the
>>> interest of the community.
>>>
>>> On Fri, Aug 13, 2010 at 12:41 PM, Jean-Baptiste
>>> Onofré<jb...@nanthrax.net>wrote:
>>>
>>>
>>>> Hi all,
>>>>
>>>> After a first archetype release vote, some discussions have involved
>>>> on
>>>> IRC.
>>>>
>>>> There is two points that have to be clarified:
>>>>
>>>> 1/ Archetypes and components
>>>>
>>>> Currently, we have one archetype per endpoint type. For example, we
>>>> have
>>>> one archetype to create a HTTP Consumer endpoint, one archetype to
>>>> create a
>>>> HTTP Provider endpoint, etc.
>>>> I have homogenized all archetype in this way, splitting some like
>>>> servicemix-mail-service-unit in servicemix-mail-poller-service-unit
>>>> and
>>>> servicemix-mail-sender-service-unit.
>>>> Using this solution:
>>>> - we have important number of archetypes (it's maybe not simple for
>>>> user to
>>>> pick up the right one)
>>>> - each archetype provides a simple xbean corresponding exactly of the
>>>> expected behavior (for example, the user will have a HTTP consumer
>>>> endpoint
>>>> and only this using servicemix-http-consumer-service-unit).
>>>>
>>>> We have another way to see archetypes: one archetype per component.
>>>> In that case, we have only servicemix-http-service-unit.
>>>> The xbean.xml contains all possible endpoints configuration.
>>>>
>>>> 2/ XBean content and documentation
>>>>
>>>> The archetypes provide a sample xbean with the endpoint configuration.
>>>>
>>>> A comment should be present just before the endpoint snippet:
>>>>
>>>> <!-- Endpoint description -->
>>>> <component:endpoint ... />
>>>>
>>>> This comment could contain:
>>>> - the URL of the component wiki page
>>>> - a brief documentation on the endpoint: what the endpoint does, what
>>>> the
>>>> endpoint attributes.
>>>>
>>>> Another question is: should we have an endpoint sample or endpoints
>>>> commented to let the user uncomment what he wants.
>>>>
>>>> For example, we can have:
>>>>
>>>> <http:consumer .../>
>>>> <http:provider .../>
>>>>
>>>> or
>>>>
>>>> <!--
>>>> <http:consumer .../>
>>>> -->
>>>> <!--
>>>> <http:provider .../>
>>>> -->
>>>>
>>>> and let the user uncomment and change the endpoint matching what he
>>>> needs.
>>>>
>>>> Any comment is welcome.
>>>>
>>>> FYI, I will want some feedback to this discussion before resuming my
>>>> work
>>>> on archetypes.
>>>>
>>>> Regards
>>>> JB
>>>>
>>>>
>>>
>>>
>>> --
>>> Ioannis D. Canellos
>>>
>>>
>>
>>
>> --
>> http://lhein.blogspot.com
>>
>
>
>
Re: [DISCUSS] Archetypes structure and content
Posted by Adrian Trenaman <tr...@progress.com>.
Nice one Lars.
I remember when I was a beginner, and it's with these memories in mind
that I have the following observations.
1) +1 on Archetypes that show how to do the common use-cases easily, and
show all the options as well. However, if we're throwing in the optional
stuff, then we *MUST* annotate with really clear comments that give the
new user confidence to either (a) enable the feature or (b) confidently
delete this fragment. I'm not kidding here: the number of times I've
seen xbean files strewn with commented-out or left-in elements, which
were left untouched because the developers weren't confident enough to
do something about them. Let's encourage people to keep their
configuration lean and mean and to the point.
2) I believe we should remove the Apache License from the
archetype-generated files. The second somebody uses an archetype, they
have created something for themselves, and consequently, they own the
copyright and they own the license. Some users are afraid to take out
the license (would that be legal?!), and then leave it in, which would
errantly mean that they're releasing their code under ASL. I think it
would be better to simply have a comment at the top of the file that
says "This configuration file was generated by and Apache Licensed
archetype. You can remove this comment if you like. Have fun.".
Best,
Ade.
On 13/08/2010 11:33, Lars Heinemann wrote:
> Hi,
>
> I think one archetype per component should be enough.
> The selection of the archetype would be easy for users.
>
> Of course the documentation inside the xbean.xml should be more complete that
> users can decide which of the endpoint definitions inside that xbean
> is the correct
> one to use. Therefore we need to entend that a bit.
>
> Here is an example I would use for the servicemix-mail archetype. It
> could be described
> even more detailed but thats only a quickshot to get you an idea what
> I am thinking of.
>
>
> <?xml version="1.0" encoding="UTF-8"?>
> <!--
>
> Licensed to the Apache Software Foundation (ASF) under one or more
> contributor license agreements. See the NOTICE file distributed with
> this work for additional information regarding copyright ownership.
> The ASF licenses this file to You under the Apache License, Version
> 2.0 (the "License"); you may not use this file except in compliance
> with the License. You may obtain a copy of the License at
>
> http://www.apache.org/licenses/LICENSE-2.0 Unless required by
> applicable law or agreed to in writing, software distributed under the
> License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
> CONDITIONS OF ANY KIND, either express or implied. See the License for
> the specific language governing permissions and limitations under the
> License.
> -->
> <beans xmlns="http://www.springframework.org/schema/beans"
> xmlns:mail="http://servicemix.apache.org/mail/1.0"
> xmlns:example="http://servicemix.apache.org/example"
> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
> xsi:schemaLocation="http://servicemix.apache.org/mail/1.0
> http://servicemix.apache.org/schema/servicemix-mail-2010.01.xsd
> http://www.springframework.org/schema/beans
> http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
>
> <!--
>
> This is a configuration for the servicemix-mail component. Below
> you will find two sample endpoint definitions for polling and sending
> emails. For a more complete documentation of both endpoint types
> have a look at the servicemix.mail wiki page at:
>
> http://servicemix.apache.org/servicemix-mail
> -->
>
> <!--
> The following endpoint definition describes a polling process which
> will connect to a specified email
> account and polls emails in a specific polling interval. All
> polled emails will be processed by the
> default mail marshaler and sent to the specified target
> service and endpoint. The debugging of the mail
> api is currently switched off. If you experience problems with
> the connection switch the debug mode on.
> All polled messages are not deleted from the email account and
> only new messages are processed.
>
> Attributes:
> service : the service name of the mail poller
> endpoint : the endpoint name of the mail poller
> targetService : the name of the target service to send
> messages to
> targetEndpoint : the name of the target endpoint to
> send messages to
> period : the polling interval in millis
> debugMode : switches the mail api debug mode on or off
> connection : the connection string as
> <protocol>://<username>@<mailserver>/<folder>?password=<password>
> for more possibilities refer to the components wiki page at
> http://servicemix.apache.org/servicemix-mail
> deleteProcessedMessages : flag if processed messages
> should be deleted from the mail server or not
> processOnlyUnseenMessages : flag if only unread messages
> should be processed (works only perfect with IMAP)
>
> It is also possible to define a custom marshaler which converts
> the mails to a normalized message in a way you defined it. See the
> components wiki page for how to do that.
> -->
>
> <!--
> <mail:poller service="example:serviceName"
> endpoint="mail-poller"
> targetService="example:targetServiceName"
> targetEndpoint="targetEndpoint"
> period="10000"
> debugMode="false"
> connection="imap://username@host/INBOX?password=mypass"
> deleteProcessedMessages="false"
> processOnlyUnseenMessages="true" />
> -->
>
> <!--
> The following endpoint definition describes a sender endpoint. All
> incoming messages exchanges are converted to
> mails via the default mail marshaler and sent using the
> defined mail account. The sender of the email is specified
> via the sender attribute but may be overridden by putting
> specific properties to the normalized message. Same applies
> for the receiver of the email specified by the receiver attribute.
> The debugging of the mail api is currently
> switched off. If you experience problems with the connection
> switch the debug mode on.
>
> Attributes:
> service : the service name of the mail poller
> endpoint : the endpoint name of the mail poller
> sender : the default sender of the mail
> receiver : the default receiver of the mail
> debugMode : switches the mail api debug mode on or off
> connection : the connection string as
> <protocol>://<username>@<mailserver>/<folder>?password=<password>
> for more possibilities refer to the components wiki page at
> http://servicemix.apache.org/servicemix-mail
>
> It is also possible to define a custom marshaler which converts
> the mails to a normalized message in a way you defined it. See the
> components wiki page for how to do that. There are also more
> attributes described which are not that commonly used. Almost every
> aspect of
> the connection can be overridden by specifying special messages
> properties. See the wiki for more information on that.
> -->
>
> <!--
> <mail:sender service="example:serviceName"
> endpoint="mail-sender"
> sender="no-reply@mycompany.com"
> receiver="your-static-receiver-address@some-host.com"
> debugMode="false"
> connection="smtp://username@host?password=mypass" />
> -->
>
> </beans>
>
>
> Hope that helps in this discussion.
> If I would be a new user I could very easy decide which endpoint to
> use here and how to get started
> with the most commons settings. For more unusual cases and more
> complete docs the user can refer
> to the links to the servicemix-mail wiki page. We could even link in
> here some cookbook recipes for the
> most common use cases. But thats an idea only for now.
>
> Regards
> Lars
>
>
>
>
> 2010/8/13 Ioannis Canellos<io...@gmail.com>:
>
>> Here is a small analysis on why I believe that its better to keep archetypes
>> per endpoint type.
>>
>> Below is a list of pros& cons for both cases *(archetypes per component and
>> archetypes per endpoint type)*. This list is enriched with my personal
>> experience as a newcomer.
>> I hope you find this useful.
>> *
>> Archetype per Component Pros& Cons:*
>> *
>> Pros:*
>>
>> - Easier to maintain
>> - Help the user realize that service units are per component and not per
>> endpoint
>> - Short archetype selection makes it easier for the newcomers to decide
>> on what they need.
>>
>> *Cons:*
>>
>> - The output can intimidate newcomers.
>> - The user will have to decide what he needs to remove from the generated
>> xbean.xml.
>> - The minimal required effort to create an endpoint is not clear
>>
>> *Archetype per Endpoint Type Pros& Cons:
>>
>> **Pros:*
>>
>> - Produce simpler output for newcomers.
>> - The archetype clearly demonstrates how simple it is to create an
>> endpoint *(with the minimal effort)*.
>> - Promotes a development style which I consider a best practice *(spread
>> the functionality in multiple SUs, I can provide further details on why)*
>> .
>>
>> *Cons:*
>>
>> - Harder to maintain
>> - The user has to decide what type of endpoint is required, before using
>> the archetype.
>>
>> *Sharing my personal experience:*
>> I have been using service mix for almost a year. I found the existence of
>> archetypes per endpoint type to be useful. The first archetype I used was
>> the archetype for the Http Consumer Endpoint. The output was the minimal
>> possible and I was happy with it. Then I tried to use the EIP Service Unit
>> archetype. The output was not that simple to understand *(it wasn't hard
>> either but it required some reading)*, since I had to read all the comments
>> in order to realize what I needed to keep and what I needed to discard.
>>
>> *Conclusion:*
>> In my opinion, the only difference is "*what is more friendly to newcomers*".
>> However, I believe that this is very important. Now days service mix is
>> drawing attention and it draws users from different experience levels. This
>> is why I believe that having archetypes per endpoint type serves best the
>> interest of the community.
>>
>> On Fri, Aug 13, 2010 at 12:41 PM, Jean-Baptiste Onofré<jb...@nanthrax.net>wrote:
>>
>>
>>> Hi all,
>>>
>>> After a first archetype release vote, some discussions have involved on
>>> IRC.
>>>
>>> There is two points that have to be clarified:
>>>
>>> 1/ Archetypes and components
>>>
>>> Currently, we have one archetype per endpoint type. For example, we have
>>> one archetype to create a HTTP Consumer endpoint, one archetype to create a
>>> HTTP Provider endpoint, etc.
>>> I have homogenized all archetype in this way, splitting some like
>>> servicemix-mail-service-unit in servicemix-mail-poller-service-unit and
>>> servicemix-mail-sender-service-unit.
>>> Using this solution:
>>> - we have important number of archetypes (it's maybe not simple for user to
>>> pick up the right one)
>>> - each archetype provides a simple xbean corresponding exactly of the
>>> expected behavior (for example, the user will have a HTTP consumer endpoint
>>> and only this using servicemix-http-consumer-service-unit).
>>>
>>> We have another way to see archetypes: one archetype per component.
>>> In that case, we have only servicemix-http-service-unit.
>>> The xbean.xml contains all possible endpoints configuration.
>>>
>>> 2/ XBean content and documentation
>>>
>>> The archetypes provide a sample xbean with the endpoint configuration.
>>>
>>> A comment should be present just before the endpoint snippet:
>>>
>>> <!-- Endpoint description -->
>>> <component:endpoint ... />
>>>
>>> This comment could contain:
>>> - the URL of the component wiki page
>>> - a brief documentation on the endpoint: what the endpoint does, what the
>>> endpoint attributes.
>>>
>>> Another question is: should we have an endpoint sample or endpoints
>>> commented to let the user uncomment what he wants.
>>>
>>> For example, we can have:
>>>
>>> <http:consumer .../>
>>> <http:provider .../>
>>>
>>> or
>>>
>>> <!--
>>> <http:consumer .../>
>>> -->
>>> <!--
>>> <http:provider .../>
>>> -->
>>>
>>> and let the user uncomment and change the endpoint matching what he needs.
>>>
>>> Any comment is welcome.
>>>
>>> FYI, I will want some feedback to this discussion before resuming my work
>>> on archetypes.
>>>
>>> Regards
>>> JB
>>>
>>>
>>
>>
>> --
>> Ioannis D. Canellos
>>
>>
>
>
> --
> http://lhein.blogspot.com
>
Re: [DISCUSS] Archetypes structure and content
Posted by Lars Heinemann <lh...@apache.org>.
Hi,
I think one archetype per component should be enough.
The selection of the archetype would be easy for users.
Of course the documentation inside the xbean.xml should be more complete that
users can decide which of the endpoint definitions inside that xbean
is the correct
one to use. Therefore we need to entend that a bit.
Here is an example I would use for the servicemix-mail archetype. It
could be described
even more detailed but thats only a quickshot to get you an idea what
I am thinking of.
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version
2.0 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by
applicable law or agreed to in writing, software distributed under the
License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for
the specific language governing permissions and limitations under the
License.
-->
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:mail="http://servicemix.apache.org/mail/1.0"
xmlns:example="http://servicemix.apache.org/example"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://servicemix.apache.org/mail/1.0
http://servicemix.apache.org/schema/servicemix-mail-2010.01.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
<!--
This is a configuration for the servicemix-mail component. Below
you will find two sample endpoint definitions for polling and sending
emails. For a more complete documentation of both endpoint types
have a look at the servicemix.mail wiki page at:
http://servicemix.apache.org/servicemix-mail
-->
<!--
The following endpoint definition describes a polling process which
will connect to a specified email
account and polls emails in a specific polling interval. All
polled emails will be processed by the
default mail marshaler and sent to the specified target
service and endpoint. The debugging of the mail
api is currently switched off. If you experience problems with
the connection switch the debug mode on.
All polled messages are not deleted from the email account and
only new messages are processed.
Attributes:
service : the service name of the mail poller
endpoint : the endpoint name of the mail poller
targetService : the name of the target service to send
messages to
targetEndpoint : the name of the target endpoint to
send messages to
period : the polling interval in millis
debugMode : switches the mail api debug mode on or off
connection : the connection string as
<protocol>://<username>@<mailserver>/<folder>?password=<password>
for more possibilities refer to the components wiki page at
http://servicemix.apache.org/servicemix-mail
deleteProcessedMessages : flag if processed messages
should be deleted from the mail server or not
processOnlyUnseenMessages : flag if only unread messages
should be processed (works only perfect with IMAP)
It is also possible to define a custom marshaler which converts
the mails to a normalized message in a way you defined it. See the
components wiki page for how to do that.
-->
<!--
<mail:poller service="example:serviceName"
endpoint="mail-poller"
targetService="example:targetServiceName"
targetEndpoint="targetEndpoint"
period="10000"
debugMode="false"
connection="imap://username@host/INBOX?password=mypass"
deleteProcessedMessages="false"
processOnlyUnseenMessages="true" />
-->
<!--
The following endpoint definition describes a sender endpoint. All
incoming messages exchanges are converted to
mails via the default mail marshaler and sent using the
defined mail account. The sender of the email is specified
via the sender attribute but may be overridden by putting
specific properties to the normalized message. Same applies
for the receiver of the email specified by the receiver attribute.
The debugging of the mail api is currently
switched off. If you experience problems with the connection
switch the debug mode on.
Attributes:
service : the service name of the mail poller
endpoint : the endpoint name of the mail poller
sender : the default sender of the mail
receiver : the default receiver of the mail
debugMode : switches the mail api debug mode on or off
connection : the connection string as
<protocol>://<username>@<mailserver>/<folder>?password=<password>
for more possibilities refer to the components wiki page at
http://servicemix.apache.org/servicemix-mail
It is also possible to define a custom marshaler which converts
the mails to a normalized message in a way you defined it. See the
components wiki page for how to do that. There are also more
attributes described which are not that commonly used. Almost every
aspect of
the connection can be overridden by specifying special messages
properties. See the wiki for more information on that.
-->
<!--
<mail:sender service="example:serviceName"
endpoint="mail-sender"
sender="no-reply@mycompany.com"
receiver="your-static-receiver-address@some-host.com"
debugMode="false"
connection="smtp://username@host?password=mypass" />
-->
</beans>
Hope that helps in this discussion.
If I would be a new user I could very easy decide which endpoint to
use here and how to get started
with the most commons settings. For more unusual cases and more
complete docs the user can refer
to the links to the servicemix-mail wiki page. We could even link in
here some cookbook recipes for the
most common use cases. But thats an idea only for now.
Regards
Lars
2010/8/13 Ioannis Canellos <io...@gmail.com>:
> Here is a small analysis on why I believe that its better to keep archetypes
> per endpoint type.
>
> Below is a list of pros & cons for both cases *(archetypes per component and
> archetypes per endpoint type)*. This list is enriched with my personal
> experience as a newcomer.
> I hope you find this useful.
> *
> Archetype per Component Pros & Cons:*
> *
> Pros:*
>
> - Easier to maintain
> - Help the user realize that service units are per component and not per
> endpoint
> - Short archetype selection makes it easier for the newcomers to decide
> on what they need.
>
> *Cons:*
>
> - The output can intimidate newcomers.
> - The user will have to decide what he needs to remove from the generated
> xbean.xml.
> - The minimal required effort to create an endpoint is not clear
>
> *Archetype per Endpoint Type Pros & Cons:
>
> **Pros:*
>
> - Produce simpler output for newcomers.
> - The archetype clearly demonstrates how simple it is to create an
> endpoint *(with the minimal effort)*.
> - Promotes a development style which I consider a best practice *(spread
> the functionality in multiple SUs, I can provide further details on why)*
> .
>
> *Cons:*
>
> - Harder to maintain
> - The user has to decide what type of endpoint is required, before using
> the archetype.
>
> *Sharing my personal experience:*
> I have been using service mix for almost a year. I found the existence of
> archetypes per endpoint type to be useful. The first archetype I used was
> the archetype for the Http Consumer Endpoint. The output was the minimal
> possible and I was happy with it. Then I tried to use the EIP Service Unit
> archetype. The output was not that simple to understand *(it wasn't hard
> either but it required some reading)*, since I had to read all the comments
> in order to realize what I needed to keep and what I needed to discard.
>
> *Conclusion:*
> In my opinion, the only difference is "*what is more friendly to newcomers*".
> However, I believe that this is very important. Now days service mix is
> drawing attention and it draws users from different experience levels. This
> is why I believe that having archetypes per endpoint type serves best the
> interest of the community.
>
> On Fri, Aug 13, 2010 at 12:41 PM, Jean-Baptiste Onofré <jb...@nanthrax.net>wrote:
>
>> Hi all,
>>
>> After a first archetype release vote, some discussions have involved on
>> IRC.
>>
>> There is two points that have to be clarified:
>>
>> 1/ Archetypes and components
>>
>> Currently, we have one archetype per endpoint type. For example, we have
>> one archetype to create a HTTP Consumer endpoint, one archetype to create a
>> HTTP Provider endpoint, etc.
>> I have homogenized all archetype in this way, splitting some like
>> servicemix-mail-service-unit in servicemix-mail-poller-service-unit and
>> servicemix-mail-sender-service-unit.
>> Using this solution:
>> - we have important number of archetypes (it's maybe not simple for user to
>> pick up the right one)
>> - each archetype provides a simple xbean corresponding exactly of the
>> expected behavior (for example, the user will have a HTTP consumer endpoint
>> and only this using servicemix-http-consumer-service-unit).
>>
>> We have another way to see archetypes: one archetype per component.
>> In that case, we have only servicemix-http-service-unit.
>> The xbean.xml contains all possible endpoints configuration.
>>
>> 2/ XBean content and documentation
>>
>> The archetypes provide a sample xbean with the endpoint configuration.
>>
>> A comment should be present just before the endpoint snippet:
>>
>> <!-- Endpoint description -->
>> <component:endpoint ... />
>>
>> This comment could contain:
>> - the URL of the component wiki page
>> - a brief documentation on the endpoint: what the endpoint does, what the
>> endpoint attributes.
>>
>> Another question is: should we have an endpoint sample or endpoints
>> commented to let the user uncomment what he wants.
>>
>> For example, we can have:
>>
>> <http:consumer .../>
>> <http:provider .../>
>>
>> or
>>
>> <!--
>> <http:consumer .../>
>> -->
>> <!--
>> <http:provider .../>
>> -->
>>
>> and let the user uncomment and change the endpoint matching what he needs.
>>
>> Any comment is welcome.
>>
>> FYI, I will want some feedback to this discussion before resuming my work
>> on archetypes.
>>
>> Regards
>> JB
>>
>
>
>
> --
> Ioannis D. Canellos
>
--
http://lhein.blogspot.com
Re: [DISCUSS] Archetypes structure and content
Posted by Ioannis Canellos <io...@gmail.com>.
Here is a small analysis on why I believe that its better to keep archetypes
per endpoint type.
Below is a list of pros & cons for both cases *(archetypes per component and
archetypes per endpoint type)*. This list is enriched with my personal
experience as a newcomer.
I hope you find this useful.
*
Archetype per Component Pros & Cons:*
*
Pros:*
- Easier to maintain
- Help the user realize that service units are per component and not per
endpoint
- Short archetype selection makes it easier for the newcomers to decide
on what they need.
*Cons:*
- The output can intimidate newcomers.
- The user will have to decide what he needs to remove from the generated
xbean.xml.
- The minimal required effort to create an endpoint is not clear
*Archetype per Endpoint Type Pros & Cons:
**Pros:*
- Produce simpler output for newcomers.
- The archetype clearly demonstrates how simple it is to create an
endpoint *(with the minimal effort)*.
- Promotes a development style which I consider a best practice *(spread
the functionality in multiple SUs, I can provide further details on why)*
.
*Cons:*
- Harder to maintain
- The user has to decide what type of endpoint is required, before using
the archetype.
*Sharing my personal experience:*
I have been using service mix for almost a year. I found the existence of
archetypes per endpoint type to be useful. The first archetype I used was
the archetype for the Http Consumer Endpoint. The output was the minimal
possible and I was happy with it. Then I tried to use the EIP Service Unit
archetype. The output was not that simple to understand *(it wasn't hard
either but it required some reading)*, since I had to read all the comments
in order to realize what I needed to keep and what I needed to discard.
*Conclusion:*
In my opinion, the only difference is "*what is more friendly to newcomers*".
However, I believe that this is very important. Now days service mix is
drawing attention and it draws users from different experience levels. This
is why I believe that having archetypes per endpoint type serves best the
interest of the community.
On Fri, Aug 13, 2010 at 12:41 PM, Jean-Baptiste Onofré <jb...@nanthrax.net>wrote:
> Hi all,
>
> After a first archetype release vote, some discussions have involved on
> IRC.
>
> There is two points that have to be clarified:
>
> 1/ Archetypes and components
>
> Currently, we have one archetype per endpoint type. For example, we have
> one archetype to create a HTTP Consumer endpoint, one archetype to create a
> HTTP Provider endpoint, etc.
> I have homogenized all archetype in this way, splitting some like
> servicemix-mail-service-unit in servicemix-mail-poller-service-unit and
> servicemix-mail-sender-service-unit.
> Using this solution:
> - we have important number of archetypes (it's maybe not simple for user to
> pick up the right one)
> - each archetype provides a simple xbean corresponding exactly of the
> expected behavior (for example, the user will have a HTTP consumer endpoint
> and only this using servicemix-http-consumer-service-unit).
>
> We have another way to see archetypes: one archetype per component.
> In that case, we have only servicemix-http-service-unit.
> The xbean.xml contains all possible endpoints configuration.
>
> 2/ XBean content and documentation
>
> The archetypes provide a sample xbean with the endpoint configuration.
>
> A comment should be present just before the endpoint snippet:
>
> <!-- Endpoint description -->
> <component:endpoint ... />
>
> This comment could contain:
> - the URL of the component wiki page
> - a brief documentation on the endpoint: what the endpoint does, what the
> endpoint attributes.
>
> Another question is: should we have an endpoint sample or endpoints
> commented to let the user uncomment what he wants.
>
> For example, we can have:
>
> <http:consumer .../>
> <http:provider .../>
>
> or
>
> <!--
> <http:consumer .../>
> -->
> <!--
> <http:provider .../>
> -->
>
> and let the user uncomment and change the endpoint matching what he needs.
>
> Any comment is welcome.
>
> FYI, I will want some feedback to this discussion before resuming my work
> on archetypes.
>
> Regards
> JB
>
--
Ioannis D. Canellos