You have downloaded one of the following versions of the JOnAS platform, depending if you want JOnAS source code or not:
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 your PATH with $JONAS_ROOT/bin/unix on Unix or with %JONAS_ROOT%/bin/nt on Windows, 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:
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.
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/unix/config_env" on Unix (or the file "%JONAS_ROOT%\bin\nt\config_env.bat on Windows) 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/unix or bin\nt 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".
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/unix | Executables to run the tools and the EJB server on Unix |
bin/nt | Executables to run the tools and the EJB server on Windows |
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 | 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 | DTDs used for JOnAS deployment descriptors |
examples/src/eb/* | Example of entity beans. |
examples/src/sb/* | Example of session bean. |
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. |
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.
If you want to rebuild JOnAS on Jeremie instead of RMI you have to set OBJECTWEB_ORB=JEREMIE in your environment.
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
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.
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 :
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.
This file is the place where a user can put its own 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...).
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 in the $JONAS_ROOT directory and by default the CLASSPATH is up to date to access to this file.
The jndi.properties file contents for RMI is:
java.naming.factory.initial com.sun.jndi.rmi.registry.RegistryContextFactory java.naming.provider.url rmi://<hostname>:1099 java.naming.factory.url.pkgs org.objectweb.jonas.naming
The jndi.properties file contents for Jeremie is:
java.naming.factory.initial org.objectweb.jeremie.libs.services.registry.jndi.JRMIInitialContextFactory java.naming.provider.url jrmi://<hostname>:12340 java.naming.factory.url.pkgs org.objectweb.jonas.naming
Customization of JNDI consists to edit the $JONAS_ROOT/jndi.properties file and mainly to change <hostname> 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
The following steps are required to change from RMI to Jeremie:
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.
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
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.
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.
The examples provided with JOnAS are located in the example directory of your installation. The sub-directories are composed of:
Contains a bean called Op. This bean is a simple session bean, stateful, with synchronization.
Contains two beans sharing the same interface (Account), one is with bean-managed persistence (explicit persistence), the other is with container-managed persistence (implicit persistence). This is a good example for understanding what must be done or not for persistence, depending on the mode chosen in the deployment descriptor.
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 beanThe src/sb directory is composed of:
|
There are 2 ways to compile these examples:
cd examples/src/sb EJBServer
. $JONAS_ROOT/bin/config_env # set CLASSPATH java sb.ClientOp
config_env # set CLASSPATH java sb.ClientOp
cd examples/src/sb EJBServer
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