This article will show you how to write and run a simple Container-Managed Persistent Entity Bean using the Orion application server (www.orionserver.com).

Introduction

The Orion Primer showed you how to write, compile and deploy a servlet and a session bean. This article will show you how to write a Container Managed Entity Bean as well as an HTML page and a JSP that you can use to access the entity bean.

We will first draw a sketch of what we are going to build. Then we'll set up a directory structure for this, and write the necessary HTML, JSP and Java files. After that we will build the JAR, WAR and EAR files and deploy them into Orion.
If you have any trouble, see if your question is answered by any of the resources at the bottom of this article. If it's not, try posting your question on the orion-interest mailing list (see the Orion website), or on the IRC channel #java on EFnet.

Before you start, make sure you have downloaded and installed the following software:

• Java Development Kit (1.2 or later)
• Orion (1.0 or later)
• Ant

This article has the following sections:

• Introduction
• Case description
• Step 1: Setup directory structure
• Step 2: Write the remote interface
• Step 3: Write the bean class
• Step 4: Write the home interface
• Step 5: Write the EJB deployment descriptor
• Step 6: Create the front end
• Step 7: Write the Web deployment descriptor
• Step 8: Write the J2EE application definition
• Step 9: Compile and create the .jar, .war and .ear files
• Step 10: Install the application
• Step 11: Bind the web application
• Step 12: Start Orion
• See also
• To do

Instead of following the steps involved to create the necessary source files, you can download all the .java and .xml files at once. This allows you to skip to step 9. addressbook-src.tar.gz (8 KB) addressbook-src.zip (14 KB) Download one of the files and unpack it to create a directory called addressbook with the necessary files in it.

Case description

For this example, we will create a small address book application. Users will be able to list, add, edit and delete address entries. No security will be involved at this time, so all users will be able to perform these operations.

Here's a sketch of what the structure of our J2EE application will be:

The web application will contain the files needed to implement the front end for our address book application. We will create a HTML page to represent the front page, and one JSP per action.

Step 1: Setup directory structure

First thing we do, is set up a directory structure that will contain all of the files we write and those we generate. You should create the addressbook directory somewhere in your home directory, for example as /home/john.doe/projects/addressbook/.

During this exercise we will put all source files in the following directory structure:

addressbook
addressbook/etc
addressbook/src
addressbook/src/java
addressbook/src/java/addressbook
addressbook/src/java/addressbook/ejb
addressbook/src/jsp
addressbook/src/web

All .java source files will be placed under addressbook/src/java. The JSP files will be placed under src/jsp and any .html, .gif, .jpg and .css files will be put in addressbook/src/web.

The directory addressbook/etc will contain all the necessary .xml configuration files.

The generated files will end up in the lib and build directories. We haven't created these directories yet, but our build file will do this for us.

When archives are created, they will be placed under addressbook/build/.

Create the directory structure. You can use makedirs.sh (for UNIX and Linux systems) or makedirs.bat (for Windows and OS/2 systems) to perform this for you. Just run it in the directory where you would like the addressbook directory to be created.

Step 2: Write the remote interface

Now for the back end we will write an interface for your bean, just as we did in the Orion Primer. Again the new interface will be derived from javax.ejb.EJBObject:

public interface AddressEntry extends EJBObject {
   public String getName() throws RemoteException
   public String getAddress() throws RemoteException
   public String getCity() throws RemoteException
   public void setAddress(String newAddress) throws RemoteException
   public void setCity(String newCity) throws RemoteException
}

Save AddressEntry.java (View) in your addressbook/src/java/addressbook/ejb directory.

Step 3: Write the bean class

Again, we have the interface that the clients can use to modify an existing bean. So far there are little differences visible between the session bean developed in the Orion Primer trail, and the entity bean we are developing now.

Now let's look at the entity bean. This is a class that must implement the interface javax.ejb.EntityBean

public class AddressEntryBean
extends Object
implements EntityBean

This class will need to contain the following things:

1. The methods specified by the AddressEntry interface.
2. The fields to be persisted (the name, address and city).
3. The methods defined in EntityBean interface.
4. Extra methods required for an entity bean: ejbCreate and ejbPostCreate.

The EntityBean interface defines the following methods:

• public void ejbActivate()
• public void ejbPassivate()
• public void ejbRemove()
• public void setEntityContext(EntityContext)
• public void unsetEntityContext()
• public void ejbLoad()
• public void ejbStore()

The EJB specification mandates that we add an ejbCreate method too, and a corresponding ejbPostCreate:

• public String ejbCreate(String name, String address, String city)
• public void ejbPostCreate(String name, String address, String city)

Save AddressEntryBean.java (View) in your addressbook/src/java/addressbook/ejb directory.

Note that we have some additional functionality in our bean. We have a class field instanceCount and an instance field tracer. Both are used for tracing calls to our bean's methods. After deploying our bean you will be able to see what methods are called. The console will show something like:

09:55:04 AddressEntryBean[1]: <init>()
09:55:04 AddressEntryBean[1]: setEntityContext("com.evermind.server.ejb.EvermindEntityContext@5b18006768")
09:55:04 AddressEntryBean[1]: ejbActivate()
09:55:04 AddressEntryBean[1]: ejbLoad()
09:55:04 AddressEntryBean[1]: getName() -> "Ernst de Haan"
etc.

For this, the bean uses a class called TraceHelper. You will need this class too.

Save TraceHelper.java (View) in your addressbook/src/java/addressbook/ejb directory.

Step 4: Write the home interface

A home interface is used to create and destroy instances of Enterprise JavaBeans. So we need a home interface for our AddressEntry bean as well.

The home interface will be derived from javax.ejb.EJBHome. We will call it AddressBook:

public interface AddressBook extends EJBHome {

   public AddressEntry create(String name,
                              String address,
                              String city);

   public AddressEntry findByPrimaryKey(String name);

   public Collection findAll();
}

We need to use this interface from our JSP pages to get a reference to an instance of AddressEntry. The home interface we produced will give us three ways of accessing an AddressEntry instance. We can create a new instance using the create() method. We can use the findByPrimaryKey() method to get an entry by primary key, or we can get the set of all address entries by calling findAll.

Save AddressBook.java (View) in your addressbook/src/java/addressbook/ejb directory.

This is all we need to do for our home interface. Orion will create an implementation for this interface that will implement the behaviour we need. Life doesn't have to be complicated !

Step 5: Write the EJB deployment descriptor

We need an XML deployment descriptor that will describe the EJB part of our application.

In the deployment descriptor we describe every Enterprise JavaBean we would like to deploy. In our case, there is only one. This time it's an entity bean:

<entity>
   <display-name>Address book entry</display-name>
   <ejb-name>addressbook.ejb.AddressEntry</ejb-name>
   <home>addressbook.ejb.AddressBook</home>
   <remote>addressbook.ejb.AddressEntry</remote>
   <ejb-class>addressbook.ejb.AddressEntryBean</ejb-class>

   <persistence-type>Container</persistence-type>
   <prim-key-class>java.lang.String</prim-key-class>
   <reentrant>False</reentrant>

   <cmp-field><field-name>name</field-name></cmp-field>
   <cmp-field><field-name>address</field-name></cmp-field>
   <cmp-field><field-name>city</field-name></cmp-field>
   <primkey-field>name</primkey-field>
</entity>

This deployment descriptor specifies a few characteristics for the entity bean, including the fields the EJB container (Orion in this case) should persist and what the primary key is.

Save ejb-jar.xml in your addressbook/etc directory.

Step 6: Create the front end

It is now time to create the files that implement the front end of our application. This is the web module.

We will create a single HTML page as the front page, and 4 JSP files, one per action:

• List entries: List all the current entries in the address book. This JSP will call the other JSP pages. It will query the home interface of the entity bean to get the current entries.
• Add entry: Add an entry to the address book. This JSP will need no parameters. After the user submitted the data, it will be submitted to itself, so this page will handle user input errors as well as the communication with the entity bean. On success it will return the user to the page that lists all the entries.
• Edit entry: Delete an entry from the address book. This JSP will need to be passed the identifier of the address entry to be edited. After submitting it will post to itself, so it will need to handle user input errors too. On success, it will return the user to the page that lists all the entries.
• Delete entry: Delete an entry from the address book. This JSP will need to be passed the identifier of the address entry to be removed. It will display an error if the deletion was unsuccessfull. On success it will display a message saying so. In both cases the user can click a link to return to the list page.

We can visualize this as follows:

The idea of this article is not to teach you how to write JSP's, it helps you get your feet wet. See the links at the bottom of this article for links to more information that will help you improve your skills.

Save index.html (View) in your addressbook/src/web directory. Save these JSP files to your addressbook/src/jsp directory: list.jsp (View) add.jsp (View) edit.jsp (View) delete.jsp (View)

This is all there is to the front end. Take a good look at the code and make sure you get the general idea. The code contains quite some documentation to help you understand what goes on.

Step 7: Write the Web deployment descriptor

The descriptor for our J2EE web module is very simple. With optional things removed it looks like this:

<web-app>
   <welcome-file-list>
      <welcome-file>index.html</welcome-file>
   </welcome-file-list>

   <ejb-ref>
      <ejb-ref-name>ejb/AddressBook</ejb-ref-name>
      <ejb-ref-type>Entity</ejb-ref-type>
      <home>addressbook.ejb.AddressBook</home>
      <remote>addressbook.ejb.AddressEntry</remote>
   </ejb-ref>
</web-app>

The <welcome-file-list> tag specifies that if no file is specified in the URL, then index.html will be served to the web client.

The <ejb-ref> tag specifies that this web module needs the address book entity bean at the JNDI location java:comp/env/ejb/AddressBook. Orion will make sure that our web application will find the home interface there.

Save web.xml in the directory addressbook/etc.

Step 8: Write the J2EE application definition

Now we need to combine the EJB module and the web module into a J2EE application. For this we need to write a J2EE application deployment descriptor. This is an XML file that defines the modules of a Java 2 Enterprise Edition application, and how they should be deployed. In our case we can keep the file very simple:

<application>
   <module>
      <ejb>addressbook-ejb.jar</ejb>
   </module>

   <module>
      <web>
         <web-uri>addressbook-web.war</web-uri>
         <context-root>addressbook-web</context-root>
   </web>
   </module>
<application>

The root tag is <application>, and inside the application we define the two <module>s.

Save application.xml in the directory addressbook/etc.

Step 9: Compile and create the .jar, .war and .ear files

An .ear file is a special form of a ZIP file. It contains a complete deployable J2EE application. We will create a file addressbook.ear to contain the following files and directories:

META-INF/
META-INF/application.xml
addressbook-ejb.jar
addressbook-web.war

The addressbook-ejb.jar file is another special ZIP file, that contains the EJB part of the application. We will put the following files and directories in it:

META-INF/
META-INF/ejb-jar.xml
addressbook/
addressbook/ejb/AddressEntry.class
addressbook/ejb/AddressBook.class
addressbook/ejb/AddressEntryBean.class

The file addressbook-web.war is our third special ZIP file. It contains the Web part of the application. This is what we will put in this file:

WEB-INF/
WEB-INF/web.xml
index.html
list.jsp
add.jsp
edit.jsp
delete.jsp

For this purpose, I have written an Ant build file that will compile all the .java files and create the .jar, .war and .ear files for us.

Save build.xml in your addressbook/ directory.

In this file you may want to change one or two settings:

• The setting orion.dir must point the directory where you installed Orion, in my case: /usr/local/orion. If you installed Orion in D:\Orion, then you would set this to D:\Orion (not something like D:\\Orion or D:/Orion).
• The setting build.compiler can be changed to jikes to improve performance, if you installed Jikes, a Java compiler by IBM.

We are now ready to generate the class files, the web module archive (.war), the EJB module archive (.jar) and the J2EE application archive (.ear).

Go to your addressbook directory and execute: ant

This will (should) create the following files. Click on one to download the files generated on my system:

lib/ejb/addressbook/ejb/AddressEntry.class
lib/ejb/addressbook/ejb/AddressEntryBean.class
lib/ejb/addressbook/ejb/AddressBook.class
build/addressbook-ejb.jar
build/addressbook-web.war
build/addressbook.ear

Step 10: Install the application

To actually install our application, you need to add a line like the following to your server.xml in the Orion configuration directory (orion/config). Make sure you use an absolute path!

<application name="addressbook"
             path="path to ear file" />

In my case:

<application name="addressbook"
             path="/home/ernst/projects/addressbook/build/addressbook.ear" />

Please make sure that the process that will run Orion has write access to the directory that contains the .ear file.

Step 11: Bind the web application

Now we need to bind the web application to the default site. This is done by adding the following line to the file default-web-site.xml in the Orion configuration directory:

<web-app application="addressbook"
         name="addressbook-web"
         root="/addressbook" />

Step 12: Start Orion

Everything should work, so let's start Orion.

Go to the installation directory of Orion, and execute: java -jar orion.jar

You should see some log messages from Orion now. The exact messages depend on your version of Orion and configuration. On my system I got this:

Auto-unpacking /usr/home/ernst/addressbook/addressbook/build/addressbook.ear... done.
Auto-deploying addressbook...
Auto-deploying addressbook-ejb.jar (No previous deployment found)...
Auto-creating table: create table addressbook_ejb_AddressEntry (name char (255) not null primary key, address char (255), city char (255))
done.
Orion/1.2.7 initialized

Now open your favourite webbrowser, and point it to:

http://hostname:port/addressbook/

In my case I am running the Orion webserver on a different computer, that computer has IP address 10.0.0.1, and it runs Orion on port 9000:

http://10.0.0.1:9000/addressbook/

As soon as you access the web module, you should see a message appear in the screen you started Orion in, something like:

Auto-deploying Orion CMP Primer Web Application...

You should see the index.html file in your browser. It will look similar to this:

You can test the JSP pages by clicking on the link. You should see a screen indicating that there are no entries found, similar to the following:

Add entries using the Add entry link. After submitting a new address you will return to the Add address screen until you click the Back to the list link. After adding a few addresses the list page will look similar to this:

When you change anything in one of the deployment descriptors, JSP pages or Java source files, rerun ant to generate a new .ear file. Orion will detect the file has been changed and will redeploy the application.

See also

See the following pages for more information on Orion:

• Orion Website (Orion)
• Orion Support Site (Joseph B. Ottinger)
• Setting up an Application (Orion)
• Orion Tutorials Index (Orion)
• Orion taglibs Tutorial (Orion)
• Orion GUI Tools Tutorial (Orion)
• Orion Servlet 2.3 Filters Tutorial (Orion)

See the following sites for more information on Enterprise JavaBeans (EJB) and Java 2 Enterprise Edition (J2EE):

• J2EE Homepage (JavaSoft)
• J2EE tutorial (JavaSoft)
• EJB tutorial (JavaSoft).
• J2EE Technology Center (JavaSoft)
• Topical index: Enterprise JavaBeans (JavaWorld)
• The JNDI Tutorial (JavaSoft)
• RMI over IIOP (JavaSoft)
• XML DTD for application.xml files (JavaSoft)
• XML DTD for ejb-jar.xml files (JavaSoft)
• XML DTD for web.xml files (JavaSoft)

• Ant Homepage (Apache)
• Download Ant (Apache)

To do

• Elaborate on what CMP is, and what the differences between CMP and BMP are.
• Add a picture for the EJB module.

$Revision: 1.19 $ $Date: 2001/01/30 23:38:55 $