Orion Primer

This tutorial will show you how to write and run a simple Enterprise JavaBean using the Orion application server

1 Introduction

    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.

    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:

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

    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.

2 Step 1: Setup directory structure

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

    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.

3 Step 2: Write the remote interfaces

    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 javax.ejb.EJBObject
    {
      public sayHello() throws RemoteException;
    Listing 2: The Remote interface

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

4 Step 3: Write the bean class

    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 implements javax.ejb.SessionBean
      {
    Listing 3: The bean class

    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)
    Listing 4: The implemented methods

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

5 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 HelloBean bean as well.

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


      public Hello create()
    Listing 5: The create method

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

6 Step 5: Write a servlet

    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
        boundOjbect=context.lookup("java:comp/env/ejb/HelloHome");
        HelloHome helloHome=(HelloHome)PortableRemoteObject.narrow(boundObject, HelloHome.class);
        _hello=helloHome.create();
    Listing 6: The Servlet

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


        java.lang.String answer=_hello.sayHello();
        out.println("<HTML><BODY bgcolor=\"#FFFFFF\">");
        out.println("Time stamp: " + new java.util.Date().toString());
        out.println("<BR>Hello type: " + hello.getClass().getName());
        out.println("<BR>Answer: " + answer);
        out.println("</BODY>");
        out.println("</HTML>");
    Listing 7: The Servlets doGet method

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

7 Step 6: Write the J2EE application definition

    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>
    Listing 8: The EJB-module entry in the application.xml file

    The module for the web application is:


    <module>
      <web>
        <web-uri>hello-planet-ejb.war<</web-uri>
        <context-root>/hello-planet</context-root>
      </web>
    </module>
    Listing 9: The Web-module entry in the application.xml file

    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>
    Listing 10: The complete application.xml file

    Save application.xml in the etc/ subdirectory.

8 Step 7: Write the EJB deployment descriptor

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

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

9 Step 8: Write the Web deployment descriptor

    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>
    Listing 12: The Web Deployment descriptor

    Save the web.xml file in the etc/ subdirectory.

10 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 hello-planet.ear to contain the following files and directories: 


      META-INF/
      META-INF/application.xml
      hello-planet-ejb.jar
      hello-planet-web.war
    Listing 13: The EAR structure

    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
    Listing 14: The EJB JAR structure

    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
    Listing 15: The Web WAR 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 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
    Listing 16: Typical Ant output

    This will (should) create the following files. Click on one to download the already compiled class:

    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
    Listing 17: Sample ant error

    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.

11 Step 10: Install the application

    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" />
    Listing 18: The line in server.xml

    The result ending of the server.xml file could look like this: 


      <application name="hello-planet" path="/home/ernst/hello-planet/build/hello-planet.ear" />
    </application-server>
    Listing 19: Sample ending of server.xml

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


      <web-app application="hello-planet" name="hello-planet-web" root="/hello-planet" />
    Listing 20: Web-module binding in dfeault-web-site.xml

13 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

    For exampe:


      $ cd /usr/local/orion
      $ java -jar orion.jar
    Listing 21: Starting Orion

    Now open your favourite webbrowser, and point it to:


      http://hostname/hello-planet/
    Listing 22: Accessing the Web-module

    It is quite comon to be running the Orion server locally. Note that the IP address 127.0.0.1 always points to the local 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/
    Listing 23: Accessing the Web-module at localhost IP

    You should now see the output of your servlet.

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

15 See also

16 Credits

Copyright © 2005 IronFlare AB