Orion EJB tutorial

This tutorial is supposed to explain how to make simple enterprise java beans and how to deploy them in the Orion Application Server.

First we will make a simple stateful session bean without using any of the GUI tools.

Making your first Enterprise bean (a stateful session bean)

You need to create 3 Java source files for your bean. An interface for your bean, a home for your bean and the bean itself. Create the files Cart.java, CartHome.java and CartEJB.java.
The Cart.java file defines the interface for your bean. It is an interface and must extend EJBObject. To be able to use the ejb, rmi and util classes we need without fully qualifying the package names lets start with a few imports. To the top of the file, add the following:

import java.util.*;

import javax.ejb.*;

import java.rmi.RemoteException;

After these imports we put the definition of the interface. It should look like:

public interface Cart extends EJBObject

Now we will define the methods of the interface. This example bean will have two methods. These are: void addProduct(String product) and Collection getProducts(). They must both throw RemoteException. These definitions should look like:

public void addProduct(String product) throws RemoteException;

public Collection getProducts() throws RemoteException;

Now the definition of the Cart interface is done. The result should be a Cart.java that looks like this.
Now let us create the CartHome interface. Again we start by importing a few classes:

import java.rmi.RemoteException;

import javax.ejb.*;

The CartHome interface must extend the EJBHome interface. The definition of the CartHome interface will look like this:

public interface CartHome extends EJBHome

The CartHome interface will only contain one method, Cart create(). The create() method must throw CreateException and RemoteException:

public Cart create() throws CreateException, RemoteException;

Now the CartHome is done and should look something like this.
Now let us write the code for the actual bean implementation. This is done in the class CartEJB. This class must implement SessionBean.

public class CartEJB implements SessionBean

The contents of the cart can be a list, for example an ArrayList.

private Collection products = new ArrayList();

The SessionBean interface contains a few methods we must implement. These are:

� public void ejbCreate()

Called when the instance of the bean gets created.

� public void ejbActivate()

Called when the instance of the bean gets activated.

� public void ejbPassivate()

Called when the instance of the bean gets passivated.

� public void ejbRemove()

Called when the instance of the bean gets invalidated.

� public void setSessionContext(SessionContext context)

Gives the bean access to its context/environment.

In this simple bean we don�t care to implement these but just give them empty bodies.

Now we implement the actual functionality of the bean. We implement the methods we earlier definded to be in the interface Cart. These were add() and getProducts().
The method add should just add a product name to the ArrayList:

public void addProduct(String product)

{

�� products.add(product);

}

The method getProducts() should just return the list. ��

public Collection getProducts()

{

�� return products;

}

Now the CartEJB class is all done and should look like this. This means we have now written all classes needed to deploy our ejb. Before doing this just compile the files you just created (note that the ejb.jar in the orion dir needs to be in the classpath when compiling).

Deploying your bean

In this first example we do not use any of the GUI tools, but insted we write everything by hand. This means that we manually create the deployment descriptor for the bean. The descriptor is named ejb-jar.xml and is located in the META-INF directory in the bean directory or in the bean jar. In this case you should create a directory named META-INF in the same directory as you put your class-files and create the file ejb-jar.xml
The ejb-jar.xml file is in XML format, so let's first specify the XML format and the DTD:

The ejb-jar.xml has a root tag called <ejb-jar>. Enclosed by this tag we use a few additional tags (these are not all tags that are available in the dtd. For a full listing, see the EJB 1.1 specification)
1. <display-name> The display name of the jar file (For example "cart jar")
2. <description> The description of the jar file (Enter whatever you like)
3. <enterprise-beans> Contains information about the beans in this jar
  1. <session> Marks that information about a session bean in enclosed
    1. <display-name> The display name of the session bean (Enter whatever you like)
    2. <description> The description of the session bean (Enter whatever you like)
    3. <ejb-name> The name of the EJB that will be used for binding the EJB to the naming context (MyCart).
    4. <home> The name of the EJB home class (CartHome)
    5. <remote> The name of the remote interface of the bean (Cart)
    6. <ejb-class> The name of the EJB class
    7. <session-type> Specifies Stateful or Stateless bean (Stateful in this case)
    8. <transaction-type> Specifies what transaction type to use with this bean. (Let's use Container)
Now the file is done and ready to save. Don't forget to close the tags. Your ejb-jar.xml should now look something like this
in config/ejb.xml add an <ejb-jar>path/to/your/ejb/dir/relative/to/the/config/dir</ejb-jar>.
In config/server.xml make sure that the rmi-config tag is not commented out.
Start Orion (if it is not already running), if you don�t get any errors on startup the bean was deployed successfully.

Building a simple client

1. Now we will build a simple application client to test our bean. Start with creating a file called CartClient.java.

2. As usual we start with some imports:

import java.rmi.RemoteException;

import javax.ejb.*;

import javax.naming.*;

import javax.rmi.PortableRemoteObject;

3. The client is a normal java application so it does not have to extend or implement any class or interface. Simply define it as:

public class CartClient

4. This client will only contain one method, the main method:

public static void main(String[] args)

5. The first thing you have to do to use an EJB is to get the naming context to be able to do lookups:

Context context = new InitialContext();

6. Now, look up the CartHome, narrow it to the right class and create a new Cart (and narrow it too):

Object homeObject = context.lookup("MyCart");

CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject, CartHome.class);

Cart cart = (Cart)PortableRemoteObject.narrow(home.create(), Cart.class);

7. The cart object is now ready to be used. From now on we simply call the methods on the Cart in a normal fashion, for example we could add some products:

cart.addProduct("Shirt");

cart.addProduct("Shoes");

�� or get the contents of the Cart:

Collection products = cart.getProducts();

8. Improvise and let your client do whatever you want. But before you compile you have to make sure the body of your main method is enclosed in a try-block to handle exceptions. Make sure you catch RemoteException (can happen on any remote invocation), NamingException (can occur when looking up the home) and CreateException (can happen when the Cart is created).

9. Now your client is done. An example client can be found here.

10. To be able to look up objects correctly using JNDI we must specify a few things in jndi.properties (you can put this file in the same directory as your client):

java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory

java.naming.provider.url=ormi://localhost

java.naming.security.principal=admin

java.naming.security.credentials=123

The file can also be found here.

11. Now compile your client and run it. Make sure orion/ejb.jar is in your classpath. You have now made and used your first EJB!

Next lesson: A simple Entity bean (coming soon)