# Getting started with JOnAS

1. JOnAS installation
   - Where to find JOnAS?
   - Downloading JOnAS
   - Setting up JOnAS environment
2. Running your first EJB application
   - JOnAS examples
   - Building the sb example
   - Running the sb example
   - Understanding why all this running
3. More complex examples
   - Other JOnAS examples
   - An example with DataBase
     - Configuring Database access
     - Creating the table in the database
     - Configuring the classpath
     - Building the eb example
     - Running the eb example
4. Using CMP2.0 persistence

The purpose of this tutorial is to explain how to install JOnAS and to guide the user until running a first example of EJB. Then it guides the user for running a more complex example in which an EJB has access to a database.

Additional information about JOnAS configuration may be found here

.

## JOnAS installation

### Where to find JOnAS?

You can find the latest stable binary version of JOnAS on the following site :

- Objectweb

On this site the binary version and sources are available.
You can get the current (or previous) version of JOnAS sources via CVS

### Downloading JOnAS

For downloading JOnAS you have to fill in a form.
Then you can choose between the JOnAS latest binary version or the JOnAS latest source code.
All these configurations are available as .tgz files.

### Setting up JOnAS environment

Choose a location for JOnAS installation for example `your_install_dir`.
Beware that if you have already installed a previous version of JOnAS in this location the new installation will overload previous files and you may loose configuration files that you may have customized. In this situation, it is prudent to save these files before re-starting the installation process. Note that its recommended to use a different location for the customized configuration files as explained in the Configuration Guide.

The installation process consists on unzip the downloaded files under `your_install_dir` directory.
To unzip these files, just go where you want to install JOnAS, and unzip it.
You can use `gunzip jonas2.tgz` and `tar -xvf jonas2.tar` on unix-like systems, or winzip utility on Windows systems.

After having installed the JOnAS product, all you have to do is to set these three variables in your environment:

- OBJECTWEB_ORB = `RMI` or `JEREMIE` depending on the orb you choose,
- JONAS_ROOT = `your_install_dir`/JONAS where `your_install_dir` is the directory where you have installed JOnAS,
- PATH = $JONAS_ROOT/bin/unix on Unix or with %JONAS_ROOT%\bin\nt on Windows.

Since jonas 2.6.1, you must run '`ant install`' in the JOnAS_ROOT directory to rebuild global libraries depending on your environment. This must be done again if you decide to switch orb (from RMI to JEREMIE i.e.) or if you change your web environment (switching from CATALINA to JETTY i.e.)

You are now ready to use JOnAS and run your first EJB application

## Running your first EJB application

### JOnAS examples

You can find several examples in the JOnAS distribution under `$JONAS_ROOT/example/src`, but the first to run is located in the `sb` directory

This is the simplest example, running it, garantees you JOnAS is correctly installed!

In this example a java client accesses a Stateful Session bean, calls the buy method of the bean several times inside the scope of transactions.

### Building the sb example

The simplest way to compile this example is to go under `$JONAS_ROOT/example/src/sb` directory and to use the `compile.sh` shell script on Unix, or the `compile.bat` script on Windows.

It is possible to use the Ant 1.5 build tool for building examples (note that some Ant tasks need an additional `bcel.jar` that can be found on the BCEL site). when the Ant 1.5 build tool is installed on your machine, you can build the JOnAS examples by using the build.xml files you find in $JONAS_ROOT/examples or $JONAS_ROOT/examples/src directories.
To do so just use the `build.sh` shell script on Unix, or the `build.bat` script on Windows. For using Ant to build the examples, the environment variable OBJECTWEB_ORB must be set (to RMI, JEREMIE, or DAVID).

### Running the sb example

This example is a distributed one in which two processes are involved:

- the JOnAS server, in which beans will be loaded, and
- the java client that creates instances of beans and calls business methods on it.

For running this example you must:

- Run the JOnAS server: `jonas start`
  the following message is displayed on the standard output:
  `The JOnAS Server 'jonas' version-number is ready`

- Make beans available to clients by loading the jar conatining the sb example:
  `jonas admin -a sb.jar`
  the following message is displayed on the standard output:
  `message-header : Op available`

- Run the java client in another Unix xterm:
  `jclient sb.ClientOp`

- Or run the java client in a Windows console:
  `jclient sb.ClientOp`

- If you see the following output:
  `Create a bean`
  `Start a first transaction`
  `First request on the new bean`
  `Second request on the bean`
  `Commit the transaction`
  `Start a second transaction`
  `Rollback the transaction`
  `Request outside any transaction`
  `ClientOp OK. Exiting.`
  ``
  CONGRATULATIONS !!! You have succeeded to run you first EJB application with JOnAS !

- Before ending, don't forget to stop the JOnAS server:
  `jonas stop`

- And if you have all forgotten, go to the README file in the working directory.

### Understanding why all this running

- First of all it is running because the `CLASSPATH` is correctly set.
  At the JOnAS server launching, the correct setting of the `CLASSPATH` is due to the fact you have used the `jonas` script which itself call the JOnAS `bootstrap` class.
  To run the client, you have used the `jclient` script. Note that the bean classes have been found in `$JONAS_ROOT/examples/classes`. If it wasn't the case, you have to call the `jclient` script with the `-cp "$JONAS_ROOT/ejbjars/sb.jar"` option.

- You may wonder how the client has succeeded to contact JOnAS server.
  As you may know the client has got a distributed reference that was previously registered in the naming service. For this, server and client are using JNDI. The `jndi.properties` file (JNDI configuration file) is located in `$JONAS_ROOT/conf` directory and this directory is seen via the `CLASSPATH` correctly set.
  This `jndi.properties` has the jndi properties set to the default values.
  With these default values you use the rmiregistry on the `localhost` on the rmiregistry default port (1099).
  By default the rmiregistry is launched is the same JVM that JOnAS Server.

## More complex examples

### Other JOnAS examples

Here we give a brief description of other examples you can find under `$JONAS_ROOT/example/src`:

1. eb example uses Entity beans.
   The two beans shares the same interface (`Account`), one uses bean-managed persistence (explicit persistence), the other uses container-managed persistence (implicit persistence).
   This is a good example for understanding what must be done, or not done, for persistence, depending on the chosen mode of persistence. It provides both a CMP 1.1 and a CMP 2.0 implementation.

2. lb example uses Entity bean with local interfaces.
   A session bean, (`Manager`), manages locally an entity bean (`Manac`) which represents an account.
   This is a good example for understanding what must be done for a local client collocated with an entity bean providing local interfaces.

3. jms directory contains a Stateful Session bean with methods performing JMS operations and a pure JMS client receptor of messages.

4. mailsb directory contains a SessionMailer and MimePartDSMailer Stateful Session beans with methods providing a way for building and sending mails.

5. mdb/samplemdb contains a Message Driven bean listening to a topic and a MdbClient which is a pure JMS Client that sends 10 messages on the corresponding topic.
   This is a very good example for understanding how to write and use message driven beans.

6. mdb/sampleappli contains two Message Driven beans one listening to a topic (`StockHandlerBean`) the other listening to a queue (`OrderBean`), an Entity bean with container managed persistence (`StockBean`) and a Stateless Session bean for creating the table used in the database.
   SampleAppliClient sends several messages on the topic, at receipt of message the StockHandlerBean update the database via the StockBean and sends a message to the Queue inside a global transaction, all the EJBs are involved in transactions that may commit or rollback.

7. alarm is an application watching alarm messages generated asynchronously through JMS. It involves the different technics used in JOnAS:

   - Entity Bean for AlarmRecord, persistent in a DataBase,
   - Session Bean to allow clients to visualize alarm received,
   - Message Driven Bean to catch Alarms,
   - JMS to use a topic where Alarms are sent and received,
   - tomcat or jetty (for JSP pages and servlets),
   - security.

8. earsample contains complete J2EE application. This sample is a simple stateful Session bean, with synchronization and security.
   This bean is accessed from a servlet in where the user is authenticated and JOnAS controls access to the methods of the bean. The servlet perform a suite of lookup in the java:comp/env environment on different way (resource-ref, resource-env-ref, env-entry, ejb-ref and ejb-local-ref) to illustrate that the uniform naming works in the servlets.

9. cmp2 contains an example illustrating most of the concepts of the CMP 2.0.

In all the corresponding directories you will find a README that explains how to build and run the example.

### An example with DataBase

In the eb example you can find two Entity beans that manage `Account` objects.

The two beans shares the same interface (Account), one is with bean-managed persistence (BMP, explicit persistence), the other is with container-managed persistence (CMP, implicit persistence). The default CMP implementation is CMP 1.1, a CMP 2.0 implementation is also provided, see the README for using it).

Before running this example you must:

- configure Database access,
- configure your classpath environment,
- create the table in the database used for this example (BMP and CMP 1.1 only).

### Configuring Database access

In order to be able to access to your relational database, JOnAS will create and use a DataSource object that must be configured according to the database you intend to use.

These DataSource objects are configured via properties files. You can find in `$JONAS_ROOT/conf` templates for configuring DataSource objects for Oracle, InstantDB, InterBase or PostgreSQL databases:

- `Oracle1.properties`,
- `InstantDB1.properties`,
- `InterBase1.properties`,
- `PostgreSQL1.properties`

You can customize one of these files, depending on the database you have, with values proper to your installation. Then you must update the property `jonas.service.dbm.datasources` in the `jonas.properties file`.

For example:
`jonas.service.dbm.datasources Oracle1`
if you decided to use the `Oracle1.properties` file.

You will find in Configuring Database service of the Configuration Guide more details about DataSource objects and their configuration.

### Creating the table in the database

You may find in`$JONAS_ROOT/examples/src/eb` `Account.sql`, `Account.idb`, that are a SQL script for Oracle and another for InstantDB. If your Oracle server is running, or InstantDB properly installed and configured, you can then create the table used by the example (do not create it if you are using CMP 2.0).

Example for Oracle:
`sqlplus user/passwd`
`SQL> @Account.sql`
`SQL> quit`

### Configuring the classpath

The JDBC driver classes must be accessible from the classpath. For that, you must update the `config_env` or `config_env.bat` file.

In this file, set one of the following variables: `IDB_CLASSES`, `ORACLE_CLASSES`, `POSTGRE_CLASSES` or `INTERBASE_CLASSES` with the value proper to your database installation.

### Building the eb example

The simplest way to compile this example is to go under `$JONAS_ROOT/example/src/eb` directory and to use the `compile.sh` shell script on Unix, or the `compile.bat` script on Windows.

If the Ant 1.5 build tool is installed on your machine, you can build the JOnAS examples by using the build.xml files you find in $JONAS_ROOT/examples or $JONAS_ROOT/examples/src directories.
To do so just use the `build.sh` shell script on Unix, or the `build.bat` script on Windows.

### Running the eb example

Here again two processes are involved:

- the JOnAS server in which beans will be loaded and
- the java client that creates instances of beans and calls business methods on it.

For running this example you must:

- Run the JOnAS server to make beans available to clients:
  `jonas start`
  `jonas admin -a eb.jar`
  the following messages are displayed on the standard output:
  `The JOnAS Server 'jonas' version-number is ready and running on rmi`
  `message-header : AccountExpl available`
  `message-header : AccountImpl available`

- Then run the java clients in another Unix xterm:
  `jclient eb.ClientAccount AccountImplHome`
  `jclient eb.ClientAccount AccountExplHome`

- Or run the java clients in Windows console:
  `jclient eb.ClientAccount AccountImplHome`
  `jclient eb.ClientAccount AccountExplHome`

- If you see the following output:
  `Getting a UserTransaction object from JNDI`
  `Connecting to the AccountHome`
  `Getting the list of existing accounts in database`
  `101 Antoine de St Exupery 200.0`
  `102 alexandre dumas fils 400.0`
  `103 conan doyle 500.0`
  `104 alfred de musset 100.0`
  `105 phileas lebegue 350.0`
  `106 alphonse de lamartine 650.0`
  `Creating a new Account in database`
  `Finding an Account by its number in database`
  `Starting a first transaction, that will be committed`
  `Starting a second transaction, that will be rolled back`
  `Getting the new list of accounts in database`
  `101 Antoine de St Exupery 200.0`
  `102 alexandre dumas fils 300.0`
  `103 conan doyle 500.0`
  `104 alfred de musset 100.0`
  `105 phileas lebegue 350.0`
  `106 alphonse de lamartine 650.0`
  `109 John Smith 100.0`
  `Removing Account previously created in database`
  `ClientAccount terminated`
  ``
  You have succeeded to the example eb.

- Before ending don't forget to stop the JOnAS server:
  `jonas stop`