OpenSubsystems

Business Components for Java Applications

J2EE Application Server Setup

JOnAS

Last modified

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

JOnAS Application Server 4.6

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.

Installation

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.

Database Configuration
JDBC driver

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.

OpenSubsystems

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.

Data source

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

Server Configuration

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.

Deploying Application

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