$Author: bastafidli $
$Date: 2006/08/27 07:52:11 $
$Revision: 1.8 $
$RCSfile: j2eesetup_jonas.html,v $
This document will help you get started with JOnAS application server supported by OpenSubsystems. It will walk you through obtaining, installing and configuring the application server so that it can be used to run OpenSubsystems components and applications. It also describes how OpenSubsystems can integrate with and utilize transaction manager and connection pools provided by the application server to access your databases.
Official page |
Download |
Documentation
Tested version: JOnAS Application Server 4.6.6
JOnAS Application Server is popular open source application server developed by Objectweb consortium. It is J2EE 1.4 certified and used by many open source projects and commercial clients.
Download the installation package of JOnAS Application Server from the official website. The binary versions are available as either .tgz or .exe files in two flavors. The first one is bundled with Tomcat servlet container while the other one comes with Jetty servlet container. The contents are otherwise the same so grab whichever flavor is the most convenient for the platform you are running on. We recommend to use the graphical installer available in the exe package. The only additional requirement to run JOnAS is to have an up-to-date version of Java on your machine. JOnAS with Tomcat 5.5.x requires at least JDK 1.5 to run while JOnAS with Jetty should run with JDK 1.4. Make sure to get the JDK and not the JRE. Although JOnAS will start with JRE only, you'll experience problems compiling JSP pages. You should also make sure that the JAVA_HOME environment variable is set to point to your JDK installation.
Once Java is installed and setup you can start the graphical installation wizard by doubleclicking on the downloaded exe file. Be aware that if you have already installed previous version of JOnAS in this location the new installation will overwrite the existing files, thus customized configuration files may be lost. It is prudent to save these files before starting the installation process. The wizard will guide you through the installation process on your machine. It is safe to accept all the default options as the installation should correctly detect your Java location and install all the required components.
For more information read the JOnAS installation guide especially if you are not using the automated installation wizard.
Before you can use OpenSubsystems with JOnAS you will have to
configure the persistence layer so that OpenSubsystems can access
your database. Copy the JDBC driver for the database you want
to use into directory
[JONAS_ROOT]/lib/commons/jonas
You should have this driver available if you have followed
the Database Setup instructions.
Next configure settings
required to access your database. You have to include the
default OpenSubsystems configuration file
oss.properties
in JOnAS configuration directory
[JONAS_BASE]/conf
The JONAS_BASE environment variable is by default initialized
to JONAS_ROOT, which is the directory where JOnAS was installed,
but you can change it to point to your own set of configuration
files.
Once the OpenSubsystem configuration file is setup, make sure that the uncommented database related settings in this file match the database you want to use. If you decide to use third party transaction manager or connection pool supported by OpenSubsystems, uncomment them in the configuration file as well. If all the connection pools and transaction managers supported by OpenSubsystems are commented out OpenSubsystems will detect if it is running inside of J2EE server and it will use the transaction management and connection pooling capabilities provided by JOnAS as part of the J2EE implementation.
If the JOnAS connection pool is being used you have to
configure JOnAS data source that matches the database enabled
in the configuration file. In the directory
[JONAS_ROOT]/conf
locate the example datasource configuration file for your
database. The files are named [databaseidentifier].properties.
The database identifier should correspond to your database,
e.g. use db2.properties if you use
IBM DB2 database. In case there
is no such file for your database, use one of the example files
as a template, create a copy of it and rename it to
[your_database_identifier].properties. Copy the file of your
choice to directory
[JONAS_BASE]/conf
if you have explicitely configured JONAS_BASE, otherwise if
you are just using the default installation, you can leave it
in the [JONAS_ROOT]/conf directory.
Open the [databaseidentifier].properties file in your favorite
editor and change it's settings to correspond to the values in
the OpenSubsystems configuration file you have setup
previously. For example, if you have configured OpenSubsystems
to use MySQL database after the change the datasource
configuration section in mysql.properties should look similar
to this:
datasource.name OSSDS
datasource.url jdbc:mysql://localhost/OSS
datasource.classname com.mysql.jdbc.Driver
datasource.username basta
datasource.password fidli
datasource.mapper rdb.mysql
Notice that the datasource-name property should be set to
OSSDS. This is because if no other datasource name is specified
in the requestConnection or setDefaultDataSourceName methods of
org.opensubsystems.core.persist.db.DatabaseConnectionFactory
interface the default connection pool is always looked up for
OSSDS
JNDI datasource name. If your application sets different
default datasource name, adjust this property accordingly.
JOnAS provides two ways how to make the datasources available
to the application, the dbm and the resource services. The dbm
service can directly use the datasource property file you have
previously configured. To utilize this service you just need
to modify file
[JONAS_BASE]/conf/jonas.properties
and change the property jonas.service.dbm.datasources to specify
your datasource. If you have configured the datasource in file
MySQL.properties then the setting in jonas.properties will look
like this:
jonas.service.dbm.datasources MySQL
Unfortunately, a defect (#305029) in JOnAS dbm service, prevents OpenSubsystems to create the user you have configured to use for your datasource if the user doesn't exist yet. If the user does exist because you have created it manually beforehand, you are safe to use the JOnAS dbm service. On the other hand, if you want to take an advantage of the full potential of Open Core and let it fully configure the database including the user you have specified for database connections, you have to use JOnAS resource service.
The resource service requires the datasource to be specified in the form of resource adapter. First, due to the same defect mentioned earlier you will have to change the property specifying the minimal number of connections to 0. Modify your datasource property file like this:
jdbc.minconpool 0
This change will allow JOnAS to configure and initialize the datasource even before OpenSubsystems based application is deployed. The next step is to convert the datasource specified in the property file into resource adapter. JOnAS provides handy tool to do this. On the command line go to the [JONAS_BASE]/conf subdirectory where your property file is located and execute following command
C:\JOnAS-4.6.6\conf>RAConfig -dm -p [datasourcename] %JONAS_ROOT%/rars/autoload/JOnAS_jdbcDM [datasourcename]
where the [datasource] name is the name of your property file without the extenstion, e.g. for datasource accessing MySQL defined in file MySQL.properties the command will be
C:\JOnAS-4.6.6\conf>RAConfig -dm -p MySQL %JONAS_ROOT%/rars/autoload/JOnAS_jdbcDM MySQL
This will create file [datasource].rar (in our example
MySQL.rar). The remaining step is to copy the newly created
resource adapter rar file into
[JONAS_ROOT]\rars\autoload
Once the resource adapter is in place, JOnAS is correctly
configured to provide database access to OpenSubsystems-based
application. You can find more information about this process
in JOnAS
JDBC DataSources configuration guide
Ability to debug applications or subsystems running inside of JOnAS application server is essential during the development and the testing phase. You do not have to do anything special to enable remote debugging with JOnAS since the supplied startup scripts (jonas.bat for Windows or jonas for Unix) provide all the necessary options (-debug, -p, -s). For more information about particular options read the Java application launcher documentation. You can use Eclipse IDE to debug application running under JOnAS that was started in the debug mode. Follow the Debugging Remote Application guide for step by step instructions to configure your environment.
Once OpenSubsystems detects it is running inside of J2EE
application server and no particular controller manager have been
specified, it will by default treat and create controllers as
stateless session EJBs. In order for the application to work
correctly, it is neccessary to setup JOnAS to use Jeremie
communication protocol. Open configuration file
[JONAS_BASE]/conf/carol.properties
in your favorite editor and modify it to match the following
setting:
carol.protocols=jeremie
For more information read the JOnAS Choosing the protocol configuration guide. If you have modified the default OpenSubsystems configuration file oss.properties and specified there a different controller manager (e.g. one, which will instruct OpenSubsystems to do not treat controllers as EJBs even when running inside of J2EE application server and treat them as POJOs instead) then the previously described configuration change can be safely ignored.
The last step is to deploy your application to JOnAS
application server. Locate the jar with EJBs, war or ear file
for the OpenSubsystems-based application or subsystems. To
deploy the standalone EJBs only, copy the .jar file (e.g. for
OpenSubsystems demo application named [subsystemname]-ejb.jar)
to directory
[JONAS_ROOT]/ejbjars/autoload
When deploying web application, copy the .war file to directory
[JONAS_ROOT]/webapps/autoload
Full enterprise application can be deployed by copying the
.ear file to directory
[JONAS_ROOT]/apps/autoload
Remember the name of the file you have deployed, since the
application or subsystem deployed using file [applicationname].ear
or [applicationname].war can be by default accessed using url
http://localhost:8080/[applicationname]/
once the JOnAS application server is started. If you are deploying
one of the default OpenSubsystem demo applications with names
such as [subsystemname].ear, [subsystemname].war,
[subsystemname]-app.ear or [subsystemname]-app.war, the default
url is
http://localhost:8080/[subsystemname]/
At this time you are ready to start JOnAS application server.
On the command line go to the
[JONAS_ROOT]\bin\nt\
directory if you are on Windows or to the
[JONAS_ROOT]\bin\unix
directory if you are on Unix-based system. Once there, execute
the jonas script (jonas.bat if you're on Windows, jonas if you
are on Linux, OS X, or another UNIX-like system). You will see
the list of options you can use with JOnAS:
C:\JOnAS-4.6.6\bin\nt>jonas
No arguments specified.
"jonas start | stop | admin | version | check | -fg | -bg | -win | -n | -debug | -cfgsvc | -cnhost | -cnport"
"Debug mode : jonas start -debug -p <debug-port> [-s <suspend:y/n>]"
Use the command
jonas check
to verify that the environment is correct. If the environment
is correct, JOnAS is ready to be used. You can start JOnAS
using command
jonas start
and optionally use one of the flags described above such as
-fg or -debug. You should see the log messages from all the
JOnAS components as they are deployed and started. It is
possible that you can encounter exceptions, such as:
java.sql.SQLException: User not found: [username you have configured]
...
SEVERE: The connection could not be allocated: User not found: [username you have configured]
The connection could not be allocated: User not found: [username you have configured]
if the database user for the user name you have configured in the configuration file doesn't exist. It is safe to ignore this exception if you have configured your database connections using resource adapter as described earlier, since as the application is deployed, OpenSubsystems creates the user for you and then connects to the database as the specified user. The last message should look similar to this
The JOnAS Server 'jonas' version 4.6.6 is ready
Now you can go to you browser and access url http://localhost:9000/ to verify that the JOnAS server is in fact up and running. The default page has links to a few useful JOnAS resources. You can get a live view of the server by going to the JOnAS Administration Console and login as user jonas with password jonas. To access the deployed application copy the URL http://localhost:9000/[applicationname]/ to your browser address bar and modify it to reference your application.
If you have started jonas using the -fg flag, you can stop the
server just by pressing CTRL+C in its console window. If you
have started JOnAS server on the background, to stop it, you
have to on the command line execute command
jonas stop
