Orion Primer

Orion Primer

$Revision: 4.41 $

This tutorial will show you how to write and run a simple Enterprise JavaBean using the Orion application server (www.orionserver.com). You will be taught how to write and compile a simple session bean and a simple servlet and how to deploy and run these.

Note

This tutorial assumes you are familiar with the basics of EJB and J2EE. If you are not, please read up on these subjects first. See the links at the bottom of this tutorial.

The goal of this tutorial is to show you a fast, easy and sensible way of writing and deploying a simple Enterpise JavaBean manually. Once you know how do this, you may find that you have less trouble doing more complex things.

We will first set up a directory structure, then write some a few .java and .xml files that will form our sample application Hello Planet. We will then use these files to build a J2EE application and finally deploy this application in Orion. If you run into trouble, check out the links at the bottom of this page. If you find any inconsistencies or errors in this document, then please send an email to the author (see the bottom of this page.)

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

Tip: Installing Orion on FreeBSD
If you are running FreeBSD, then you can install Orion by simply installing the www/orion port. This will install JDK 1.2 or 1.3 too, if it not already installed:

Become root (su root)
Go to the directory that contains the www/orion/ port (cd /usr/ports/www/orion/).
Install the port (make install).

This tutorial has the following sections:

Introduction
Step 1: Setup directory structure
Step 2: Write the remote interfaces
Step 3: Write the bean class
Step 4: Write the home interface
Step 5: Write a servlet
Step 6: Write the J2EE application definition
Step 7: Write the EJB deployment descriptor
Step 8: Write the Web deployment descriptor
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

Fast forward: Skip creating source files
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. In this case you only need to download and unpack either one of the following files:

Note that these files already contain the build.xml file, so you won't have to download it in step 9.

First thing we do, is setting up a directory structure that will contain all of the files we write and those we generate. You should create the hello-planet directory somewhere in your home directory, for example as /home/john.doe/hello-planet/ (on UNIX and Linux systems) or C:\hello-planet (on Windows systems).

Create the following directory structure:

hello-planet/ hello-planet/src/ hello-planet/src/java/ hello-planet/src/java/hello/ hello-planet/src/java/hello/ejb/ hello-planet/src/java/hello/web/ hello-planet/etc/

All .java source files will be placed in the src/java/ subdirectory. If your project would contain JPython code as well, you would place it under src/jpython/.

The directory hello-planet/etc/ will contain all the necessary .xml files.

The generated Java .class files will be placed in the lib/java/ subdirectory. This directory will be created automatically during the build process, in step 9.

When archives are created (JAR and ZIP files), they will be placed in the build/ subdirectory. This directory will also be created during the automated build process in step 9.

You can use makedirs.sh (for UNIX and Linux systems) or makedirs.bat (for Windows systems) to create the required directory structure for you.

First thing we should write is an interface that derives from EJBObject and that contains the methods our bean will export.

public interface Hello
extends EJBObject {
   public String sayHello() throws RemoteException
}

Save to your computer
Save Hello.java (view) in your hello-planet/src/java/hello/ejb/ directory.

Now that we have the interface that the clients will use (Hello), we will write a session bean that actually implements that functionality. The session bean must implement the interface SessionBean.

public class HelloBean
extends Object
implements SessionBean

Besides the method sayHello() in the Hello interface, we need to implement the following methods, because the SessionBean interface defines them:

public void ejbActivate()
public void ejbPassivate()
public void ejbRemove()
public void setSessionContext(SessionContext)

Save to your computer
Save HelloBean.java (view) in your hello-planet/src/java/hello/ejb/ directory.

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

Our home interface will be derived from EJBHome. We only need a single method at this time:

public Hello create()

This method provides the caller with an instance that implements the Hello interface.

Save to your computer
Save HelloHome.java (view) in the directory hello-planet/src/java/hello/ejb/.

In order to call the session bean and make the results visible, we will write a small servlet that does exactly that. We will derive the servlet from the base class for HTTP servlets: HttpServlet. When our servlet is initialized, we will let it attempt to get a reference to the home interface of our bean:

// Get the initial JNDI context
Context context = new InitialContext();

// Get a reference to the Hello interface
Object boundObject = context.lookup("java:comp/env/ejb/HelloHome");
HelloHome helloHome = (HelloHome) PortableRemoteObject.narrow(boundObject, HelloHome.class);
_hello = helloHome.create();

When our HTTP servlet is accessed, the method doGet() will be called, which will do the following:

String answer = _hello.sayHello(); out.println("<HTML><BODY bgcolor=\"#FFFFFF\">"); out.println("Time stamp: " + new Date().toString()); out.println("<BR>Hello type: " + hello.getClass().getName()); out.println("<BR>Answer: " + answer); out.println("</BODY>"); out.println("</HTML>");

Save to your computer
Save HelloServlet.java (view) in the directory hello-planet/src/java/hello/web/.

Next, we'll create a J2EE Application Definition file, application.xml. This is an XML file that defines the components of a Java 2 Enterprise Edition application. We will include two modules at this time. One for the session bean, and one for the servlet.

The module for the session bean looks as follows:

<module>
   <ejb>hello-planet-ejb.jar</ejb>
</module>

The module for the web application is:

<module>
   <web>
      <web-uri>hello-planet-web.war</web-uri>
      <context-root>/hello-planet</context-root>
   </web>
</module>

The complete application.xml file looks as follows:

<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN"
                             "http://java.sun.com/j2ee/dtds/application_1_2.dtd">
 
<application>
 
   <!-- The display-name element specifies the human-readable name of this
        application. It is not used to identify the application.  -->
 
   <display-name>Hello Planet</display-name>
 
 
   <!-- The EJB module. All that needs to be specified is the location of the
        EJB JAR file. -->
 
   <module>
      <ejb>hello-planet-ejb.jar</ejb>
   </module>
 
 
   <!-- The web module. The context-root specifies how the web-application can
        be reached from a browser. The web-uri element specifies the location
        of the WAR file that contains the web application. -->
 
   <module>
      <web>
         <web-uri>hello-planet-web.war</web-uri>
         <context-root>/hello-planet</context-root>
      </web>
   </module>
 
</application>

Save to your computer
Save application.xml in the etc/ subdirectory.

We need to write a so-called XML deployment descriptor to 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:

<session> <display-name>The hello.ejb.Hello session bean</display-name> <ejb-name>hello.ejb.Hello</ejb-name> <home>hello.ejb.HelloHome</home> <remote>hello.ejb.Hello</remote> <ejb-class>hello.ejb.HelloBean</ejb-class> <session-type>Stateless</session-type> </session>

Save to your computer
Save ejb-jar.xml in your etc/ subdirectory.

We need a descriptor for the web-part of the application as well. In this file we will specify that we have a servlet hello.web.HelloServlet, as follows:

<servlet> <servlet-name>hello.web.HelloServlet</servlet-name> <description>Servlet that calls the Hello bean</description> <servlet-class>hello.web.HelloServlet</servlet-class> </servlet>

Save to your computer
Save the web.xml file in the etc/ subdirectory.

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

META-INF/ META-INF/application.xml hello-planet-ejb.jar hello-planet-web.war

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

META-INF/ META-INF/ejb-jar.xml hello/ hello/ejb/Hello.class hello/ejb/HelloHome.class hello/ejb/HelloBean.class

The file hello-planet-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 WEB-INF/classes/hello/ WEB-INF/classes/hello/web/ WEB-INF/classes/hello/web/HelloServlet.class

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 to your computer
Save build.xml in your hello-planet/ directory. You should take a look at this file and change any settings if necessary:

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.
The setting build.compiler can be changed to jikes to improve performance, if you installed Jikes, a Java compiler by IBM.

Now go to the hello-planet directory and execute:

ant

This typically takes less than 20 seconds, and it should display output similar to this:

Searching for build.xml ...
Buildfile: /home/ernst/hello-planet/build.xml

init:

prepare:
    [mkdir] Created dir: /home/ernst/hello-planet/lib
    [mkdir] Created dir: /home/ernst/hello-planet/lib/ejb
    [mkdir] Created dir: /home/ernst/hello-planet/lib/ejb/META-INF
    [mkdir] Created dir: /home/ernst/hello-planet/lib/web
    [mkdir] Created dir: /home/ernst/hello-planet/lib/web/WEB-INF
    [mkdir] Created dir: /home/ernst/hello-planet/lib/web/WEB-INF/classes
    [mkdir] Created dir: /home/ernst/hello-planet/lib/j2ee
    [mkdir] Created dir: /home/ernst/hello-planet/lib/META-INF
    [mkdir] Created dir: /home/ernst/hello-planet/build
    [mkdir] Created dir: /home/ernst/hello-planet/build/hello-planet

ejb-classes:
    [javac] Compiling 3 source files to /home/ernst/hello-planet/lib/ejb

ejb-meta-inf:
     [copy] Copying 1 files to /home/ernst/hello-planet/lib/ejb/META-INF

ejb-jar:
      [jar] Building jar: /home/ernst/hello-planet/build/hello-planet-ejb.jar

web-classes:
    [javac] Compiling 1 source file to /home/ernst/hello-planet/lib/web/WEB-INF/classes

web-web-inf:
     [copy] Copying 1 files to /home/ernst/hello-planet/lib/web/WEB-INF

war:
      [jar] Building jar: /home/ernst/hello-planet/build/hello-planet-web.war

j2ee-meta-inf:
     [copy] Copying 1 files to /home/ernst/hello-planet/lib/j2ee/META-INF

ear:
     [copy] Copying 1 files to /home/ernst/hello-planet/lib/j2ee
     [copy] Copying 1 files to /home/ernst/hello-planet/lib/j2ee
      [jar] Building jar: /home/ernst/hello-planet/build/hello-planet.ear
BUILD SUCCESSFUL

Total time: 5 seconds

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

lib/ejb/hello/ejb/Hello.class lib/ejb/hello/ejb/HelloHome.class lib/ejb/hello/ejb/HelloBean.class lib/web/WEB-INF/classes/hello/web/HelloServlet.class build/hello-planet-ejb.jar build/hello-planet-web.war build/hello-planet.ear

Troubleshooting: Ant fails
If running ant results in the error

Could not create task of type: copy because I can't find it in the list of task class definitions

then please update your version of Ant to at least 1.2. You can download the compiled version of Ant 1.2 from http://jakarta.apache.org/builds/jakarta-ant/release/v1.2/bin/.
Otherwise, if you get a compilation error telling you that certain packages cannot be imported because they cannot be found, make sure that the orion.dir setting in your build.xml points to the location where you installed Orion.

To actually install our application, we need to add a line to the server.xml file in our Orion configuration directory (orion/config). Make sure you add it before the closure of the main tag </application-server>. This is the line you should add:

<application name="hello-planet" path="path to ear file" />

In my case the end of the server.xml file now looks like this:

   <application name="hello-planet" path="/home/ernst/hello-planet/build/hello-planet.ear" />
</application-server>

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. Again, place it before the main tag </web-site>:

<web-app application="hello-planet" name="hello-planet-web" root="/hello-planet" />

Everything should work, so let's start Orion. Go to the installation directory of Orion, and execute:

java -jar orion.jar

In my case:

$ cd /usr/local/orion $ java -jar orion.jar

Now open your favourite webbrowser, and point it to:

http://hostname/hello-planet/

In my case I am running the Orion webserver locally. Note that the IP address 127.0.0.1 always points to your own computer. So if you are running Orion on the same computer as the webbrowser, then you should point your browser to:

http://127.0.0.1/hello-planet/

You should now see the output of your servlet.

Tip: Continue exploring Orion
After you finished this tutorial, you may want to try the Orion CMP Primer for an introductory tutorial about EJB's and JSP's.

See the following documents for more information on Orion:

See the following sites for more information on J2EE, EJB and JNDI:

J2EE Homepage (JavaSoft)
Introduction to the J2EE Architecture (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)

For more information about Ant, and to to download it, visit the following web pages:

Ant Homepage (Apache)
Download Ant (Apache)

Things considered for a future release of this document:

Change the session bean to stateful.
Add more explanatory text.
Add documentation in the XML files.

Credits

This tutorial is written by:

Ernst de Haan (ernst@jollem.com)

Comments, additions, questions are welcome. Please include the revision number of this tutorial in your reply. Please redirect your flames to /dev/null.

Thanks go to the following people for their invaluable comments, suggestions and improvements (in no particular order):

Alex Chudnovsky (chud@bigpond.net.au) primary reviewer
Al Fogleson (foglesa@email.uophx.edu)
Poririev Sergey (parf@aha.ru)
David Golpira (golpira@alternatecomputing.com)
Jason Amy (jasona@premier1.net)
Magnus Stenman (magnus@orionserver.com)
Chris Miller (kiwi@vardus.co.uk)
Montebove Luciano (L.Montebove@finsiel.it)
Sebastiaan van Erk (sebster@sebster.com)
Dennis Carroll (Dennis.Carroll@DOT.STATE.MN.US)
Henry Hu (henryh@keystroke.com)
Martijn van Berkum (mvberkum@gx.nl)
Jeff Schnitzer (jeff@infohazard.org)
Christopher R. Spence (vampired@mediaone.net)
Thomas Pluempe (thomanski@gmx.de)
Julian Richardson (JRichardson@softwright.co.uk)
Matthew Neill (matthew.neill@jda.com)

This document was generated from an XML document (tutorial.xml) and then converted to HTML using an XSLT stylesheet (classic.xsl).

$Revision: 4.41 $ $Date: 2001/06/27 10:40:38 $