Maven Archetypes
Up to this point, you have created a Maven project manually, generating the folders and creating the pom.xml files from scratch. This can become tedious, especially when you frequently have to create projects. To address this issue, Maven provides archetypes. Maven archetypes are project templates that allow users to generate new projects easily.
Maven archetypes also provide a great platform to share best practices and enforce consistency beyond Maven’s standard directory structure. For example, an enterprise can create an archetype with the company’s branded cascading style sheet (CSS), approved JavaScript libraries, and reusable components. Developers using this archetype to generate projects will automaticaly conform to the company’s standards.
Maven provides hundreds of out-of-the-box archetypes for developers to use. Additionally, a lot of open source projects provide additional archetypes that you can download and use. Maven also provides an archetype plug-in with goals to create archetypes and generate projects from archetypes.
The archetype plug-in’s generate goal allows you to view and select an archetype for use. Listing 6-1 shows the results of running the generate goal at the command line. As you can see, there are 491 archetypes to choose from. This chapter will look at using a few of these archetypes.
Listing 6-1. Maven generate Goal
$mvn archetype:generate
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom <<<
[INFO]
[INFO] --- maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
...........................
...........................
1176: remote -> ru.yandex.qatools.camelot:camelot-plugin (-)
1177: remote -> se.vgregion.javg.maven.archetypes:javg-minimal-archetype (-)
1178: remote -> sk.seges.sesam:sesam-annotation-archetype (-)
1179: remote -> tk.skuro:clojure-maven-archetype (A simple Maven archetype for Clojure)
1180: remote -> tr.com.lucidcode:kite-archetype (A Maven Archetype that allows users to create a Fresh Kite project)
1181: remote -> uk.ac.rdg.resc:edal-ncwms-based-webapp (-)
1182: local -> com.inflinx.book.ldap:practical-ldap-empty-archetype (-)
1183: local -> com.inflinx.book.ldap:practical-ldap-archetype (-)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): 491:
Generating a Web Project
Maven provides the maven-archetype-webapp archetype for generating a web application. Let’s generate the application by running the following command in the C:apressgswm-bookchapter6 folder:
mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp
The command runs in interactive mode. Enter the following information for the requested inputs:
Define value for property 'groupId': : com.apress.gswmbook
Define value for property 'artifactId': : gswm-web
Define value for property 'version': 1.0-SNAPSHOT: : <<Hit Enter>>
Define value for property 'package': com.apress.gswmbook: : war
Confirm the properties configuration:
groupId: com.apress.gswmbook
artifactId: gswm-web
version: 1.0-SNAPSHOT
package: war
Y: <<Hit Enter>>
The generated directory structure should resemble the one shown in Figure 6-1.
Figure 6-1. Maven web project structure
The pom.xml file is minimal and only has a JUnit dependency. Maven makes it easier to run your web application using embedded web servers, such as Tomcat and Jetty. Listing 6-2 shows the modified pom.xml file with a Tomcat plug-in added.
Listing 6-2. Modified pom.xml with Embedded Tomcat Plug-in
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.apress.gswmbook</groupId>
<artifactId>gswm-web</artifactId>
<packaging>war</packaging>
<version>1.0-SNAPSHOT</version>
<name>gswm-web Maven Webapp</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<finalName>gswm-web</finalName>
<plugins>
<plugin>
<groupId>org.apache.tomcat.maven</groupId>
<artifactId>tomcat7-maven-plugin</artifactId>
<version>2.2</version>
</plugin>
</plugins>
</build>
</project>
In order to launch the web application inside the Tomcat server, run the following command at the root directory of the project:
mvn tomcat7:run
You will see the project deployed and view output similar to that shown in Listing 6-3.
Listing 6-3. Output from the Tomcat run Command
Oct 11, 2014 12:08:43 PM org.apache.catalina.core.StandardService startInternal
INFO: Starting service Tomcat
Oct 11, 2014 12:08:43 PM org.apache.catalina.core.StandardEngine startInternal
INFO: Starting Servlet Engine: Apache Tomcat/7.0.47
Oct 11, 2014 12:08:45 PM org.apache.catalina.util.SessionIdGenerator createSecureRandom
INFO: Creation of SecureRandom instance for session ID generation using [SHA1PRNG] took [334] milliseconds.
Oct 11, 2014 12:08:45 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Now launch the browser and navigate to http://localhost:8080/gswm-web/. You should see the web page as shown in Figure 6-2.
Figure 6-2. Web project launched in browser
Java Enterpise Edition (JEE) projects are often split into several modules to ease development and maintainability. Each of these modules produces artifacts such as Enterprise JavaBeans (EJBs), web services, web projects, and client jars. Maven supports development of such large JEE projects by allowing multiple Maven projects to be nested under a single Maven project. The layout of such a multimodule project is shown in Figure 6-3. The parent project has a pom.xml file and individual Maven projects inside it.
Figure 6-3. Multimodule project structure
In the rest of this section, we will explain how to build a multimodule project for the scenario where you have to split your large project into a web application (WAR artifact) that provides a user interface, a service project (JAR artifact) that holds service layer code, and a persistence project that holds your repository layer code. Figure 6-4 provides a visual representation of this scenario.
Figure 6-4. Maven multimodule project
Let’s start the process by generating the parent project. To do this, run the following command at the command line under C:apressgswm-bookchapter6:
mvn archetype:generate -DgroupId=com.apress.gswmbook -DartifactId=gswm-parent -Dversion=1.0.0-SNAPSHOT -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=pom-root
The archetype pom-root creates the gswm-parent folder and a pom.xml file underneath it. As you can see in Listing 6-4, the generated pom.xml file has minimal content. Notice that the packaging of the parent project is set to type pom.
Listing 6-4. Parent pom.xml File
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.apress.gswmbook</groupId>
<artifactId>gswm-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>gswm-parent</name>
</project>
Then create the web project by running the following command in the C:apressgswm-bookchapter6gswm-parent folder:
mvn archetype:generate -DgroupId=com.apress.gswmbook -DartifactId=gswm-web -Dversion=1.0.0-SNAPSHOT -Dpackage=war -DarchetypeArtifactId=maven-archetype-webapp
During this web project generation, you are providing Maven coordinates, such as groupId, version, and so on, as parameters to the generate goal. This created the gswm-web project.
The next step is to create the service project. Run the following command under C:apressgswm-bookchapter6gswm-parent:
mvn archetype:generate -DgroupId=com.apress.gswmbook -DartifactId=gswm-service -Dversion=1.0.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
Notice that you didn’t provide the package parameter, as the maven-archetype-quickstart produces a JAR project by default. Also, notice the use of the interactiveMode parameter. This instructs Maven to simply run the command without prompting the user for input.
Similar to the previous step, create another Java project gswm-repository by running the following command under C:apressgswm-bookchapter6gswm-parent:
mvn archetype:generate -DgroupId=com.apress.gswmbook -DartifactId=gswm-repository -Dversion=1.0.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
Now that you have all of the projects generated, let’s look at the pom.xml file under gswm-parent. Listing 6-5 shows the pom.xml file.
Listing 6-5. Parent pom.xml File with Modules
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.apress.gswmbook</groupId>
<artifactId>gswm-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>gswm-parent</name>
<modules>
<module>gswm-web</module>
<module>gswm-service</module>
<module>gswm-repository</module>
</modules>
</project>
The modules element allows you to declare child modules in a multimodule project. As you generated each module, Maven intelligently registered them as a child module. Additionally, it modified the individual module’s pom.xml file and added the parent pom information. Listing 6-6 shows gswm-web project’s pom.xml file with the parent pom elements.
Listing 6-6. The pom.xml File for the Web Module
<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.apress.gswmbook</groupId>
<artifactId>gswm-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<groupId>com.apress.gswmbook</groupId>
<artifactId>gswm-web</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>war</packaging>
<name>gswm-web Maven Webapp</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<finalName>gswm-web</finalName>
</build>
</project>
With the entire infrastructure set up, you are ready to build the next project. To accomplish this, simply run the mvn package command under gswm-project, as shown in Listing 6-7.
Listing 6-7. Maven Package Run on the Parent Project
C:apressgswm-bookchapter6gswm-parent>mvn package
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] gswm-parent
[INFO] gswm-web Maven Webapp
[INFO] gswm-service
[INFO] gswm-repository
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] gswm-parent ....................................... SUCCESS [0.001s]
[INFO] gswm-web Maven Webapp ............................. SUCCESS [1.033s]
[INFO] gswm-service ...................................... SUCCESS [0.552s]
[INFO] gswm-repository ................................... SUCCESS [0.261s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.949s
[INFO] Finished at: Mon Oct 13 23:09:21 MDT 2014
[INFO] Final Memory: 6M/15M
[INFO] ------------------------------------------------------------------------
Maven provides several ways to create a new archetype. Here we will use an existing project to generate an archetype.
Let’s start by creating a prototype project that you will use as the seed for archetype creation. This project will be Servlet 3.0 compatible, and it has a Status Servlet that returns a HTTP status code 200. Instead of creating a web project from scratch, copy the previously generated gswm-web project code and create gswm-web-prototype under C:apressgswm-bookchapter6. Make the following changes to the newly copied project:
- Remove all other resources, such as Integrated Development Environment (IDE) specific files (.project, .classpath, and so forth) that you don’t want to end up in the archetype.
- Replace the contents of the web.xml file under the webapp/WEB-INF folder. This will upgrade the web application to use Servlet 3.0:
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<display-name>Archetype Created Web Application</display-name>
</web-app> - Add the Servlet 3.0 dependency to the pom.xml file. The updated pom.xml is shown in Listing 6-8.
Listing 6-8. The pom.xml with Servlet Dependency
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.apress.gswmbook</groupId>
<artifactId>gswm-web</artifactId>
<packaging>war</packaging>
<version>1.0-SNAPSHOT</version>
<name>gswm-web Maven Webapp</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.0.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<finalName>gswm-web</finalName>
<plugins>
<plugin>
<groupId>org.apache.tomcat.maven</groupId>
<artifactId>tomcat7-maven-plugin</artifactId>
<version>2.2</version>
</plugin>
</plugins>
</build>
</project> - Because you will be doing Java web development, create a folder named java under src/main. Similarly, create test/java and test/resources folders under src.
- Create the AppStatusServlet.java file in the com.apress.gswmbook.web.servlet package under src/main/java. The package com.apress.gswmbook.web.servlet translates to folder structure comapressgswmbookwebservlet. The source code for AppStatusServlet.java is shown in Listing 6-9.
Listing 6-9. AppStatusServlet Java Class Source Code
package com.apress.gswmbook.web.servlet;
import javax.servlet.annotation.WebServlet;
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;
@WebServlet("/status")
public class AppStatusServlet extends HttpServlet {
public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
PrintWriter writer = response.getWriter();
writer.println("OK");
response.setStatus(response.SC_OK);
}
}
The prototype project will be similar to the structure shown in Figure 6-5.
Figure 6-5. Generated prototype project
Using the command line, navigate to the project folder gswm-web-prototype and run the following command:
mvn archetype:create-from-project
Upon completion of the command, you should see the message Archetype created in target/generated-sources/archetype. The newly created archetype is now under gswm-web-prototype/target/generated-sources/archetype.
The next step is to move the newly created archetype into a separate folder gswm-web-archetype so that it can be tweaked before it is published. To accomplish this, follow these steps:
- Create folder gswm-web-archetype in the C:apressgswm-bookchapter6 folder.
- Copy subdirectories and files in the C:apressgswm-bookchapter6gswm-web-prototype argetgenerated-sourcesarchetype folder to the gswm-web-archetype folder.
- Delete the target subdirectory from the C:apressgswm-bookchapter6gswm-web-archetype folder.
The directory structure for gswm-web-archetype should be similar to that shown in Figure 6-6.
Figure 6-6. Web archetype project structure
Let’s start the modification process with the pom.xml file located at gswm-web-archetypesrcmain esourcesarchetype-resources. Change the final name in the pom.xml file from gswm-web to ${artifactId}. During project creation, Maven will replace the ${artifactId} expression with the user-supplied artifactId value.
When a project is created from an archetype, Maven prompts the user for a package name. It will create the directories corresponding to the package under the src/main/java folder of the newly created project. It then moves all of the contents under the archetype’s archetype-resources/src/main/java folder into that package. Because you would like the AppStatusServlet under the subpackage web.servlet, create the folder web/servlet and move AppStatusServlet.java under the newly created folder. The new location of the AppStatusServlet.java is shown in Figure 6-7.
Figure 6-7. AppStatusServlet under the web.servlet package
Open AppStatusServlet.java and change the package name from package ${package}; to package ${package}.web.servlet;.
The final step in creating the archetype is to run the following at the command line inside the folder gswm-web-archetype:
mvn clean install
Once the archetype is installed, the easiest way to create a project from it is to run the following command under C:apressgswm-bookchapter6:
mvn archetype:generate -DarchetypeCatalog=local
Enter the values shown in Listing 6-10 for the Maven prompts, and you will see a test-project created.
Listing 6-10. Creating a New Project Using Archetype
C:apressgswm-bookchapter6>mvn archetype:generate -DarchetypeCatalog=local
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:1: local -> com.apress.gswmbook:gswm-web-archetype (gswm-web-archetype)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
Define value for property 'groupId': : com.apress.gswmbook
Define value for property 'artifactId': : test-project
Define value for property 'version': 1.0-SNAPSHOT: :
Define value for property 'package': com.apress.gswmbook: :
Confirm properties configuration:
groupId: com.apress.gswmbook
artifactId: test-project
version: 1.0-SNAPSHOT
package: com.apress.gswmbook
Y: :
------------------------------------------------------------------------------
project
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1:27.635s
[INFO] Finished at: Mon Oct 13 23:36:01 MDT 2014
[INFO] Final Memory: 9M/22M
[INFO] ------------------------------------------------------------------------
Because the pom.xml file for the test-project already has the embedded Tomcat plug-in, run mvn tomcat7:run in the command line under the folder C:apressgswm-bookchapter6 est-project to launch the project. Open a browser and navigate to http://localhost:8080/test-project/status. You will see OK displayed, as shown in Figure 6-8.
Figure 6-8. Output of the generated test project
Summary
Maven archetypes are project templates that allow you to bootstrap new projects quickly. This chapter used built-in archetypes for generating advanced Maven projects, such as web projects and multimodule projects. You also looked at creating and using a custom archetype.
In the next chapter, you will learn the basics of site generation and creating documentation and reports using Maven.