Deployment and Installation Guide

Target audience

The target audience for this guide is the application deployer.

The content of this guide is the following:

  1. Deployment and installation process principles
  2. Example of deploying and installing an EJB using an ejb-jar file
  3. Deploying and installing a Web application
  4. Deploying and installing a J2EE application

Deployment and installation process principles

The deployment and installation of Enterprise Beans

We suppose here, that the Enterprise Bean provider followed the Enterprise Beans Programmer's Guide, and packed the beans's classes together with the deployment descritors in a ejb-jar file.
In order to deploy the Enterprise Beans in JOnAS, the deployer must add to the ejb-jar file the interposition classes interfacing the EJB components with the services provided by the JOnAS application server.
The GenIC tool provided in the JOnAS distribution allows for generation of interposition classes and update of ejb-jar file.
The application deployer may also need to customize the deployment descriptors in order to adapt it to the operational environment. This must be done before using GenIC.

The deployer may choose to deploy the Enterprise Beans as stand alone application components, or to include them in a war or ear packaging. In the first case, the ejb-jar must be installed in the $JONAS_ROOT/ejbjars directory. The second case is presented below.

The deployment and installation of Web and J2EE applications

Once the packaging of the application components made as presented in the WAR Packaging, or EAR Packaging guides, the obtained archive file must be installed in the:

Example of deploying and installing an EJB using an ejb-jar file

Suppose that we want to customize the deployment of the AccountImpl bean in the JOnAS example examples/src/eb.
The customization wanted will be to change the name of the database table used for the persistence of the AccountImpl.

The current directory is $JONAS_ROOT/examples/src/eb.

Now, you may launch the JOnAS application Server using the command:
  jonas start

We have described step by step all the work to do in order to build the new ejb-jar.jar file, explaining thus the deployment process. In practice you may use the scripts in the $JONAS_ROOT/examples/src/eb directory which perform deployment and installation. These scripts are called compile.sh for unix or compile.bat for Windows.

If jakarta ANT is installed on your machine you can type ant install in the $JONAS_ROOT/examples/src directory to build and install all ejb-jar.jar files for the examples.
In you need to write your own build.xml file for ANT, you can use the ejbjar task which is one of the optional EJB tasks defined in ANT 1.5. The ejbjar task contains a nested element called jonas which implements the deployment process described above (interposition classes generation and EJB-JAR file update).
Currently, we provide for JOnAS 2.6 a new version of the EJB task containing an updated implementation of the jonas nested element. This implementation, that can be found in $JONAS_ROOT/lib/common/ow_jonas_ant.jar, was not yet sumitted to the Jakarta Apache.
As an example, this code snippet is taken from the $JONAS_ROOT/examples/src/alarm/build.xml:
  <!-- ejbjar task -->
  <taskdef name="ejbjar"
     classname="org.objectweb.jonas.ant.EjbJar"
     classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" />

  <!-- Deploying ejbjars via ejbjar task -->
  <target name="jonasejbjar"
    description="Build and deploy the ejb-jar file"
    depends="compile" >
   <ejbjar basejarname="alarm"
      srcdir="${classes.dir}"
      descriptordir="${src.dir}/beans/org/objectweb/alarm/beans"
      dependency="full">
    <include name="**/alarm.xml"/>
    <dtd publicId="-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN"
      location="${jonas.root}/xml/ejb-jar_2_0.dtd" />
    <dtd publicId="-//ObjectWeb//DTD JOnAS 2.5//EN"
      location="${jonas.root}/xml/jonas-ejb-jar_2_5.dtd" />
    <support dir="${classes.dir}">
      <include name="**/ViewProxy.class"/>
    </support>
    <jonas destdir="${dist.ejbjars.dir}" jonasroot="${jonas.root}" orb="${objectweb_orb}" />
   </ejbjar>
  </target>

Deploying and installing a Web application

Before deploying a web application in the JOnAS application server, you must first package its components in a war file as explained in the WAR packaging guide.
In case you use jakarta ANT, take a look at the target war in the $JONAS_ROOT/examples/websample/build.xml file.

The next step is installing the war file into the $JONAS_ROOT/webapps directory.
Note:Become aware that the war file must not be installed in the $CATALINA_HOME/webapps directory !

Then, do some configuration: before running the web application, check that the web service is present in the jonas.services property. The ejb service may also be needed in case the Web application uses enterprise beans.
You may add in the jonas.service.web.descriptors section the name of your war file.

Finaly, run the application Server:
  jonas start

The web components are deployed in a web container created during the startup. If the war file was not added in the jonas.service.web.descriptors list, you can dynamicaly deploy the web components using the jonas admin command or Jadmin tool.

Deploying and installing a J2EE application

Before deploying a J2EE application in the JOnAS application server, you must first package its components in a the ear file as explained in the EAR packaging guide.
In case you use jakarta ANT, take a look at the target ear in the $JONAS_ROOT/examples/earsample/build.xml file.

The next step is installing the ear file into the $JONAS_ROOT/apps directory.

Then, do some configuration: before running the application, check that the ejb, web and ear services are present in the jonas.services property.
You may add in the jonas.service.ear.descriptors section the name of your ear file.

Finaly, run the application Server:
  jonas start

The application components are deployed in EJB and web containers created during the startup. If the ear file was not added in the jonas.service.ear.descriptors list, you can dynamicaly deploy the application components using the jonas admin command or Jadmin tool.