EasyBeans Maven Plugin User's guide

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 :

The Maven EasyBeans plugin has 4 objectives:

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:

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.

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:

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

Pom parameters for goal run are :

Pom parameters for goal stop are :

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

<pluginGroups>
    <pluginGroup>  
        <groupId>org.ow2.easybeans</groupId>
    </pluginGroup>
</pluginGroups>

mvn easybeans:run

To run EasyBeans with Maven along the build lifecycle, run the integration tests and then stop EasyBeans, the EasyBeans Plugin can be invoked by calling the integration-test phase of the lifecycle.

mvn integration-test

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 :

By default, when using EasyBeans plugin out of the Maven build lifecycle, the following files are deployed:

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:

If you want to deploy more archives, you must add them to the POM configuration as explained in the "Using additional resources" section.

There are four ways to declare files that need to be deployed:

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>

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>

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.

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);
}

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;
    }
}

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);
    }
}

<dependency>
    <groupId>org.ow2.easybeans</groupId>
    <artifactId>easybeans-component-smartclient</artifactId>
</dependency>

<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>

mvn integration-test