Installation Guide

  1. Different JOnAS Configuration Available
  2. Installing JOnAS
  3. Prerequired classes
  4. Contents of the JOnAS binary distribution
  5. Contents of the JOnAS source distribution
  6. Recompiling JOnAS from the source
  7. Working on JOnAS source with CVS
  8. Configuring JOnAS environment
  9. Configuring JNDI Environment
  10. Configuring JOnAS and JNDI for Jeremie
  11. Configuring Database Access
  12. Runing the supplied examples

Different JOnAS Configuration Available

You have downloaded one of the following versions of the JOnAS platform, depending if you want JOnAS source code or not:

jonas-binary
A "ready to use" jonas-2-0 binary distribution for JDK 1.2.x versions (Java 2)
jonas-src
JOnAS source code. It is also possible to get a CVS version of JOnAS sources. See "Working on JOnAS sources with CVS".
This file is needed only for those who want to recompile the JOnAS platform, or maybe just have a look to the JOnAS source code.

Installing JOnAS

All these configurations are available as a .tgz file. To unzip these files, just go where you want to install JOnAS, and unzip it. You can use gunzip + tar on unix-like systems, or winzip utility on NT.

After having installed the jonas product, you must set at least these two variables in your environment:

JONAS_ROOT=your_install_dir/jonas_jdk1.2

Update you PATH with $JONAS_ROOT/bin if you want to retrieve easily the JOnAS commands.

Note that your CLASSPATH is no longer to be changed, because this will be done in a configuration file (see below).

Notes for Windows:

JOnAS is provided with a set of commands that are intended to be used in a UNIX system. The Windows users will have to either adapt them for Windows, or use the Cygnus tools that emulate a Unix environment. You can download them at http://sourceware.cygnus.com/cygwin/download.html

Windows NT(R) 4.0 has a registry path restriction of 511 characters. If your current path may become greater, you should remove entries from it prior to installing.

Windows 95 has an AUTOEXEC.BAT path variable restriction of 255 characters. If your current PATH variable or CLASSPATH variable settings may become greater you should remove entries from them prior to installing.

Prerequired classes

You will need a set of additional classes that are not part of the JOnAS distribution. You may install these .jar files everywhere, but /usr/local/lib is a good place, at least for most UNIX systems.

Once you have installed all these prerequisites, you have to configure the file "$JONAS_ROOT/bin/config.env" accordingly with your favorite text editor. You may want to add your own classes at the end of the file. This file will be used by all the JOnAS scripts files, located in the bin directory. In a future version, a configuration tool will be provided to change these values.

NOTE: If you intend to recompile JOnAS from the sources, you do not have to modify this file because it will be generated from make. You will have to modify the configuration makefile instead. See "Recompiling JOnAS from the source".

Contents of the JOnAS binary distribution

In the JOnAS installation directory, you can find:

jonas.properties An auto-documented property file for the JOnAS EJB server.
jndi.properties Example of JNDI property file.
ReleaseNotes.txt Release Notes for this version
java.policy Example of policy file, necessary for JDK1.2
bin/* Executables to run the tools and the EJB server
doc/*.html The JOnAS documentation, in HTML format.
jdoc/* The javadoc documentation for JOnAS classes and tools. Read jdoc/index.html first.
LicenceAgreement.txt License agreement text file.
Oracle1.properties

InstantDB1.properties

PostgreSQL.properties

Templates for datasource property files.
lib/JEREMIE_jonas.jar

lib/RMI_jonas.jar

JOnAS server classes, for Jeremie or RMI
xml/ejb-jar_1_.dtd

xml/jonas-ejb-jar.dtd

DTDs used for JOnAS deployment descriptors
examples/src/eb/* Example of entity beans.
examples/src/sb/* Example of session bean.

Contents of the JOnAS Source Distribution

JOnAS is an open source project. Thus, you can download the source code freely. The source tree can be installed everywhere. You will have to set:

OBJECTWEB_HOME=your_install_directory

Under $OBJECTWEB_HOME, you can find:

build Environment needed to produce JOnAS
jonas JOnAS source code
Makefile A gnu Makefile to compile the whole src distribution.

Recompiling JOnAS from the Sources

JOnAS uses the GNU make utility. You can download it from GNU site: "http://www.gnu.org/software/make/make.html" if you don't have it yet.

For NT users, you have to download cygnus tools that will provide you with a Unix like environment. Look at "http://sourceware.cygnus.com/cygwin/download.html".

First of all, you must set the correct paths for all the jar files included in CLASSPATH. For this, edit the file $OBJECTWEB_HOME/build/gmk/config.mk and follow the instructions at the end of the file.

To rebuild JOnAS from the sources, you just have to run make in objectweb directory:

cd $OBJECTWEB_HOME; make

The equivalent of the binary distribution will be produced in $JONAS_ROOT

Working on Jonas Source Code with CVS

CVS (Concurrent Version System) provides network-transparent source control for groups of developers. It runs on most UNIX systems and Windows NT. You can get more information on http://www.cyclic.com.

Working with CVS allows you to do things like "cvs status" or "cvs diff" and any other read-only cvs commands. However, you will not be allowed to commit changes yourself because it's read only. To start working with CVS on jonas, you must make a "checkout" of the jonas module with a command like this:

cvs -d :pserver:cvs@cvs.objectweb.org:/cvsroot/objectweb login

(passwd is cvs)

cvs -d :pserver:cvs@cvs.objectweb.org:/cvsroot/objectweb co jonas

You can also set your CVSROOT variable instead of using the -d option.

Configuring JOnAS Environment

JOnAS EJB servers are configured with a set of properties defined in files named "jonas.properties". Such files can be found at three different places :

  1. $JONAS_ROOT/jonas.properties

    This file holds all possible properties with their default values.This is the only mandatory file for JOnAS properties. The set of all possible properties is self documented in this file.

  2. $HOME/jonas.properties

    This file is the place where a user can put its own properties.

  3. ./jonas.properties

    This file can be used to configure properties that depend on a particular EJB server. It is placed in the directory where the server is run. The typical usage of this file is to put the list of XML deployment descriptors (.xml) that must be read by EJB server.

An EJB server will read the three possible files in this order (1, 2, 3), each one may overwrite properties defined in a previous file. Finally, it is possible to define properties on the command line: (java -D...).

Configuring JNDI Environment

Acces to JNDI is bound to a jndi.properties file that must be accessible from your CLASSPATH. Such a file is supplied with the JOnAS distribution as example. You must customize it and place it in a directory viewed by your CLASSPATH.

For example, you may just leave the jndi.properties file in JONAS_ROOT and add in your .profile:

export XTRA_CLASSPATH=$JONAS_ROOT

Customization of JNDI consists mainly to change localhost to the hostname where registry will be run, and to choose between rmi and jeremie. You may want to change the standard port number too. In this case, don't forget to run registry with this port number as argument:

registry 12803 &

Configuring JOnAS and JNDI for Jeremie

The following steps are required to change from RMI to Jeremie:

Configuring Database Access

In order to be able to access one or several relational databases (currently Oracle, InstantDB, or PostgreSQL), JOnAS will create and use DataSource objects. You have to configure such a DataSource object according to the database you intend to use for the persistence of a bean. More details about DataSource objects and their configuration is provided in the "Configuring JDBC DataSources" chapter of the "Bean Programmer's Guide".

The subsections below briefly explains how to configure a DataSource object for your database, in order to be able to run the Entity Bean example delivered with the platform.

Configuring Oracle for the supplied example

A template Oracle1.properties file is supplied in the installation directory. This file is used to define a DataSource object, named Oracle1. You must update this template with values proper to your installation. The fields are the following:

datasource.name JNDI name of the DataSource:

The name used in the example is "jdbc_1".

datasource.url The JDBC database URL: for the Oracle JDBC "Thin" driver it is

jdbc:oracle:thin:@hostname:sql*net_port_number:ORACLE_SID

If you are using an Oracle OCI JDBC driver, the URL is

jdbc:oracle:oci7: or jdbc:oracle:oci8:

datasource.classname Name of the class implementing the Oracle JDBC driver:

oracle.jdbc.driver.OracleDriver

datasource.username Database user name
datasource.password Database user password

In order that the EJB platform creates the corresponding DataSource object, you must have its name (Oracle1, not the JNDI name) in your jonas.properties file, on the jonas.datasources line:

jonas.datasources            Oracle1

You may have several DataSource objects defined for an EJB server, in this case, you will have several dataSourceName.properties files, and the list of DataSource names on the jonas.datasources line of the jonas.properties file:

jonas.datasources            Oracle1, Oracle2, InstantDB1

Your Oracle server must be running, and a JDBC driver installed (Oracle JDBC drivers may be downloaded at their Web site). You can then create the table used by the example with the SQL script provided in examples/src/eb/Account.sql. For example:

sqlplus user/passwd

SQL> @Account.sql

SQL> quit

Configuring InstantDB for the supplied example

A template InstantDB1.properties file is supplied in the installation directory. This file is used to define a Datasource object, named InstantDB1. You must update this template with values proper to your installation. The fields are the following:

datasource.name JNDI name of the DataSource:

The name used in the example is "jdbc_1".

datasource.url The JDBC database URL: for InstantDB it is

jdbc:idb=Account.prp

datasource.classname Name of the class implementing the JDBC driver:

jdbc.idbDriver

datasource.username Database user name: not necessary for the InstantDB example.
datasource.password Database user password: not necessary for the InstantDB example.

In order that the EJB platform creates the corresponding DataSource object, you must have its name (InstantDB1, not the JNDI name) in your jonas.properties file, on the jonas.datasources line

jonas.datasources            InstantDB1

InstantDB should have been properly installed and configured, which means that your CLASSPATH should have been updated to access the "sample" InstantDB class. Please set the IDB_HOME environment variable to the InstantDB installation directory. You have to create the Account database using the "sample" utility provided with InstantDB:

cd examples/src/eb
java sample Account.idb

Note: in the recent versions of InstantDB, i.e. starting from 2.0, the sqlsyntax.txt file does not exist anymore, and is not necessary, so in this case you do not have to perform the copy command.

Configuring other databases

The same kind of process can be used for other databases. We supply with JOnAS a template of datasource for PostgreSQL. Not all databases have been tested against JOnAS however.

Running the examples

The examples provided with JOnAS are located in the example directory of your installation. The sub-directories are composed of:

Account entity beans

The src/eb directory is composed of :

Account.java Account bean Remote interface.
AccountHome.java Account bean Home interface.
AccountExplBean.java Account bean implementation, in bean-managed (explicit) persistence.
AccountImplBean.java Account bean implementation, in container-managed (implicit) persistence.
AccountBeanPK.java Primary key class of the Account bean.
ClientAccount.java Client for this bean
ejb-jar.xml standard deployment descriptor, for both beans
jonas-ejb-jar.xml JOnAS specific deployment descriptor
jonas.properties Property file for the EJB server, local to this directory.
Account.sql SQL script for Oracle, used to create the table in the database.
Account.idb SQL script for InstantDB, used to create the table in the database.
Account.prp Configuration file for InstantDB.
compile.sh Script shell to compile the bean, for users that could not run the gnu make
Makefile A gnu Makefile to compile everything

Op session bean

The src/sb directory is composed of:

Op.java Op bean Remote interface.
OpHome.java Op bean Home remote interface.
OpBean.java Op bean implementation.
ejb-jar.xml Standard deployment descriptor for bean Op.
jonas-ejb-jar.xml JOnAS specific deployment descriptor
jonas.properties Property file for the EJB server, local to this directory.
compile.sh Script shell to compile the bean, for users that could not run the gnu make.
Makefile gnu Makefile
ClientOp.java Client for the bean.

Compiling the examples

There are 2 ways to compile these examples:

For NT users, you must use the cygnus package to get the UNIX like stuff.

Running the Session Bean example

  1. Make sure that a rmiregistry is running on your host, with the correct port number defined by the java.naming.provider.url property in your jonas.properties file. You can run the script $JONAS_ROOT/bin/registry.
  2. Run an EJB server to make beans available to clients :

    cd examples/src/sb

    EJBServer &

  3. Run client program .

    . $JONAS_ROOT/bin/config.env # set CLASSPATH

    java sb.ClientOp

Running the Entity Bean example

  1. Make sure that your rmiregistry is still running.
  2. Run the EJB server in the examples/src/eb directory:

    cd examples/src/eb; EJBServer &

  3. Run clients programs

    Since two entity beans are provided for only one client, you must specify which bean is to be used, either the entity bean with bean-managed persistence (AccountExplHome), or the entity bean with container-managed persistence (AccountImplHome). Example for container-managed persistence test:

    java eb.ClientAccount AccountImplHome

Note:
You could run only one EJB server for all beans, session or entity. For that, it is necessary to put a jonas.properties file that contains both .xml files, or to pass the .xml files to load inside the command line, with -D option.