 ------
 How to use Bobber Archetypes 
 ------

Overview

  Maven 2 introduced the concept of archetypes which allow a developer to create maven project templates that could be invoked by a developer to create a new
  project instance. The ability to create maven templates promotes project standardization and expedites maven project developement by automatically generating
  boilerplate code. The archetype functionality uses the Velocity templating engine to generate the POM file.
  
  There are a few limitations with the new archetype functionality. First only the POM file is processed as a velocity template. Second only four system 
  properties are passed into the Velocity engine so one those four variables may be used in templates. Also although archetype-resource files are included
  in an archetype generated by the default archetype plugin only those files listed in the archetype descriptor are extracted when an archetype is created.
  Finally the default archetype support does not allow for template renaming which could be used to change the package/directory structure of generated archetype Java files.
  
  The Bobber archetype plugin attempts to address those limitations by redefining the archetype descriptor and implementation. The Bobber archetype plugin
  uses a new descriptor file that defines all the template variables the archetype uses along with default values. When an archetype is created and interactive mode
  is enabled in the maven 2 settings the values for the variables will be prompted to the maven user, the default being either the system property value set on
  the command line or the default value from the archetype descriptor. The second section of the archetype descriptor
  contains velocity template paths in the archetype and the paths that the generated output is to be stored. The Bobber archetype extracts all files from the archetype except for the
  archetype resources file and Velocity template files that end with .vm to the file sytem in addition to the processed templates. 
  
  
Using the Bobber Archetype

  
  
  
  
* Install Bobber

** Configuring Maven

  Add Bobber to the pluginGroup portion of the ~/.m2/settings.xml . If this file does not exist, create it with the following values:
  
-------------------------------------------------
  <settings>
  <pluginGroups>
    <pluginGroup>com.javaforge.bobber</pluginGroup>
  </pluginGroups>
  </settings>
-------------------------------------------------
  
  The global settings.xml is located in the maven 2 installation directory under conf.
  
  next add the Bobber plugin repository the to ~/.m2/settings.xml or $MAVEN_HOME/conf/settings.xml for setting it globally:
  
-------------------------------------------------
    <settings>
    <pluginGroups>
      <pluginGroup>com.javaforge.bobber</pluginGroup>
    </pluginGroups>
    <pluginRepositories>
       <pluginRepository>
         <id>mortbay-repo</id>
         <name>mortbay-repo</name>
         <url>http://SOMEURL GOES HERE</url>
       </pluginRepository>
     </pluginRepositories>

    </settings>
    
-------------------------------------------------


  Once the environment is set one can create an archetype. Use the exact same procedure as creating a default maven archetype except
  use the new format for the archetype descriptor. The following variables are required for archetype generation, just as in the default 
  archetype plugin.
  
-------------------------------------------------
  package
  packageName
  groupId
  artifactId
  version
-------------------------------------------------
  
  If package is not set with a value then groupid is used. packagePath is a computed value based on the package converting the . to / that is also available
  to vm templates in addition to the variables above. Additional variables that are used by templates must be declared in the archetype descriptor.
  
------------------------------------------------------------------------------------------------------------------
   ...
      <variables>
        <variable>
          <name>ComponentName</name>
          <description>JBI Component Name</description>
          <defvalue>JBI</defvalue>
        </variable>
      <variables>
      
   ...
------------------------------------------------------------------------------------------------------------------
  
  The name is the name used in the templates. If maven interactive mode is enabled it is also displayed along with the description on the terminal when 
  the value for the variable is prompted for. The defvalue is the default value to use if a value is not specified on the command line. Currently the element
  does not support Velocity ML.
  
  
  Use the extension .vm for all velocity templates in the archetype. Make sure to add
  new Template entries in the archetype descriptor for the templates, using the location in the archeype as the file element and the new location
  in the generated POM as the output element. The output can be a static string or a Velocity ML string that will be proccessed by the Velocity engine, ie.
  
  For file /archetype-resources/src/main/java/MyClass.vm
  
  specifying a archetype descriptor:
  
------------------------------------------------------------------------------------------------------------------
  <archetype>
    <id>my project</id>
    <variables>
      <variable>
        <name>aVariable</name>
        <description>a variable used in a Velocity template</description>
        <defvalue>aValue</defvalue>
      </variable>
      </variables>
    <templates>
      <template>
        <file>src\main\java\MyClass.vm</file>
        <output>boot\src\main\java\\${packagePath}\\${aVariable}.java</output>
      </template>
    </templates>
</archetype>
  
------------------------------------------------------------------------------------------------------------------
  
  To create an archtype, use the following syntax, the same as the default archetype:create plugin :
  
------------------------------------------------------------------------------------------------------------------
  mvn bobber-archetype:create -DarchetypeGroupId=com.javaforge.bobber -DarchetypeArtifactId=maven-archetype-jbi-component \ 
  -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=org.bobber.test -DartifactId=SPML
------------------------------------------------------------------------------------------------------------------

One can disable interactive mode by setting the flag (lookup flag) or set new values for variables defined in the archetype descriptor by
setting the values on the command line:

------------------------------------------------------------------------------------------------------------------
  mvn bobber-archetype:create -B -DarchetypeGroupId=com.javaforge.bobber -DarchetypeArtifactId=maven-archetype-jbi-component \ 
  -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=org.bobber.test -DartifactId=SPML -DComponentName=SPML
------------------------------------------------------------------------------------------------------------------



