$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.
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
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
in JOnAS configuration directory
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
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
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
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
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
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:
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:
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
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
in your favorite editor and modify it to match the following setting:
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)
When deploying web application, copy the .war file to directory
Full enterprise application can be deployed by copying the .ear file to directory
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
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
At this time you are ready to start JOnAS application server.
On the command line go to the
directory if you are on Windows or to the
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
to verify that the environment is correct. If the environment is correct, JOnAS is ready to be used. You can start JOnAS using command
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