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:
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.
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
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.
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.
The Java Naming and Directory Interface (JNDI) must be installed on your host. 3 files are needed: jndi.jar, providerutil.jar, rmiregistry.jar. It may be downloaded from the Sun web site http://java.sun.com/products/jndi/. You don't need this on JDK1.2 since they are part of the JDK.
The EJB 1.1 standard interface must be downloaded from Sun web site at: http://java.sun.com/products/ejb/.
The JDBC 2.0 Standard Extension (binary javax.sql) should be installed on your host. It may be downloaded from the Sun web site http://java.sun.com/products/jdbc/download.html.
The Java Transaction API (JTA) must also be downloaded from the Sun Web site. They are available with the JTA specification at http://java.sun.com/products/jta/. Be careful that, at least for JTA version 1.01, the JTA classes are together with the specification on the Sun web site. Choose "Specification and javadoc help files for JTA interfaces" (Continue button). The JTA classes (.jar) are in the proposed zip file (jta-spec1_0_1.zip).
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".
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 | 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. |
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://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.
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
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, for example the "java.naming.provider.url" if each user has its own rmiregistry.
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...).
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:@ 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
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
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.
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.
Examples of deployment descriptors.
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 beanThe src/sb directory is composed of:
|
cd examples/src/sb
EJBServer &
java -Djava.naming.provider.url="rmi://
cd examples/src/eb; 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 -Djava.naming.provider.url="rmi://