Getting started with JOnAS

 
  1. JOnAS installation
  2. Running your first EJB application
  3. More complex examples
  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 :

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 (standalone or packaged with Tomcat or Jetty) or the JOnAS latest source code.
All these configurations are available as .tgz files or .exe auto-installable files for windows.

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 it is recommended to use a different location through the JONAS_BASE environment variable for customizing configuration files as explained in the Configuration Guide.

The installation process consists in unziping 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 and tar -xvf 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:

Since jonas 2.6.1, and when using standalone packages (without Tomcat or Jetty) 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 change your web environment (switching from CATALINA to JETTY). Of course this step is not necessary for JOnAS-Tomcat and JOnAS-Jetty packages.

Moreover, if you decide to use RMI/IIOP, you have to rebuild global libraries by running 'ant installiiop' in the JOnAS_ROOT directory. This is valid for all JOnAS packages. See also the Configuration Guide about the communication protocol choice.

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/examples/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
(Go to the download area)). 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.

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. 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.
    A complete description of this example is here in the JMS User's Guide.

  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:


  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:

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:

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

For running this example you must: