Getting started with JOnAS

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

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 :

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

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:

For running this example you must:

Understanding why all this running

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. 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. websample contains a simple stateful Session bean, with synchronization and security.
    This bean is accessed from a servlet in Tomcat or Jetty where the user is authenticated and JOnAS controls access to the methods of the bean.

  8. alarm is an application whose watch alarm messages generated asynchronously JMS. It involves the different technics used in JOnAS:

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

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:

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:

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:

For running this example you must: