# Deployer's Guide

## Target audience

The target audience for this guide is the deployer. The deployer is responsible for the deployment of Enterprise Beans and their containers in the EJB server.

## Deployment process description

The deployment process consists of:

- Customizing the deployment descriptor of the bean in order to adapt it to the specific operational environment.
- Generating the container classes.

Deployment descriptors are written in XML, the deployer must use its favorite XML editor for editing it and the GenIC tool (provided with the JOnAS distribution) for the container classes generation process.

There is two XML deployment descriptors:

- the standard deployment descriptor respecting the deployment descriptor's XML DTD defined in the EBJ specification version 2.0 (See $JONAS_ROOT/xml/ejb-jar_2_0.dtd), and
- the JOnAS specific deployment descriptor respecting the deployment descriptor's XML DTD (See $JONAS_ROOT/xml/jonas-ejb-jar_X_Y.dtd).
  The file's name of this specific deployment descriptor must be the file's name of the standard deployment descriptor prefixed by `jonas-`.

## Example deploying using deployment descriptor in XML

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.
- The GenIC generation tool can be run explicitely via the command:
  `GenIC -d ../../classes ejb-jar.xml`
  or via:
  `make`
- Running the EJB Server:
  Make sure the property `jonas.service.ejb.descriptors` is set to `ejb-jar.xml` in the jonas.properties file.
  `EJBServer`

## Example deploying using ejb-jar file

Back to the previous example

- 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`
- 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 it in the `$JONAS_ROOT/ejbjars` directory:
  `cp ../../classes/eb/ejb-jar.jar $JONAS_ROOT/ejbjars/ejb-jar.jar`
- Running the EJB Server:
  Make sure the property `jonas.service.ejb.descriptors` is set to `ejb-jar.jar` in the jonas.properties file.
  `EJBServer`

We have described step by step all the work to do to build the `ejb-jar.jar` file in order to explain all the process.

In fact in the `$JONAS_ROOT/examples/src/eb` directory there is a script `compile.sh` for unix or `compile.bat` for Windows that you can use.

If the GNU make is installed on your machine you can use the Makefile file you find in this directory.
You only have to type `make install` and all the process to build the `ejb-jar.jar` file and install it in the `$JONAS_ROOT/ejbjars` directory will be made.
In your real application you will have the choice to write your own script that will looks like the `compile.sh` or `compile.bat`, or to write a `Makefile` file that use the common makefile rules that are provided in the JOnAS distribution.
It is quite easy to understand how to change the `Makefile` file for your own purpose:

- You have to choose what name you want to give at your ejb-jar file. If you choose, for example, to build the `Foo.jar` file set the variable `EJBJARS`:
  `EJBJARS = Foo`
- In this case, the deployment descriptors files names must be `Foo.xml` and `jonas-Foo.xml`.
- Then give the list of the classes that must be in the `Foo.jar` file.
  `Foo_CLASSES = Bar BarBean BarHome`
- Then give the list of the classes that must be compiled.
  `CLASSES = $(Foo_CLASSES) ClientBar`
- Set the `ROOT` variable and `JAVAPACKAGE`. The first depend of the location of your working directory, the second is the name of the java package.
- That's all.
- `make install` allows you to build your `Foo.jar` file and install it in `$JONAS_ROOT/ejbjars` directory.