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 Database Access
  10. Runing the supplied examples

Different JOnAS Configuration Available

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

jonas-jdk1.1
A "ready to use" JOnAS binary distribution for JDK 1.1.x versions.
jonas-jdk1.2
A "ready to use" JOnAS binary distribution for JDK 1.2.x versions (Java 2)
jonas-src
JOnAS source code, for all JDK versions. 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 tp the JOnAS source code.

Installing JOnAS

All these configurations are available as a zip file (.zip). To unzip the zip files, just go where you want to install jonas, and unzip it:

cd

unzip jonas-xxxx.zip

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

JONAS_ROOT=your_install_dir/jonas_jdk1.2 (or 1.1 if you work on JDK1.1)

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://www.cygnus.com.

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

Depending on the JDK version you use, you will need a set of additional classes that are not part of the jonas distribution. You may install these .jar files everyuwhere, 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 "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.

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.
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.
examples/dd/* Some deployment descriptors that can be used as examples to build your deployment descriptors using our textual format. (See the GenDD Tool, and "Defining the Deployment Descriptor").
lib/jonas.jar JOnAS server classes
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://www.cygnus.com/".

To rebuild jonas from the sources, you just have to run make in objectweb directory.

The equivalent of the binary distribution will be produced in jonas/output. You can update your JONAS_ROOT variable with $OBJECTWEB_HOME/jonas/output if you want to use the jonas you will produce instead of the standard binary version.

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 set the CVSROOT environment variable as follows:

Bourne shells: (sh,bash,ksh,etc) CVSROOT=????; export CVSROOT

Berkeley shells:(csh,tcsh) setenv CVSROOT ????

You can then check out jonas: cvs co jonas

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, for example the "java.naming.provider.url" if each user has its own rmiregistry.

  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 bean files (.ser) 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 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:@::

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

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_2".

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
cp $IDB_HOME/Classes/db/sqlsyntax.txt .
mkdir tmp
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
AccountExpl.txt Account bean deployment descriptor, in textual form, for the bean-managed persistence implementation (AccountExplBean).
AccountImpl.txt Account bean deployment descriptor, in textual form, for the container-managed persistence implementation (AccountImplBean).
AccountExpl.properties List of properties used by the EJB server for that bean with bean-managed persistence. This file is referenced in AccountExpl.txt only.
AccountImpl.properties List of properties used by the EJB server for that bean with container-managed persistence. This file is referenced in AccountImpl.txt only.
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.ksh 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.
Op.txt Op bean deployment descriptor, textual form.
jonas.properties Property file for the EJB server, local to this directory.
compile.ksh Script shell to compile the bean, for users that could not run the gnu make.
Makefile gnu Makefile
ClientOp.java Client for the bean.

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.
  2. Run an EJB server to make beans available to clients :

    cd examples/src/sb

    EJBServer &

  3. Run client program

    java -Djava.naming.provider.url="rmi://hostname:1099" 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 -Djava.naming.provider.url="rmi://hostname:1099" 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 .ser files, or to pass the .ser files to load inside the command line, with -D option.