Version 14

    With maven's widespread adoption as a build tool, maven archetypes have become the de-facto standard way to share and/or kickstart new projects in a jiffy.

    The maven archetype technology is now embedded inside modern Java IDEs, allowing users to create new projects very easily from a nice UI interface.

    This document is meant to provide a few guidelines when it comes to building archetypes themselves, so that you can ensure created projects :

    a) Build everywhere (CLI and IDEs) out-of-the-box

    b) Follow best practices in modular application architecture

    c) Are truly portable among JavaEE 6 application servers


    Create from an existing project

    The best way to create a new maven archetype is to start from an existing maven project. If this is a multimodule project, then it's strongly suggested your sub-modules artifactIds are composed of <parentArtifactId>-<somesuffix> (ex : ee6app has ee6app-web, ee6app-ejb, ee6app-fmk ... submodules). That way, the maven archetype plugin will be able to isolate the common rootArtifactId and users will create truly personalized projects.


    At the root of your project <myproject>, just run the "archetype:create-from-project" goal.


    mvn clean archetype:create-from-project -Dinteractive=true


    Using the attribute -Dinteractive=true will activate well, the interactive mode. It'll allow you to set some default property values.

    To ease the integration of the archetype with JBoss Tools, let's add a enterprise property, that will be reused later on.


    [INFO] Setting default groupId:
    [INFO] Setting default artifactId: multi
    [INFO] Setting default version: 0.0.1-SNAPSHOT
    [INFO] Setting default package:
    Add a new custom property Y: : Y
    Define property key: enterprise
    Define value for enterprise : : false
    Add a new custom property Y: : N
    Confirm archetype configuration:
     Y: : N
    Define value for archetype.groupId: : org.jboss.archetypes.sample
    Define value for archetype.artifactId:  multi-archetype: : 
    Define value for archetype.version:  0.0.1-SNAPSHOT: : 
    Define value for groupId: : org.jboss.multi
    Define value for artifactId:  multi: : ee6
    Define value for version:  0.0.1-SNAPSHOT: : 
    Define value for package: : org.jboss.multi
    Add a new custom property Y: : N
    Confirm archetype configuration:
     Y: : Y


    It'll create a new maven-archetype project under <myproject>/target/generated-sources/. For multi-module archetypes, you'll see all the module folders are prefixed with __rootArtifactId__. This rootArtifactId is available for templating purposes under the ${rootArtifactId} placeholder. You can find an example of a multi-module archetype metadata here :


    Remove hardcoded packages

    Now that the archetype skeleton is created, it needs to be curated from some hard-coded values. For instance, in all java classes and configuration files, packages must be changed to ${package}.<module-suffix> (see for instance)



    Lock down plugin versions

    It's considered a best practice to lock down the plugin versions in parent pom. To do this, use the jboss-parent POM as your parent.


          <relativePath />




    Logic in archetype templates

    Archetype templates are based on the Velocity template engine. As such, it's possible to embed a certain amount of logic when generating the project files. You can, for instance, define dependencies, based on the value of some archetype property. ex :


    #if( $enterprise == "true" ||  $enterprise == "y" ||  $enterprise == "yes")


    This blog's WYSIWYG editor doesn't want to display the velocity syntax properly, be aware strings in the if statements must be surrounded by double quotes. See a proper example here.


    This renders maven archetypes much more powerful than what you might expect. Read for more informations.


    Don't embed JBoss repositories in pom.xml

    Putting repositories in your POMs is a Bad Idea. You need to make sure all your dependencies are in Maven Central. If you need help with doing this, email the JDF team -


    Escape special characters

    Whenever some special characters need to be used, and to prevent the archetype plugin, or rather Velocity, from filtering, you need to define escaping variables in each processed file, such as :


    #set( $symbol_pound = '#' ) 
    #set( $symbol_dollar = '$' ) 
    #set( $symbol_escape = '\' ) 


    Web application context root

    Be aware that m2e-wtp, for instance, determines the context root of a standalone web application from the <finalName> value defined in (or inferred from) the <build> section of a war project. So if you are creating a WAR, you should define:




    in the pom.xml defined in your archetype.


    The <finalName> value of an artifact is used, in maven's reactor, to define the deployed name of war or ear artifacts. However, due to an Eclipse WTP limitation, for EAR packaging, the eclipse project name needs to be the same as the finalName, to prevent any discrepancy between Eclipse andMaven CLI. See this JBoss Tools issue.


    Annotation processors

    Simply put, annotation processors are not supported yet by m2e. So, if projects from your archetypes are supposed to use this feature, you have no other option (for now) but to add the relevant eclipse configuration files to your archetype resources.



    JBoss target runtimes

    For archetypes designed to run on either JBoss AS 7 or EAP 6, Bill of Materials (BOM) poms should be used in the <dependencyManagement> section of the pom.xml, in order to control the versions of the dependencies provided by the application server.


    BOM Pom dependency in dependencyManagement









    You could also choose to use any BOM from the JBoss Stacks. Switching the BOM value should allow the project to build and deploy directly against the targeted application server.


    You shoukld define a version property for the EE6 API and use the previously mentioned enterprise archetype property to insert one value or another :


    #if ($enterprise == "true" || $enterprise == "y" || $enterprise == "yes" )
            <!-- Certified version of the JBoss EAP components we want to use -->
            <!-- Alternatively, comment out the above line, and un-comment the 
                line below to use version 1.0.2.Final which is based on community built dependencies. -->
            <!-- <>1.0.2.Final</> -->
            <!-- Alternatively, comment out the above line, and un-comment the 
                line below to use version ${jboss-bom-enterprise-version} which is a release certified 
                to work with JBoss EAP 6. It requires you have access to the JBoss EAP 6 
                maven repository. -->
            <!-- <>${jboss-bom-enterprise-version}</>> -->

    And in the <dependencyManagement> section :


                <!-- JBoss distributes a complete set of Java EE 6 APIs including 
                    a Bill of Materials (BOM). A BOM specifies the versions of a "stack" (or 
                    a collection) of artifacts. We use this here so that we always get the correct 
                    versions of artifacts. Here we use the jboss-javaee-6.0-with-tools stack 
                    (you can read this as the JBoss stack of the Java EE 6 APIs, with some extras 
                    tools for your project, such as Arquillian for testing) and the jboss-javaee-6.0-with-hibernate 
                    stack you can read this as the JBoss stack of the Java EE 6 APIs, with extras 
                    from the Hibernate family of projects) -->