35.2 Developing Embeddable Enterprise Bean Applications

35.2.1 Running Embedded Applications

The embedded container, the enterprise bean components, and the client all are executed in the same virtual machine using the same classpath. As a result, developers can run an application that uses the embedded container just like a typical Java SE application, as follows:

java -classpath mySessionBean.jar:containerProviderRuntime.jar:myClient.jar \                                                                                            
com.example.ejb.client.Main

In the above example, mySessionBean.jar is an EJB JAR containing a local stateless session bean, containerProviderRuntime.jar is a JAR file supplied by the enterprise bean provider that contains the needed runtime classes for the embedded container, and myClient.jar is a JAR file containing a Java SE application that calls the business methods in the session bean through the embedded container.

In GlassFish Server, the runtime JAR that includes the classes for the embedded container is glassfish-embedded-all.jar.

35.2.2 Creating the Enterprise Bean Container

The javax.ejb.embedded.EJBContainer abstract class represents an instance of the enterprise bean container and includes factory methods for creating a container instance. The EJBContainer.createEJBContainer method is used to create and initialize an embedded container instance.

The following code snippet shows how to create an embedded container that is initialized with the container provider's default settings:

EJBContainer ec = EJBContainer.createEJBContainer();

By default, the embedded container will search the virtual machine classpath for enterprise bean modules: directories containing a META-INF/ejb-jar.xml deployment descriptor, directories containing a class file with one of the enterprise bean component annotations (such as @Stateless), or JAR files containing an ejb-jar.xml deployment descriptor or class file with an enterprise bean annotation. Any matching entries are considered enterprise bean modules within the same application. Once all the valid enterprise bean modules have been found in the classpath, the container will begin initializing the modules. When the createEJBContainer method successfully returns, the client application can obtain references to the client view of any enterprise bean module found by the embedded container.

An alternate version of the EJBContainer.createEJBContainer method takes a Map of properties and settings for customizing the embeddable container instance:

Properties props = new Properties();
props.setProperty(...);
...
EJBContainer ec = EJBContainer.createEJBContainer(props);

Properties props = new Properties();
props.setProperty(EJBContainer.MODULES, "mySessionBean");
EJBContainer ec = EJBContainer.createEJBContainer(props);

Properties props = new Properties();
File ejbJarFile = new File(...);
props.setProperty(EJBContainer.MODULES, ejbJarFile);
EJBContainer ec = EJBContainer.createEJBContainer(props);

35.2.3 Looking Up Session Bean References

To look up session bean references in an application using the embedded container, use an instance of EJBContainer to retrieve a javax.naming.Context object. Call the EJBContainer.getContext method to retrieve the Context object:

EJBContainer ec = EJBContainer.createEJBContainer();
Context ctx = ec.getContext();

References to session beans can then be obtained using the portable JNDI syntax detailed in Portable JNDI Syntax. For example, to obtain a reference to MySessionBean, a local session bean with a no-interface view, use the following code:

MySessionBean msb = (MySessionBean) 
            ctx.lookup("java:global/mySessionBean/MySessionBean");

35.2.4 Shutting Down the Enterprise Bean Container

From the client, call the close method of the instance of EJBContainer to shut down the embedded container:

EJBContainer ec = EJBContainer.createEJBContainer();
...
ec.close();

While clients are not required to shut down EJBContainer instances, doing so frees resources consumed by the embedded container. This is particularly important when the virtual machine under which the client application is running has a longer lifetime than the client application.