How to create a EJB 3.x project using Maven in Eclipse – Part 1

In this EJB3 Maven tutorial, we will see how to build and deploy EJB3 in JBoss AS 7 using m2eclipse plugin which provides Maven integration in Eclipse IDE. This tutorial is split into 2 parts with this part containing the steps to develop and deploy the EJB in JBoss AS using Maven whereas the next part shows how to create and run the EJB3 remote client using Maven.

Environment Used

Java SE 6
Eclipse Juno for Java EE Developers (4.2) IDE
Maven Eclipse Plugin – m2eclipse version 1.2
EJB 3.x (stateless session bean)
JBoss Application Server (AS) 7.1.0.Final

Setting up development environment:
Read this page for installing and setting up the environment for creating Maven projects in Eclipse using m2eclipse plugin.

Project Description

We are going to create a simple EJB 3 HelloWorld stateless session bean project and a remote Java application client which will call/invoke the bean.
This “HelloWorld” example explains how to develop and deploy EJB3 in JBoss application server 7.
For testing this “HelloWorld” bean we write a remote Java Application Client (main() method).

Creating New Maven Project in Eclipse

Open Eclipse IDE and create a new Maven project which can be done in three ways,
- Right click on Project Explorer -> New -> Other… -> Maven -> Maven Project
- File menu -> New -> Other… -> Maven -> Maven Project
- Click on the down arrow on New icon on toolbar -> Other… -> Maven -> Maven Project

Select Maven Project and click Next.

This screen prompts for project workspace location. Make sure “Use default Workspace location” and “Create a simple project (skip archetype selection)” are selected and click Next.

We skip the archetype selection because you can copy paste the pom.xml provided below. Otherwise you can select a “maven quickstart” or any “java ee” archetypes.

Now we have to configure the project by enter the following details and click Finish.
- Enter Group Id: as “com.theopentutorials.ejb3“
- Enter Artifact Id as “ejbmavendemo“
- Enter Version: as “1.0-SNAPSHOT“
- Packaging: jar
- Name: EJB3 Maven Demo

Right-click the project, select Properties. Click on “Project Facets” and click “Convert to faceted form”.
Check the “EJB Module” and select the version as 3.0 or 3.1
Put Eclipse IDE in Java EE perspective. (Window menu -> Open Perspective)

Creating Session Bean and Bean Interface

Right click on src/main/java folder -> New -> Session Bean (EJB 3.x)
Java package name as com.theopentutorials.ejb3
Enter the Class name as HelloWorldBean
Select the State type as Stateless
Check the Remote Business Interface and enter the name as com.theopentutorials.ejb3.HelloWorld.
Click Finish

Bean Interface

Copy the following code in the bean interface and save it.

package com.theopentutorials.ejb3;
import javax.ejb.Remote;

@Remote
public interface HelloWorld {
	public String sayHello();
}

Bean Class

Copy the following code in the bean class and save it.

package com.theopentutorials.ejb3;
import javax.ejb.Stateless;

@Stateless
public class HelloWorldBean implements HelloWorld {
    public HelloWorldBean() {
    }

    public String sayHello() {
	return "Hello World !!!";
    }
}

Configuring Maven pom.xml for EJB3

Complete pom.xml

Complete pom.xml is shown below. Open your pom.xml and copy-paste the following content.

<?xml version="1.0"?>
<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.theopentutorials.ejb3</groupId>
	<artifactId>ejbmavendemo</artifactId>
	<version>1.0-SNAPSHOT</version>
	<name>EJB3 Maven Demo</name>
	<packaging>ejb</packaging>

	<properties>
		<!-- Explicitly declaring the source encoding eliminates the following 
			message: -->
		<!-- [WARNING] Using platform encoding (UTF-8 actually) to copy filtered 
			resources, i.e. build is platform dependent! -->
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

		<!-- JBoss dependency versions -->
		<version.org.jboss.as.plugins.maven.plugin>7.3.Final</version.org.jboss.as.plugins.maven.plugin>
		<version.org.jboss.spec.jboss.javaee.6.0>3.0.0.Final</version.org.jboss.spec.jboss.javaee.6.0>

		<!-- other plugin versions -->
		<version.compiler.plugin>2.3.1</version.compiler.plugin>
		<version.ejb.plugin>2.3</version.ejb.plugin>

		<!-- maven-compiler-plugin -->
		<maven.compiler.target>1.6</maven.compiler.target>
		<maven.compiler.source>1.6</maven.compiler.source>
		
		<!-- Optional: to use jboss-as:run goal -->
		<!--<jboss-as.home>C:\Users\iByteCode\Desktop\jboss-as-7.1.0.Final</jboss-as.home> -->
	</properties>

	<dependencyManagement>
		<dependencies>
			<!-- Define the version of JBoss' Java EE 6 APIs we want to use -->
			<!-- 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 stack (you can read this as 
				the JBoss stack of the Java EE 6 APIs). You can actually use this stack with 
				any version of JBoss AS that implements Java EE 6, not just JBoss AS 7! -->
			<dependency>
				<groupId>org.jboss.spec</groupId>
				<artifactId>jboss-javaee-6.0</artifactId>
				<version>${version.org.jboss.spec.jboss.javaee.6.0}</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<dependencies>

		<!-- Import the Common Annotations API (JSR-250), we use provided scope 
			as the API is included in JBoss AS 7 -->
		<dependency>
			<groupId>org.jboss.spec.javax.annotation</groupId>
			<artifactId>jboss-annotations-api_1.1_spec</artifactId>
			<scope>provided</scope>
		</dependency>

		<!-- Import the EJB 3.1 API, we use provided scope as the API is included 
			in JBoss AS 7 -->
		<dependency>
			<groupId>org.jboss.spec.javax.ejb</groupId>
			<artifactId>jboss-ejb-api_3.1_spec</artifactId>
			<scope>provided</scope>
		</dependency>

	</dependencies>

	<build>
		<!-- Set the name of the deployment -->
		<plugins>
			<!-- JBoss AS plugin to deploy the application -->
			<plugin>
				<groupId>org.jboss.as.plugins</groupId>
				<artifactId>jboss-as-maven-plugin</artifactId>
				<version>${version.org.jboss.as.plugins.maven.plugin}</version>
				<configuration>
					<filename>${project.build.finalName}.jar</filename>
				</configuration>
			</plugin>
			<!-- Compiler plugin enforces Java 1.6 compatibility and activates annotation 
				processors -->
			<plugin>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>${version.compiler.plugin}</version>
				<configuration>
					<source>${maven.compiler.source}</source>
					<target>${maven.compiler.target}</target>
				</configuration>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-ejb-plugin</artifactId>
				<version>${version.ejb.plugin}</version>
				<configuration>
					<ejbVersion>3.1</ejbVersion>
					<!-- this is false by default -->
					<generateClient>true</generateClient>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Maven Plugins used

1. maven-compiler-plugin
The maven-compiler-plugin is used to compile the sources of your project. In the above pom.xml we have used the version 2.3.1 of the plugin with the source and target JDK set to 1.6 under configuration.

We have defined these settings as properties inside <properties> tag and referring it through ${property}.

<version.compiler.plugin>2.3.1</version.compiler.plugin>
<!-- maven-compiler-plugin -->
<maven.compiler.target>1.6</maven.compiler.target>
<maven.compiler.source>1.6</maven.compiler.source>

2. maven-ejb-plugin
This plugin generates J2EE Enterprise Javabean (EJB) file as well as the associated client jar. We specify the ejb version as 3.1 and request the plugin to generate the client by setting the “generateClient” property to true.

3. jboss-as-maven-plugin
The jboss-as-maven-plugin is used to deploy, redeploy, undeploy or run your application in JBoss AS. Under the configuration we specify the build file name same as the project build filename which is by default of the form “artifactid-version” in our case “ejbmavendemo-1.0-SNAPSHOT”.

Required Maven Dependencies for EJB3

1. jboss-javaee-6.0
Defines the version of JBoss’ Java EE 6 APIs we want to use. 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 specify this in <dependencyManagement> tag so that we always get the correct versions of artifacts. The type of this dependency itself a pom which contains the required dependencies.

<dependency>
	<groupId>org.jboss.spec</groupId>
	<artifactId>jboss-javaee-6.0</artifactId>
	<version>${version.org.jboss.spec.jboss.javaee.6.0}</version>
	<type>pom</type>
	<scope>import</scope>
</dependency>

2. jboss-annotations-api_1.1_spec

<dependency>
	<groupId>org.jboss.spec.javax.annotation</groupId>
	<artifactId>jboss-annotations-api_1.1_spec</artifactId>
	<scope>provided</scope>
</dependency>

3. jboss-ejb-api_3.1_spec

<dependency>
	<groupId>org.jboss.spec.javax.ejb</groupId>
	<artifactId>jboss-ejb-api_3.1_spec</artifactId>
	<scope>provided</scope>
</dependency>

Whenever the pom.xml is changed, update the project to reflect the changes made. To update, Right click on your project in Package Explorer -> Maven -> Update Project … as shown below.

Install EJB3 in local Maven repository

The next step is to build the EJB and client interfaces JARs and install them in your local Maven repository. To do that we use maven’s clean and install phase.

Right-click your pom.xml and select “Run As -> Maven build…” and type the goal as “clean install” as shown below.

You can check your local maven repository (for example, username/.m2/repository/com/theopentutorials) folder which should contain the ejbmavendemo-1.0-SNAPSHOT.jar and client jar file.

When executing this “clean install” if you face any problem such as

Unable to locate the Javac Compiler in: C:\Program Files\Java\jre6\..\lib\tools.jar. Please ensure you are using JDK 1.4 or above and not a JRE (the com.sun.tools.javac.Main class is required) OR
Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:2.3.1:compile (default-compile) on project ejbmavendemo: Compilation failure

then we need to specify the JRE directory to point to JDK instead of JRE directory. To do that, go to Eclipse menu Windows menu -> Preferences -> Java -> Installed JREs. Select the Installed JRE from right pane and click on Edit. For JRE home: select JDK directory and click Finish and OK.

Deploy EJB3 JAR in JBoss AS

Now we have to deploy this ejb application in JBoss which can be done in many ways.

Method 1: using jboss-as:deploy maven goal
The JBoss AS server should be running before we can deploy. “jboss-as:deploy” maven goal deploys the application in JBoss server.

Start JBoss Application Server either using command line or inside Eclipse Servers.
Right click your pom.xml -> Run as -> Maven Build …. In the Goals: type jboss-as:deploy as shown below. Click on Apply and Run.

Method 2: using jboss-as:run maven goal
You can also use “jboss-as:run” maven goal which starts the application server and deploys your application. But for this “run” goal, we need to add a property (jboss-as.home) in <properties> tag mentioning your “JBOSS_HOME” directory. This is already mentioned in the complete pom.xml (provided above) under <properties> tag. Just uncomment the below given line in that file and mention your JBOSS_HOME directory. If you did not specify the jboss-as.home property then the plugin will download the entire JBoss AS from their site.

<!-- Optional: to use jboss-as:run goal -->
<jboss-as.home>C:\Users\iByteCode\Desktop\jboss-as-7.1.0.Final</jboss-as.home>

Right click your pom.xml -> Run as -> Maven Build …
In the Goals: type jboss-as:run. Click on Apply and Run.

You can use Web Console to check whether the EJB3 application JAR has been installed in JBoss. Use the URL http://localhost:9990/ and select Manage Deployments under Deployments. You may need a management realm username/password to login. To do so refer this link.