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
.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.
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.
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:
your_install_dir
/JONAS
where your_install_dir
is the directory where you have installed JOnAS,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
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.
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.
This example is a distributed one in which two processes are involved:
For running this example you must:
Run the JOnAS server:
jonas start
the following message is displayed on the standard output:
The JOnAS Server 'jonas' version-number is ready
Make beans available to clients by loading the jar conatining the sb example:
jonas admin -a sb.jar
the following message is displayed on the standard output:
message-header : Op available
Run the java client in another Unix xterm:
jclient sb.ClientOp
Or run the java client in a Windows console:
jclient sb.ClientOp
If you see the following output:
Create a bean
Start a first transaction
First request on the new bean
Second request on the bean
Commit the transaction
Start a second transaction
Rollback the transaction
Request outside any transaction
ClientOp OK. Exiting.
CONGRATULATIONS !!!
You have succeeded to run you first EJB application with JOnAS !
Before ending, don't forget to stop the JOnAS server:
jonas stop
And if you have all forgotten, go to the README file in the working directory.
First of all it is running because the CLASSPATH
is correctly set.
At the JOnAS server launching, the correct setting of the
CLASSPATH
is due to the fact you have used the
jonas
script which itself call the JOnAS bootstrap
class.
To run the client, you have used the jclient
script.
Note that the bean classes have been found in
$JONAS_ROOT/examples/classes
.
If it wasn't the case, you have to call the jclient
script
with the -cp "$JONAS_ROOT/ejbjars/sb.jar"
option.
You may wonder how the client has succeeded to contact JOnAS server.
As you may know the client has got a distributed reference that was previously
registered in the naming service. For this, server and client are using JNDI.
The carol.properties
file (which contains JNDI configuration) is located in
$JONAS_ROOT/conf
directory.
This carol.properties
has the jndi properties set to the default values.
With these default values the registry runs on localhost
on
the default port (1099 for RMI/JRMP).
By default the registry is launched is the same JVM that JOnAS Server.
Here we give a brief description of other examples you can find under
$JONAS_ROOT/example/src
:
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.
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.
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.
mailsb directory contains a SessionMailer and MimePartDSMailer Stateful Session beans with methods providing a way for building and sending mails.
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.
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.
alarm is an application watching alarm messages generated asynchronously through JMS. It involves the different technics used in JOnAS:
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.
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.
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:
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.
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
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.
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.
Here again two processes are involved:
For running this example you must:
Run the JOnAS server to make beans available to clients:
jonas start
jonas admin -a eb.jar
the following messages are displayed on the standard output:
The JOnAS Server 'jonas' version-number is ready and running on rmi
message-header : AccountExpl available
message-header : AccountImpl available
Then run the java clients in another Unix xterm:
jclient eb.ClientAccount AccountImplHome
jclient eb.ClientAccount AccountExplHome
Or run the java clients in Windows console:
jclient eb.ClientAccount AccountImplHome
jclient eb.ClientAccount AccountExplHome
If you see the following output:
Getting a UserTransaction object from JNDI
Connecting to the AccountHome
Getting the list of existing accounts in database
101 Antoine de St Exupery 200.0
102 alexandre dumas fils 400.0
103 conan doyle 500.0
104 alfred de musset 100.0
105 phileas lebegue 350.0
106 alphonse de lamartine 650.0
Creating a new Account in database
Finding an Account by its number in database
Starting a first transaction, that will be committed
Starting a second transaction, that will be rolled back
Getting the new list of accounts in database
101 Antoine de St Exupery 200.0
102 alexandre dumas fils 300.0
103 conan doyle 500.0
104 alfred de musset 100.0
105 phileas lebegue 350.0
106 alphonse de lamartine 650.0
109 John Smith 100.0
Removing Account previously created in database
ClientAccount terminated
You have succeeded to the example eb.
Before ending don't forget to stop the JOnAS server:
jonas stop