Copyright © 2009 OW2 Consortium
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
$Id: index.html 5369 2010-02-24 14:58:19Z benoitf $
Abstract
This documentation is to help developers to use EasyBeans in their Maven project using EJB3 applications.
Table of Contents
List of Tables
Table of Contents
EasyBeans is an open-source Enterprise JavaBeans (EJB) container hosted by the OW2 Consortium. The License used by EasyBeans is the LGPL. EasyBeans is the EJB 3.0 container of the JOnAS application server.
EasyBeans main goal is to ease the development of Enterprise JavaBeans. It uses some new architecture design like the bytecode injection (with ASM ObjectWeb tool), IoC, POJO and can be embedded in OSGi bundles or other frameworks (Spring, Eclipse plugins, etc.).
It aims at providing an EJB 3.0 container as specified in the Java Platform Enterprise Edition 5.x (Java EE). It means that Session beans (Stateless or Stateful), Message Driven Beans (MDB) are available on EasyBeans.
EasyBeans is available on EasyBeans.org home page
EasyBeans user's guide is available here.
In order to use EasyBeans (standalone version) to deploy an ejb3 application and test itself in a simple way, we need to :
Start EasyBeans using a standalone jar package for example
java -jar ow2-easybeans-hibernate-1.1.0-M1.jar
Deploy an ejb3 application package into easybeans-deploy folder
Launch tests
Stop EasyBeans
Developing and testing a J2EE application requires a large number of manipulations. Today, many projects are developed using the Maven 2 project manager. This tool can automate Java project dependencies management as well as its construction, installation and deployment. To process all these tasks, Maven uses plugins which have a specific role (compilation, package construction, tests...). Maven uses a xml file known as a Project Object Model (POM) to describe the software project being built, its dependencies on other external modules and components, and the build order.
To learn more about Maven, please visit http://maven.apache.org/.
As seen, Maven optimizes project achievement time by helping developers during the implementation and testing phases . When creating an EJB application, tests can't be undertaken by just using Maven because EJBs need to be deployed in an EJB container. As EasyBeans is an EJB container, it is useful to run it with Maven just by referencing dependencies and build configurations in the POM of the project.
The solution is to create a Maven plugin that starts EasyBeans and deploys the project before tests are launched.
The Maven EasyBeans plugin has 4 objectives:
Start EasyBeans
Deploy all EJB applications from the project
Automate the deployment of modified EJBs
Stop EasyBeans
Once EJB are deployed, integration tests can be launched.
Moreover, EasyBeans plugin can be configured in some ways as explained in the followings examples.
The EasyBeans Maven plugin has 2 goals:
easybeans:run runs EasyBeans and deploy EJBs
easybeans:stop Stop EasyBeans
Instructions on how to use the EasyBeans Plugin can be found here.
The following examples show how to use the EasyBeans Plugin in more advanced use-cases.
Table of Contents
Anyone can check out source code from the SVN server using the following command or your favourite GUI SVN client:
svn checkout svn://svn.forge.objectweb.org/svnroot/easybeans/sandbox/maven-easybeans-plugin
Once you have checked out the source code from the SVN server, you get at least two directories:
plugin
Contains all sources to build the plugin.
examples
Contains all sources of the examples to understand how to use the plugin.
To install the plugin to your Maven local repository, go into the plugin folder and use the following command:
mvn install
To test all the bound to the Maven build lifecycle examples (HelloWorld, Calculator, Directory and Directory-exploded), just use the following command in the examples folder:
mvn integration-test
To test the examples that are not bound to the Maven build lifecycle (contained in the Unbound-project module), use the following instructions:
First, install and deploy the examples:
mvn install
All the unbound examples are installed in the local repository.
mvn easybeans:run
EasyBeans is started and all the unbound EJB modules examples are deployed.
Now, tests can be launched by using the following command in the Client module into another console:
mvn exec:exec
When tests are done, use the last following command in the directory of your choice:
mvn easybean:stop
Table of Contents
Call this target to:
Start EasyBeans
Deploy all project resources
Deploy all additional resources declared to the POM configuration
In the case of a bound to the Maven build lifecycle project, run goal automaticaly stops.
In the other case, all deployed resources are scanned and deployed again if necessary. This re-deployment may be:
Automatic (default)
Re-deployment is done on every project modification.
Manual
Re-deplyment is done on [Enter] button push.
Moreover, in the all cases, run goal automaticaly found deployable files into the current project, and in the local repository. For unbound projects, deployable files located into children projects are automaticaly deployed too.
Pom parameters for goal run are :
Table 3.1. Run goal parameters
Name | Type | Description | Default-value |
---|---|---|---|
deployables | List | List of additional deployables of current project | - |
scanInterval | Long | The interval in milliseconds to scan EJBs for change | 1000 |
autoDeployment | boolean | Activate automatic redeployment or manual redeployment | true |
wait | String | Define if the plugin waits after the launch of server | - |
serverConfig | String | Path of EasyBeans configuration XML file | - |
checkLocalRepository | boolean | If plugin automatocaly check artifacts in the local repository | true |
Table of Contents
To run EasyBeans with Maven out of the build lifecycle, the EasyBeans Plugin can be invoked by calling the run goal.
mvn org.ow2.easybeans:maven-easybeans-plugin:run
This command line is verbose and can be shorted by adding the following code to the settings.xml file:
<pluginGroups> <pluginGroup> <groupId>org.ow2.easybeans</groupId> </pluginGroup> </pluginGroups>
The command line to invoke EasyBeans plugin is now :
mvn easybeans:run
Here is the minimal configuration avalaible to add the plugin in the POM build section (needed if you want to tell the EasyBeans plugin version you want to use explicitly):
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> </plugin>
To specify more options, just add a configuration tag in the previous plugin declaration.
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <configuration> ... </configuration> </plugin>
Read Complex configuration section for more indications on available options.
Table of Contents
Concerning project that are not bound to the Maven build lifecycle, you can use the EasyBeans plugin to run EasyBeans by using the run goal.
In this case, there are 2 behaviors :
Default configuration
No POM configuration is needed to run the mojo. EasyBeans is lauched with plugin default options.
In this case, automatic deployment is enabled, as said by the plugin log :
[INFO] Automatic deployment is enabled with a scan delay of 1000 ms.
User configuration
POM can be configured explicitly to use the EasyBeans plugin with options. For example, the following code inactivate automatic re-deployment :
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <configuration> <autoDeployment>false</autoDeployment> </configuration> </plugin>
In this case, re-deployement is manual. Just type Enter to deploy a modified deployed file again.
[INFO] Automatic deployment is disabled. Press [ENTER] for redeploy archives.
By default, when using EasyBeans plugin out of the Maven build lifecycle, the following files are deployed:
Project deployable archive included in ${basedir}/target folder.
All deployables archives included in the target folders of all project childs.
Local repository installed archetypes related to current POM artifact.
If you want to deploy more archives, you must add them in the POM configuration as explained in the "Using additional resources" section.
Bound to the Maven build lifecycle, EasyBeans plugin runs at the pre-integration-test phase by calling integration-test phase or a following build phase like install or deploy by using maven command. So, EasyBeans is started with all configured options.
Then several files are deployed into this container.
At this time, Maven execute the integration-test phase and runs tests by using the Surefire plugin. Tests must be added in the POM configuration by following instructions detailed in the "Running a test" section. Finally, when tests are passed, the post-integration-test phase is called. EasyBeans stops and all resources are released.
To use the EasyBeans plugin with your Maven project, and bound it to the integration-test lifecycle phase, just add the following code to the pom.xml file:
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <executions> <execution> <id>start-maven-plugin</id> <phase>pre-integration-test</phase> <goals> <goal>run</goal> </goals> </execution> <execution> <id>stop-maven-plugin</id> <phase>post-integration-test</phase> <goals> <goal>stop</goal> </goals> </execution> </executions> </plugin>
By default, when using EasyBeans plugin along the Maven build lifecycle, the following files are deployed:
All deployables archives included in ${basedir}/target folder.
Local repository installed archetypes related to current POM artifact.
If you want to deploy more archives, you must add them to the POM configuration as explained in the "Using additional resources" section.
You can include some additional files to deploy with your project to test it.
There are four ways to declare files that need to be deployed:
Give an URL.
<urls> <url>http://www.easybeans.net/maven-plugin/files/ejb-project.jar</url> </urls>
Give a file path.
<files> <file>./resources/additional-files/ejb-project1.jar</file> <file>./resources/additional-files/ejb-project2.jar</file> </files>
Give an absolute directory path. The directory will be scanned to deploy all files included in.
<directories> <directory>./resources/additional-files/</directory> </directories>
Give a maven project artifact. In this case, all artifact information tags are required.
<artifacts> <artifact> <groupId>org.ow2.easybeans.maven-easybeans-plugin-examples</groupId> <artifactId>EJB-project</artifactId> <version>1.0</version> <type>ear</type> </artifact> </artifacts>
Additional files configurations needs to be declared in the EasyBeans plugin POM declaration.
Here is a complete declaration to deploy two files from the .resources/additional-files/ folder and a maven project artifact located in the local maven repository.
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <configuration> <deployables> <files> <file>./resources/additional-files/ejb-project1.jar</file> <file>./resources/additional-files/ejb-project2.jar</file> </files> <artifacts> <artifact> <groupId>org.ow2.easybeans.maven-easybeans-plugin-examples</groupId> <artifactId>EJB-project</artifactId> <version>1.0</version> <type>ear</type> </artifact> </artifacts> </deployables> </configuration> <executions> <execution> <id>start-easybeans</id> <phase>pre-integration-test</phase> <goals> <goal>run</goal> </goals> </execution> <execution> <id>stop-easybeans</id> <phase>post-integration-test</phase> <goals> <goal>stop</goal> </goals> </execution> </executions> </plugin>
The list of deployable files to add can be configured as explained in the "Using additional resources" section.
To change the time interval between two re-deployement in millisecond, just add the following code in the configuration tag:
<scanInterval>2000</scanInterval>
This Option is used only if automatic re-deployment is active.
Defines if re-deployment is automatic or manual.
<autoDeployment>false</autoDeployment>
This Option can be set to true or false, but is set to true by default.
This option must not be manually modified. It is related to the behavior of the plugin: bound or not to the Maven build lifecycle. You can set this option at your own risk by using a wait tag set to true or false.
This option is used to set the EasyBeans configuration file path. By default, easybeans-default.xml located in the EasyBeans dependency is used.
Add the following code in the configuration tag if you want to set the ${basedir}/myEZBConfig.xml as the used EasyBeans configuration file.
<serverConfig>${basedir}/myEZBConfig.xml</serverConfig>
This option is used to set if EasyBeans plugin has to deploy project artifact installed in the local Maven repository when this resource is not found in the ${basedir}/target folder.
Add the following code in the configuration tag if you want to set this option true or false:
<checkLocalRepository>true</checkLocalRepository>
All these options must be added in the configuration tag of the plugin POM declaration. Next is a code to set all of these options to specific values in the case of an usage not bound to the Maven build lifecycle.
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <configuration> <deployables> <urls> <url>http://www.easybeans.net/maven-plugin/ejb-project1.jar</url> <url>http://www.easybeans.net/maven-plugin/ejb-project2.jar</url> </urls> </deployables> <scanInterval>2000</scanInterval> <autoDeployment>true</autoDeployment> <wait>true</wait> <serverConfig>${basedir}/myEZBConfig.xml</serverConfig> </configuration> </plugin>
There is two methods to run tests as there are two ways to use EasyBeans plugin.
When you use the plugin along the Maven build lifecycle, tests can be run automatically by using the Maven Surefire plugin. Instructions on how to use this plugin are available here.
So, JUnit tests can be run automatically by adding the following code to the POM configuration:
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <skipTests>true</skipTests> </configuration> <executions> <execution> <phase>integration-test</phase> <goals> <goal>test</goal> </goals> <configuration> <skipTests>false</skipTests> </configuration> </execution> </executions> </plugin>
As we can see, tests are launched during the integration-test phase, just after tested resources are deployed.
Once EasyBeans is started using the Maven command (mvn easybeans:run), tests can be launched manually on deployed EJBs. For example, a client can be launched to test all remote methods.
This client can be an another Maven project launched as a normal Jar project.
This option must be set to the port to contact EasyBeans. This port is 1099 by default.
<stopPort>2055</stopPort>
This option must be set to the hostname where EasyBeans is launched. This hostname is localhost by default.
<hostname>192.168.0.126</hostname>
All these options must be added in the configuration tag of the plugin POM declaration. Next is a code to set all of these options to specific values in the case of an usage bound to the Maven build lifecycle.
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <configuration> <serverConfig>${basedir}/myEZBConfig.xml</serverConfig> </configuration> <executions> <execution> <id>start-easybeans</id> <phase>pre-integration-test</phase> <goals> <goal>run</goal> </goals> </execution> <execution> <id>stop-easybeans</id> <phase>post-integration-test</phase> <goals> <goal>stop</goal> </goals> <configuration> <stopPort>2055</stopPort> <hostname>192.168.0.126</hostname> </configuration> </execution> </executions> </plugin>
Configuration tag can be added in the plugin tag and/or in the goal execution tag.
This tutorial explains how to create a simple EJB project and how to test it automatically with the EasyBeans plugin.
The only required configuration is to have Maven 2 installed and an internet connection.
On to creating an Ejb project! In order to create the Calculator Maven project, execute the following from the command line:
mvn archetype:create \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=org.ow2.easybeans.maveneasybeansplugin.myapps \ -DartifactId=Calculator \ -Dversion=1.0-SNAPSHOT
Once you have executed this command, you will notice a few things have happened. First, you will notice that a directory named Calculator has been created for the new project, and this directory contains a file named pom.xml that should look like this:
<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>org.ow2.easybeans.maveneasybeansplugin.myapps</groupId> <artifactId>Calculator</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>Calculator</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> </project>
To create an EJB project, packaging must be set to ejb and a dependency must be added. Moreover, we change JUnit version from 3.8.1 to 4.2 to test our EJBs.
<packaging>ejb</packaging> ... <dependencies> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>4.2</version> <scope>test</scope> </dependency> <dependency> <groupId>org.ow2.spec.ee</groupId> <artifactId>ow2-ejb-3.0-spec</artifactId> <scope>compile</scope> </dependency> </dependencies> ...
Now, we must add build configurations to build a J2EE project.
<build> <plugins> <plugin> <artifactId>maven-compiler-plugin</artifactId> <version>2.0.2</version> <configuration> <source>1.6</source> <target>1.6</target> </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-ejb-plugin</artifactId> <configuration> <ejbVersion>3.0</ejbVersion> </configuration> </plugin> </plugins> </build>
At this step, the EJB project can be build.
The HelloWorld bean is divided into two parts: the business interface, and the class implementing this interface.
For the example, the interface declares only one method: add(int a, int b)
Copy the following code into a file named CalculatorInterface.java located in the org.ow2.easybeans.maveneasybeansplugin.myapps package.
package org.ow2.easybeans.maveneasybeansplugin.myapps; /** * Interface of the Calculator example. * @author Julien Blais */ public interface CalculatorInterface { /** * Returns a + b. */ int add(int a, int b); }
Even if this interface is used as a remote interface, it does not need to extend java.rmi.Remote interface.
The following code implements the existing interface.
This bean will be a stateless session bean, thus the class will be annotated with @Stateless annotation.
In addition, the interface must be a remote interface to be available for remote clients. This is done by using the @Remote annotation.
package org.ow2.easybeans.maveneasybeansplugin.myapps; import javax.ejb.Remote; import javax.ejb.Stateless; /** * Business code for the Calculator interface. * @author Julien Blais */ @Stateless @Remote(CalculatorInterface.class) public class CalculatorBean implements CalculatorInterface { /** * Add method implementation */ public int add(int a, int b) { return a + b; } }
Here is an example of a test class to test the Calculator. Note how the JNDI name of the bean is set by EasyBeans by default when deployed.
package org.ow2.easybeans.maveneasybeansplugin.myapps; import java.util.Hashtable; import javax.naming.Context; import javax.naming.InitialContext; import javax.naming.NamingException; import org.junit.Test; import static org.junit.Assert.assertTrue; /** * * @author Julien */ public class CalculatorTest { /** * JNDI name of the bean. */ private static final String JNDI_NAME = "org.ow2.easybeans.maveneasybeansplugin.myapps.CalculatorBean" + "_" + CalculatorInterface.class.getName() + "@Remote"; /** * EJB to test. */ private static CalculatorInterface calc = getEJB(); /** * Rigourous Test :-) for Calculator. */ @Test public void testDirectory() { try { System.out.println("[Start testing Calculator Ejb's]"); int a = 13; int b = -36; int result = calc.add(a, b); assertTrue(result == (a + b)); System.out.println("[End testing Calculator Ejb's]"); } catch (Exception ex) { ex.printStackTrace(); } } /** * Get the Calculator EJB interface. * @return Interface of EJB */ private static CalculatorInterface getEJB() { CalculatorInterface calculator = null; try { System.setProperty("java.rmi.server.useCodebaseOnly", "true"); Context initialContext = getInitialContext(); calculator = (CalculatorInterface) initialContext.lookup(JNDI_NAME); } catch (NamingException ex) { ex.printStackTrace(); } return calculator; } /** * Get Initial Context. * @return smartFactory initialised context * @throws NamingException naming exception */ private static Context getInitialContext() throws NamingException { Hashtable<String, Object> env = new Hashtable<String, Object>(); env.put(Context.INITIAL_CONTEXT_FACTORY, "org.ow2.easybeans.component.smartclient.spi.SmartContextFactory"); env.put(Context.PROVIDER_URL, "smart://localhost:2503"); return new InitialContext(env); } }
As seen, we used SmartContextFactory to contact the EJB deployed by EasyBeans. So, we need to depend of this component to run the tests. Just add the following dependency to the POM:
<dependency> <groupId>org.ow2.easybeans</groupId> <artifactId>easybeans-component-smartclient</artifactId> </dependency>
We just need to add the following code to bound the project into the Maven build lifecycle to deploy the EJB and test it:
<plugin> <groupId>org.ow2.easybeans</groupId> <artifactId>maven-easybeans-plugin</artifactId> <version>1.0</version> <executions> <execution> <id>start-maven-plugin</id> <phase>pre-integration-test</phase> <goals> <goal>run</goal> </goals> </execution> <execution> <id>stop-maven-plugin</id> <phase>post-integration-test</phase> <goals> <goal>stop</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <skipTests>true</skipTests> </configuration> <executions> <execution> <phase>integration-test</phase> <goals> <goal>test</goal> </goals> <configuration> <skipTests>false</skipTests> </configuration> </execution> </executions> </plugin>
To test the application, you just need to run the following maven command:
mvn integration-test
EasyBeans starts. Then the Caclulator EJB is deployed and finally, tests are launched and EasyBeans stops.