# 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

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

     <!-- 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"/>
          <support dir="${classes.dir}">
    	<include name="**/ViewProxy.class"/>
          </support>
          <jonas destdir="${dist.ejbjars.dir}"
                 jonasroot="${jonas.root}"
                 protocols="${protocols.names}" />
        </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.