Orion CMP Primer

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

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

    This article assumes you are familiar with the topics presented in the Orion Primer. If you are not, please follow the instructions in that article before starting with this article.

    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:

    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.

    Download one of the files and unpack it to create a directory called addressbook with the necessary files in it.

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


    Figure 1: Sketch of the J2EE Application

    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.

3 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
    Listing 1: The directory structure

    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.

4 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
    }
    Listing 2: The Remote interface

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

5 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 implements EntityBean
    Listing 3: The bean class

    This class will need to contain the following things:

      The methods specified by the AddressEntry interface.

      The fields to be persisted (the name, address and city).

      The methods defined in EntityBean interface.

      Extra methods required for an entity bean: ejbCreate and ejbPostCreate.

      The EntityBean interface defines the following methods:

    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"
    Listing 4: Sample console output

    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.

6 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();
    }
    Listing 5: The Home interface

    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 !

7 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>
    Listing 6: The EJB Deployment descriptor

    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.

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


    Figure 2: Web-module visualization

    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:

    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.

9 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>
    Listing 7: The Web-module descriptor

    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.

10 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>
    Listing 8: The J2EE Application descriptor

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

    Save application.xml in the directory addressbook/etc.

11 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
    Listing 9: The Applications .ear file structure

    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
    Listing 10: The EJB-modules .jar file structure

    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
    Listing 10: The Web-modules .war file structure

    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:

12 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" />
    Listing 11: Deploying the Application

    In my case: 


      <application name="addressbook" path="/home/ernst/projects/addressbook/build/addressbook.ear" />
    Listing 12: Sample deployment of the Application

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

13 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" />
    Listing 13: Binding the Web-module

14 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
    Listing 14: Sample Orion output

    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, so I would open my browser to : 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...
    Listing 15: Sample Orion output

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


    Figure 4: The welcome page

    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:


    Figure 5: The list of entries

    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:


    Figure 5: The list of entries revisited

    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.

15 See also

16 Credits

Copyright © 2005 IronFlare AB