Getting started with JOnAS

 
  1. JOnAS installation
  2. Running a first EJB application
  3. More complex examples

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 :

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:

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:

To run this example:

Understanding why this works

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:


  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:

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:

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:

To run this example: