Technology: Maven Archetypes

Maven Archetypes are used to create a basic structure for a certain kind of project. A simple example is the archetype that creates the structure for Maven site. These archetypes can be easily adapted for individual use and different types of projects.

This document introduces the BPSE Basic Sample archetype that creates a project which can be compiled directly after creation and contains a very simple program to show some software concepts. We will also look at how archetypes themselves are designed and can be created for individual use.

BPSE-Basic Archetype Structure

The basic archetype is defined through the following directory structure.

  basic
  |-- pom.xml
  `-- src
      |-- main
      |   |-- resources
      |   |   `-- META-INF
      |   |       `-- archetype.xml
      |   `-- archetype-resources
      |       |-- src
      |       |   |-- main
      |       |   |   |-- java
      |       |   |   |   |-- dao
      |       |   |   |   |   |-- package-info.java
      |       |   |   |   |   |-- IStudentDAO.java
      |       |   |   |   |   `-- JdbcObjectStudentDAO.java
      |       |   |   |   |-- domain
      |       |   |   |   |   |-- Person.java
      |       |   |   |   |   `-- Student.java
      |       |   |   |   |-- export_import
      |       |   |   |   |   |-- Export.java
      |       |   |   |   |   |-- HtmlExport.java
      |       |   |   |   |   |-- Import.java
      |       |   |   |   |   |-- package-info.java
      |       |   |   |   |   `-- XmlExportImport.java
      |       |   |   |   |-- gui
      |       |   |   |   |   |-- EditStudentFrame.java
      |       |   |   |   |   |-- ExportMenuModel.java
      |       |   |   |   |   |-- MainFrame.java
      |       |   |   |   |   |-- package-info.java
      |       |   |   |   |   |-- RegexTextField.java
      |       |   |   |   |   `-- StudentTableModel.java
      |       |   |   |   |-- helper
      |       |   |   |   |   |-- Constants.java
      |       |   |   |   |   `-- package-info.java
      |       |   |   |   |-- package-info.java
      |       |   |   |   `-- Basis.java
      |       |   |   `-- resources
      |       |   |       |-- data
      |       |   |       |   |-- pruefungen.properties
      |       |   |       |   `-- pruefungen.script
      |       |   |       |-- beans.xml
      |       |   |       |-- log4j.properties
      |       |   |       |-- messages.properties
      |       |   |       `-- messages_en.properties
      |       |   |-- site
      |       |   |   |-- apt
      |       |   |   |   |-- format.apt
      |       |   |   |   `-- index.apt
      |       |   |   |-- fml
      |       |   |   |   `-- faq.fml
      |       |   |   |-- xdoc
      |       |   |   |   `-- xdoc.xml
      |       |   |   |-- resources
      |       |   |   |   `-- images
      |       |   |   `-- site.xml
      |       |   `-- test
      |       |       |-- java
      |       |       |   `-- test
      |       |       |       |-- dao
      |       |       |       |   |-- AllDAOTests.java
      |       |       |       |   |-- package-info.java
      |       |       |       |   `-- JdbcStudentTest.java
      |       |       |       |-- export
      |       |       |       |   |-- AllExportTests.java
      |       |       |       |   |-- ExportImportTest.java
      |       |       |       |   |-- HtmlExportTest.java
      |       |       |       |   |-- package-info.java
      |       |       |       |   `-- XmlExportImportTest.java
      |       |       |       |-- AllTests.java
      |       |       |       `-- package-info.java
      |       |       `-- resources
      |       |           |-- data
      |       |           |   |-- pruefungen.properties
      |       |           |   `-- pruefungen.script
      |       |           |-- test
      |       |           |   `-- html-export.html
      |       |           `-- test-beans.xml
      |       `-- pom.xml
      `-- site
          |-- apt
          |   |-- directory.apt
          |   |-- index.apt
          |   |-- installation.apt
          |   |-- structure.apt
          |   `-- usage.apt
          |-- fml
          |-- xdoc
          `-- site.xml

General Files

  • pom.xml is the Project Object Model for the whole archetype itself which contains all information about the organisation, structure, dependencies and reporting.
  • src - site contains the documentation for the archetype.
    • src - site - site.xml defines the structure of this documentation.
  • src - site - apt contains all documentation files written in APT (Almost Plain Text).
    • src - site - apt - structure.apt for example is the file that is parsed to the text you are actually reading.
  • src - site - fml contains all documentation files written in FAQ language which is used in Maven.
  • src - site - resources contains additional resources needed for the documentation.
  • src - site - xdoc contains all documentation files written in the XDoc format.

Archetype Files

An Archetype requires a least two directories. The first one is the resources - META-INF directory which contains the archetype.xml file that defines the structure of the archetype. The second one - archetype - resources - contains a reflection of the directories and files that should be included in the archetype. The files in these directories contain 'real' information like program code or pictures and are linked to the final archetype by the archetype.xml.

Structure of the archetype.xml

The archetype.xml has the following basic structure.

  <archetype>
    <id>Archetype Id</id>
    <sources>
      <source>Path to file</source>
    </sources>
    <resources>
      <resource>Path to file</resource>
    </resources>
    <testSources/>
    <testResources/>
    <siteResources/>
  </archetype>
  • id holds the id of the archetype used in the pom.xml of the archetype.
  • sources incloses multiple source-entries that refer to the program sources of the archetype. For the path of all sources and resources the archetype-resources directory is used as root.
  • resources contains multiple resource-entries that refer to additional files needed for the archetype. These need not to necessarily be files in the common used resources-directory. Examples would be files for the configuration management or the webapp directory for webapplications.
  • testSources and testResources are similarly used to sources and resources for the needed unit tests.
  • siteResources includes resource-elements that are used for the documentation.

Example of an archetype.xml

This section shows a part of the archetype.xml of the basic archetype.

  <archetype>
    <id>bpse-archetype-basic</id>
    <sources>
      <source>src/main/java/Basis.java</source>
      <source>src/main/java/Constants.java</source>
      [...]
      <source>src/main/java/dao/IStudentDAO.java</source>
      [...]
      <source>src/main/java/gui/MainFrame.java</source>
    </sources>
    <resources>
      <resource>src/main/resources/beans.xml</resource>
      [...]
      <resource>src/main/resources/data/pruefungen.script</resource>
    </resources>
    <testSources>
      <source>src/test/java/test/dao/JdbcStudentTest.java</source>
    </testSources>
    <testResources>
      <resource>src/test/resources/test-beans.xml</resource>
    </testResources>
    <siteResources>
      <resource>src/site/site.xml</resource>
      [...]
    </siteResources>
  </archetype>

Example file

This section shows an example on how to build program code that can be used in the archetype.

The program snippet below is used in the basic archetype. At first it looks like a common Java class, but instead of the package declaration and the first part of the import declaration a Maven variable is used. This variable is the groupId which is later entered by the user who builds a new application structure. When creating a Projekt from an archetype, Maven searches the files included in the archetype-resources folder and replaces the variable with the value entered. If neccessary other Maven variables e.g. version information can also be specified.

  package ${groupId};

  import org.apache.log4j.Logger;

  import ${groupId}.gui.MainFrame;

  /**
   * This class starts the User-Interface.
   * 
   * @author Kristof
   * @version 0.1.0
   * 
   */
  public class Basis {

      /**
       * Retrieve log4j Logger for this class.
       */
      private static Logger logger = Logger.getLogger(Main.class);

      /**
       * Entry point for the application that starts the MainFrame.
       * 
       * @param args
       * @see MainFrame
       */
       public static void main(String[] args) {
            logger.info("Appliction started.");

            MainFrame main = new MainFrame();
            main.pack();
            main.setVisible(true);

            logger.info("Terminated Start Class");
       }
  }