How to setup a maven JEE project in Eclipse

Let's suppose you are new to JEE programming. After reading oracle official JEE tutorial document for a few days, you decide to get your hands wet. You download and install a JEE container, GlassFish 4 in this tutorial, to your PC. You have JDK,maven and Eclipse all ready. So, what's next?

This demo shows you how to create maven project in Eclipse that can automatically deploy to a local GlassFish server.

0. What you need

JDK 7+
Glassfish 4.0
Maven
Eclipse Java EE IDE (Luna 4.4.2 used in this demo)

1. Create a Empty Maven project in Eclipse

Since the demo is about servlet, so choose webapp archetype. For EJB you can choose the most simple one "maven-archetype-quickstart". The click next until finish.

2. Modify pom.xml

Modify pom file for 4 reasons.

Change default package from "jar" to "war"
Add JEE dependency
Change default Java version to 1.7
Configure Cargo plugin so we can use maven command-line to deploy you JEE package to server

<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.shengwang.demo</groupId>
  <artifactId>jee-servlet-demo</artifactId>
  <packaging>war</packaging>
  <version>1.0</version>
  <name>jee-servlet-demo Maven Webapp</name>
  <url>http://maven.apache.org</url>
  
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- This is where I have my glassfish installed -->
    <glassfish.home>D:\glassfish4.0</glassfish.home>
  </properties>

  <dependencies>
    <!-- JEE dependency -->
    <dependency>
      <groupId>javax</groupId>
      <artifactId>javaee-api</artifactId>
      <version>7.0</version>
    </dependency>
  </dependencies>

  <build>
    <finalName>jee-servlet-demo</finalName>

    <!-- Use Java 1.7 -->
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.5.1</version>
        <configuration>
          <source>1.7</source>
          <target>1.7</target>
        </configuration>
      </plugin>

      <!-- config cargo use local installed Glassfish -->
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <inherited>true</inherited>
        <configuration>
          <container>
            <containerId>glassfish4x</containerId>
            <type>installed</type>
            <home>${glassfish.home}</home>
          </container>
          <configuration>
            <type>existing</type>
            <home>${glassfish.home}/glassfish/domains</home>
          </configuration>
        </configuration>
      </plugin>

    </plugins>
  </build>
</project>

3. Change Servlet version

The just created project may have error about servlet version, since the archetype in Eclipse is not actively maintained. The project is still using servlet version 2.3. There's also a bug in Eclipse that you can't change the version, You can only disable the Dynamic Web Module facets and set it again.

Right click on project name, and choose "Project Facets", then unselect Dynamic Web Module first.

Uncheck the Dynamic Web Module, click OK to finish. Then open project facets again, set it back.

4. Set JEE application related config

In this demo, servlet need a web.xml for deploy. If writing a EJB has persistence, then you may need a JPA config file persistence.xml.

<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>Demo for jee servlet hello world config</display-name>

</web-app>

The web.xml for this JEE servlet is almost empty. There is no <servlet> and <servlet-mapping> for normal servlet container (like tomcat) deployment. Because JEE server can automatic register servlets with annotation @WebServlet

5. Define Java class

We has only one class to write, HelloServlet.java. If the src/main/java directory not exists, create it by hand.

package com.shengwang.demo;

import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;


@WebServlet(name = "helloServlet", urlPatterns = { "/hello" })
public class HelloServlet extends HttpServlet {
  private static final long serialVersionUID = 1L;

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    PrintWriter out = resp.getWriter();
    out.printf("%s", "hello world from a JEE servlet");
    out.flush();
  }
}

This class use JEE annotation @WebServlet to provide http service at url localhost:8080/context_name/urlPattern . context_name is set in pom.xml by <finalName>, urlPattern is the urlPattern set in Java code. So for this demo the url is http://localhost:8080/jee-servlet-demo/hello

All done, now this 3-files project hierarchy looks like:

6. Run

Use maven command line to auto deploy our servlet to the local GlassFish server.

mvn clean verify cargo:run

The console output looks like below, the cargo maven plugin will start server and deploy automatically.

Now access our hello world level JEE servlet by browser.

Now if you open admin console of GlassFish, you can see our demo is correctly deployed. (Login required, default user is 'admin', default password is 'adminadmin' for cargo plugin)