# Getting started with JOnAS

1. JOnAS installation
   - Locating JOnAS
   - Downloading JOnAS
   - Setting up the JOnAS environment
2. Running a first EJB application
   - JOnAS examples
   - Building the sb example
   - Running the sb example
   - Understanding why this works
3. More complex examples
   - Other JOnAS examples
   - An example with DataBase access
     - 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 guide the user through installing JOnAS and running a first example EJB. Guidance is also provided 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

### Locating JOnAS

The latest stable binary version of JOnAS is located at the following site :

- Objectweb

The binary version and sources are available at this site. The current (or any previous) version of JOnAS sources can be obtained via CVS.

### Downloading JOnAS

The JOnAS download page allows you to choose between the JOnAS latest binary version (standalone or packaged with Tomcat or Jetty) or the latest JOnAS source code.
All of these configurations are available as .tgz files or .exe auto-installable files for windows.

### Setting up the JOnAS Environment

Select a location for JOnAS installation, for example `your_install_dir`.
Be aware that if a previous version of JOnAS is already installed in this location, the new installation will overwrite previous files and configuration files that have been customized may be lost. In this case, it is recommended that these files be saved before re-starting the installation process. Note that it is also recommended to use a different location through the JONAS_BASE environment variable for customizing configuration files as explained in the Configuration Guide.

JOnAS installation consists of unzipping the downloaded files. To begin the installation process, go to the directory under which JOnAS is to be installed (e.g., `your_install_dir`) and unzip the downloaded files. You can use `gunzip` and `tar -xvf` on unix-based systems, or the winzip utility on Windows systems.

Once the JOnAS product is installed, the following two variables must be set in your environment to complete the installation:

- JONAS_ROOT = `your_install_dir`/JONAS where `your_install_dir` is the directory in which JOnAS is installed,
- PATH = $JONAS_ROOT/bin/unix on Unix or with %JONAS_ROOT%\bin\nt on Windows.

When using standalone packages (without Tomcat or Jetty), you must run '`ant install`' in the JOnAS_ROOT directory to rebuild global libraries based on your environment. This must also be done again if your web environment changes (e.g., switching from CATALINA to JETTY). Note that this step is not necessary for JOnAS-Tomcat and JOnAS-Jetty packages.

Additionally, if RMI/IIOP will be used, global libraries must be rebuilt by running '`ant installiiop`' in the JOnAS_ROOT directory. This is valid for all JOnAS packages. Also refer to the Configuration Guide about the communication protocol choice.

JOnAS is now ready to run the first EJB application.

## Running a First EJB Application

### JOnAS examples

There are several examples in the JOnAS distribution under `$JONAS_ROOT/examples/src`. The example located in the `sb` directory should be run first.

This basic example will verify that JOnAS is correctly installed.

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

### Building the sb example

Examples should be built using the Ant build tool. Note that some Ant tasks need an additional `bcel.jar` that can be found on the BCEL site (go to the download area). If you have the Ant build tool installed, you can build the JOnAS examples with the build.xml file found in the $JONAS_ROOT/examples or $JONAS_ROOT/examples/src directories.

### Running the sb example

This a distributed example 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.

To run this example:

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

- The following output should display:
  `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.`
  ``
  If this output displayed, the first EJB application with JOnAS has run successfully.

- Before ending, be sure to stop the JOnAS server:
  `jonas stop`

- These instructions are also located in the README file in the working directory.

### Understanding why this works

- To begin with, the `CLASSPATH` does not need to be set, because, when the JOnAS server is launched, the `jonas` script calls the JOnAS `bootstrap` class, which is in charge of loading all the required classes for JOnAS. Moreover, it is recommended that the CLASSPATH contain the least number of elements possible, to avoid potential conflicts.
  Also, the `jclient` script is being used to run the client. Note that the bean classes were found in `$JONAS_ROOT/examples/classes`. If this had not been the case, it would have been necessary to call the `jclient` script with the `-cp "$JONAS_ROOT/ejbjars/sb.jar"` option.

- The client has succeeded in contacting the JOnAS server because the client has a distributed reference that was previously registered in the naming service. For this, server and client are using JNDI. The `carol.properties` file (which contains JNDI configuration) is located in the `$JONAS_ROOT/conf` directory. This `carol.properties` has the jndi properties set to the default values. With these default values the registry runs on `localhost` on the default port (1099 for RMI/JRMP).
  By default, the registry is launched in the same JVM as the JOnAS Server.

NOTE
  jclient is a script that is used to make it easier the running of a pure java client in a development environment.
  It is not the J2EE compliant way to run a java client which is to use a J2EE container client. Examples of container client may be found in `earsample` and `jaasclient` examples of the JOnAS distribution.

## More Complex Examples

### Other JOnAS examples

Following are brief descriptions of other examples that are located under `$JONAS_ROOT/example/src`:

1. The eb example uses Entity beans.
   The two beans share 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, based on the chosen mode of persistence. It provides both a CMP 1.1 and a CMP 2.0 implementation.

2. The lb example uses Entity bean with local interfaces.
   A session bean, `Manager`, locally manages 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. The jms directory contains a Stateful Session bean with methods performing JMS operations and a pure JMS client message receptor.
   A complete description of this example is here in the JMS User's Guide.

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

5. mdb/samplemdb contains a Message Driven bean that listens 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 the following: 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. Upon receipt of a message, the StockHandlerBean updates the database via the StockBean and sends a message to the Queue inside a global transaction. All of the EJBs are involved in transactions that may commit or rollback.

7. alarm is an application that watches alarm messages generated asynchronously through JMS. It utilizes the different techniques used in JOnAS:

   - an Entity Bean for AlarmRecord, persistent in a DataBase,
   - a Session Bean to allow clients to visualize Alarms received,
   - a 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 a complete J2EE application. This sample is a simple stateful Session bean, with synchronization and security.
   This bean is accessed from a servlet in which the user is authenticated and JOnAS controls access to the methods of the bean. The servlet performs a variety of lookups (resource-ref, resource-env-ref, env-entry, ejb-ref and ejb-local-ref) in the java:comp/env environment to illustrate how the J2EE uniform naming works in the servlets.

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

10. jaasclient contains an example of a JAAS login module that illustrates the different methods for authentication. This applies to a pure Java client.
    There are different callback handlers that demonstrate how to enter identification at a command line prompt, with a dialog box, or without any prompt (where the client uses its own login/password in the code).

The corresponding directories contain a README that explains how to build and run each example.

### An example with DataBase access

The eb example contains two Entity beans that manage `Account` objects.

The two beans share the same interface (Account); one with bean-managed persistence (BMP, explicit persistence), the other with container-managed persistence (CMP, implicit persistence). The default CMP implementation is CMP 1.1. A CMP 2.0 implementation is also provided and its use is described in the the README.

Before running this example:

- 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 your relational database, JOnAS will create and use a DataSource object that must be configured according to the database that will be used.

These DataSource objects are configured via properties files. `$JONAS_ROOT/conf` contains templates for configuring DataSource objects for Oracle, InstantDB, InterBase, McKoi, MySQL or PostgreSQL databases:

- `Oracle1.properties`
- `InstantDB1.properties`
- `InterBase1.properties`
- `McKoi1.properties`
- `MySQL.properties`
- `PostgreSQL1.properties`

Depending on your database, you can customize one of these files with values appropriate for your installation. Then, the property `jonas.service.dbm.datasources` in the `jonas.properties file` must be updated.

For example:
`jonas.service.dbm.datasources Oracle1`
for the `Oracle1.properties` file.

The section "Configuring Database service" in the Configuration Guide provides more details about DataSource objects and their configuration.

### Creating the table in the database

`$JONAS_ROOT/examples/src/eb` contains an SQL script for Oracle, `Account.sql`, and another for InstantDB, `Account.idb`. If your Oracle server is running, or if InstantDB is properly installed and configured, you can 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, 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 appropriate value for your database installation.

You may also add the JDBC driver classes in your CLASSPATH, or copy the classes into `JONAS_ROOT/lib/ext`.

### Building the eb example

The Ant build tool is used to build the JOnAS examples by using the build.xml files located in the $JONAS_ROOT/examples or $JONAS_ROOT/examples/src directories.
To do this, 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.

To run this example:

- 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 the following output displays:
  `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`
  ``
  the example eb. has run successfully.

- Before ending, be sure to stop the JOnAS server:
  `jonas stop`