# 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. If you need to deploy un-packed Enterprise Beans, see Configuring EJB Container service.

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:

- `$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

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

- 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`
- Do 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`
  - Back to the source directory run the GenIC generation tool that will generates 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`

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 project. Here is 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"/>`
`<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/earsample/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.