+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://usern...@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-re...@mycompany.com" >> receiver="your-static-receiver-addr...@some-host.com" >> debugMode="false" >> connection="smtp://usern...@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<ioca...@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é<j...@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 >> > > >
