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:

Java Development Kit (1.2 or later)

Orion (1.0 or later)

Ant (1.2 or later)

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

hello-planet-pkg.tar.gz

hello-planet-pkg.zip

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 and that contains the methods our bean will export. public interface Hello extends

{ public

sayHello() throws

}

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 javax.ejb.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 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 . 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 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: . 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

(); // Get a reference to the Hello interface

boundObject = context.lookup("java:comp/env/ejb/HelloHome"); HelloHome helloHome = (HelloHome) .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 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>  <display-name>Hello Planet</display-name>  <module> <ejb>hello-planet-ejb.jar</ejb> </module>  <module> <web> <web-uri>hello-planet-web.war</web-uri> <context-root>/hello-planet</context-root> </web> </module> </application> 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 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 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 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

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

Orion Website (Orion)

Orion Support Site (Joseph B. Ottinger)

Setting up an Application (Orion)

Orion Tutorial Index (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.