Deployment and Installation Guide

Target audience

The target audience for this guide is the application deployer.

The content of this guide is the following:

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

Deployment and installation process principles

The deployment and installation of Enterprise Beans

This guide assumes that the Enterprise Bean provider followed the Enterprise Beans Programmer's Guide and packaged the beans's classes together with the deployment descriptors in a ejb-jar file. To deploy un-packed Enterprise Beans, refer to Configuring EJB Container service.

To deploy the Enterprise Beans in JOnAS, the deployer must add the interposition classes interfacing the EJB components with the services provided by the JOnAS application server.
The GenIC tool supplied in the JOnAS distribution provides the capability of generating interposition classes and updating the ejb-jar file.
The application deployer may also need to customize the deployment descriptors in order to adapt it to a specific operational environment. This must be done before using GenIC.

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

The deployment and installation of Web and J2EE applications

Once the packaging of the application components has been completed as described in the WAR Packaging or EAR Packaging guides, the obtained archive file must be installed in the:

$JONAS_ROOT/webapps directory, for war files
$JONAS_ROOT/apps directory, for ear files

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

For this example, it is assumed that a user wants to customize the deployment of the AccountImpl bean in the JOnAS example examples/src/eb by
changing the name of the database table used for the persistence of the AccountImpl.

The current directory is $JONAS_ROOT/examples/src/eb. The user will do the following:

Edit jonas-ejb-jar.xml and modify the value of the <jdbc-table-name> element included in the <jdbc-mapping> element corresponding to AccountImpl entity.
Compile all the .java files present in this directory:
javac -d ../../classes Account.java AccountImplBean.java AccountExplBean.java AccountHome.java ClientAccount.java
Perform deployment
- Build an ejbjar file named ejb-jar.jar with all the corresponding classes and the two deployment descriptors:
    mkdir -p ../../classes/META-INF
    cp ejb-jar.xml ../../classes/META-INF/ejb-jar.xml
    cp jonas-ejb-jar.xml ../../classes/META-INF/jonas-ejb-jar.xml
    cd ../../classes
    jar cvf eb/ejb-jar.jar META-INF/ejb-jar.xml META-INF/jonas-ejb-jar.xml eb/Account.class eb/AccountExplBean.class eb/AccountHome.class eb/AccountImplBean.class
- From the source directory, run the GenIC generation tool that will generate the final ejb-jar.jar file with the interposition classes:
  GenIC -d ../../classes ejb-jar.jar
Install the ejb-jar in the $JONAS_ROOT/ejbjars directory:
cp ../../classes/eb/ejb-jar.jar $JONAS_ROOT/ejbjars/ejb-jar.jar

The JOnAS application Server can now be launched using the command:
jonas start

The steps just described for building the new ejb-jar.jar file explain the deployment process. It is generally implemented by an ANT build script.

If Apache ANT is installed on your machine, type ant install in the $JONAS_ROOT/examples/src directory to build and install all ejb-jar.jar files for the examples.
To write a build.xml file for ANT, 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).
Generally, the latest version of the EJB task containing an updated implementation of the jonas nested element is provided with JOnAS, in $JONAS_ROOT/lib/common/ow_jonas_ant.jar. Click here for the documentation corresponding to this new version of the jonas nested element.
As an example, this code snippet is taken from the $JONAS_ROOT/examples/src/alarm/build.xml:
  
  <taskdef name="ejbjar"
     classname="org.objectweb.jonas.ant.EjbJar"
     classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" />

  
  <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, first package its components in a war file as explained in the WAR packaging guide.
For Apache ANT, refer to the target war in the $JONAS_ROOT/examples/earsample/build.xml file.

Next, install the war file into the $JONAS_ROOT/webapps directory.
Note: Be aware that the war file must not be installed in the $CATALINA_HOME/webapps directory.

Then, check the 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 if the Web application uses enterprise beans.
The name of the war file can be added in the jonas.service.web.descriptors section.

Finally, 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, the web components can be dynamically deployed using the jonas admin command or JonasAdmin tool.

Deploying and installing a J2EE application

Before deploying a J2EE application in the JOnAS application server, first package its components in an ear file as explained in the EAR packaging guide.
For Apache ANT, refer to the target ear in the $JONAS_ROOT/examples/earsample/build.xml file.

Next, install the ear file into the $JONAS_ROOT/apps directory.

Then, check the configuration: before running the application, check that the ejb, web and ear services are present in the jonas.services property.
The name of the ear file can be added in the jonas.service.ear.descriptors section.

Finally, 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, the application components can be dynamically deployed using the jonas admin command or JonasAdmin tool.