# 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

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 two sites:

- Evidian site
- Objectweb

On both sites 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 may choose between the JOnAS latest binary version for JDK 1.2 and JDK 1.3 or 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. So it is prudent to save these files before starting the installation process.

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 two variables in your environment:

- 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

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.

If the GNU make is installed on your machine, you can build this `sb` example by using the Makefile file you find in this directory.
To do so just type `make install`.

If the Ant 1.4 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 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 to make beans available to clients:
  `EJBServer` (you must be located in the sb directory)
  the following message is displayed on the standard output:
  `EJB container : Op available`

- Run the java client in another Unix xterm:
  `. $JONAS_ROOT/bin/unix/config_env`
  `java sb.ClientOp`

- Or run the java client in a Windows console:
  `config_env`
  `java 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:
  `JonasAdmin -s`

- 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.
  The correct setting of the `CLASSPATH` is due to the fact you have used the `EJBServer` scripts and you have run the `config_env` script before running the client JVM.

- 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/config` 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).
  Now you know where to change properties if you want to configure differently the naming service.
  By default the rmiregistry is launched is the same JVM that JOnAS Server.

- You may wonder how JOnAS has been able to fine the right bean to load. This is due to the fact that we told you to launch the JOnAS server in the sb directory. In this working directory it is able to find a `jonas.properties` file with this line
  `jonas.service.ejb.descriptors sb.jar`
  that asks the JOnAS server to create a container and load in it all the bean described in the `sb.jar` file that is in the `$JONAS_ROOT/ejbjars` directory. You may find more information about JOnAS configuration here.

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

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

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

6. websample contains a simple stateful Session bean, with synchronization and security.
   This bean is accessed from a servlet in Tomcat where the user is authenticated and JOnAS controls access to the methods of the bean.

7. alarm is an application whose watch alarm messages generated asynchronously 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,
   - a service included in EJBServer (AlarmManager),
   - tomcat (for JSP pages and servlets),
   - security.

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 (explicit persistence), the other is with container-managed persistence (implicit persistence).

Before running this example you must:

- configure Database access,
- configure your classpath environment,
- create the table in the database used for this example.

### 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 and you can find in `$JONAS_ROOT/config`:

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

Thoses files are templates for configuring DataSource objects for Oracle, InstantDB, InterBase or PostgreSQL databases.

You can customize 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 have updated `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.

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 variables `IDB_CLASSES` or `ORACLE_CLASSES` or `POSTGRE_CLASSES` or `INTERBASE_CLASSES` variable 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 GNU make is installed on your machine you can build this `eb` example by using the Makefile file you find in this directory. To do so just type `make`.

If the Ant 1.4 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:
  `EJBServer` (you must be located in the eb directory)
  the following messages are displayed on the standard output:
  `EJB container : AccountExpl available`
  `EJB container : AccountImpl available`
  `EJBServer is ready`

- Then run the java clients in another Unix xterm:
  `. $JONAS_ROOT/config/bin/unix/config_env`
  `java eb.ClientAccount AccountImplHome`
  `java eb.ClientAccount AccountExplHome`

- Or run the java clients in Windows console:
  `config_env`
  `java eb.ClientAccount AccountImplHome`
  `java 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:
  `JonasAdmin -s`