Copyright © 2008-2009 OW2 Consortium
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
People who were familiar with the JOnAS world will not be amazed. However, they should be aware of some important changes that must be taken into account.
Here is a small table describing the differences:
|API||JOnAS 4.x||JOnAS 5.x|
|JavaBeans Activation Framework||1.0||1.1.1|
A JDK 5 is required to build JOnAS 5 but JDK 6may be used for running JOnAS 5.
Usually, an application environment is composed of one JONAS_ROOT (JOnAS distribution) and one or more JONAS_BASE depending on the number of JOnAS instances needed for the application.
In JOnAS 4.x JONAS_BASE contains :
An application consists of several deployable archives: ear, ejbjar, war + some associated connectors packaged in rar archives.
All configuration files are located under
Some libraries may be installed under:
(libraries whoses classes are made available to all JOnAS services)
For a successful upgrade you must be aware of the JOnAS changes in :
the class loader hierarchy see Understanding class loader hierarchy for a complete description of the classloader mechanism.
deployment process, due to a new deployment architecture
third party libraries processing
To upgrade an application environment you must first create a new application environment and then customize it according to the old environment.
To create a new application environnement you must create a new JOnAS_BASE.
To create a JONAS_BASE template from scratch :
export JONAS_BASE=~/my_jonas_base cd $JONAS_ROOT/templates/newjb ant -f build-jb.xml create_jonas_base
set JONAS_BASE=my_jonas_base cd %JONAS_ROOT%/templates/newjb ant -f build-jb.xml create_jonas_base
This will copy all the required files and create all the needed directories.
Another way to create a JONAS_BASE template from scratch :
$JONAS_ROOT/bin must be set in the system
export JONAS_BASE=~/my_jonas_base newjb
set JONAS_BASE=my_jonas_base newjb
In order to customize a JONAS_BASE with specific property values
(port numbers, services, protocols etc...), you must edit the
file before running newjb.
For further customization that cannot be performed by
newjb you should modify the generated files in
$JONAS_BASE/conf. For more information see the
description of the newjb command in Commands Reference
|When running newjb based on information located in your home directory ($HOME/jb.config/conf/jonas-newjb.properties), you will probably have to review this file and upgrade it to conform to $JONAS_ROOT/build-jb.properties syntax. For example, jonas services names have changed between JOnAS version 4 and version 5.|
With JOnAS 5.x, the following deployment directories have been removed :
The above directories no longer exist in JONAS_BASE and have been replaced by a single directory:
To deploy a Java EE
archive in JOnAS 5.x, the only thing required is to put it in the
$JONAS_BASE/deploy directory. This directory is
periodically scanned in order to deploy new archives. 
Deployment plan repositories
Deployment plan resources
For each category, file names are chosen in alphabetical order
Here a basic how to that explains how to create a very simple deployment plan.
This example shows how to control the deployment of two archives which are located on the file system
Myear1.ear and Myear2.ear are located in local directory
Add a new repository element in $JONAS_BASE/conf/initial-repositories.xml:
<?xml version="1.0" encoding="UTF-8"?> <repositories xmlns="http://jonas.ow2.org/ns/deployment-plan/repositories/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="repositories-1.0.xsd"> <!-- Add new repositories here --> <repository id="MyLocalRepository"> <type>url</type> <url>file:/home/elsewhere</url> </repository> <!-- Default repositories --> <repository id="maven2-central"> <type>maven2</type> <url>http://repo1.maven.org/maven2/</url> </repository> <repository id="maven2-ow2-release"> <type>maven2</type> <url>http://maven.ow2.org/maven2/</url> </repository> <repository id="maven2-ow2-snapshot"> <type>maven2</type> <url>http://maven.ow2.org/maven2-snapshot/</url> </repository> </repositories>
create a new deployment plan $JONAS_BASE/deploy/MyDeploymentplan.xml
<?xml version="1.0" encoding="UTF-8"?> <deployment-plan xmlns="http://jonas.ow2.org/ns/deployment-plan/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:url="http://jonas.ow2.org/ns/deployment-plan/url/1.0"> <deployment id="foo1" xsi:type="url:url-deploymentType"> <url:resource>Myear1.ear</url:resource> </deployment> <deployment id="foo2" xsi:type="url:url-deploymentType"> <url:resource>Myear2.ear</url:resource> </deployment> </deployment-plan>
As the deployment plan is under $JONAS_BASE/deploy/ it will be taken into account at server starting time.
For more information see the depmonitor service configuration in the JOnAS Configuration Guide.
The path of the script command files has been changed, and is
$JONAS_ROOT/bin instead of
JOnAS configuration files have changed. Here we will focus on the changes that may impact the upgrade process.
jeremie protocol is no longer supported.
New properties have been added to configure cmi clusters. Note that cmi is not anymore a protocol but a JOnAS service used for clustering.
For applications that uses a carol.properties file on the client side the best practice is to start from $JONAS_ROOT/template/conf/conf/carol.properties and to customize it (see the JOnAS Configuration Guide). .
JOnAS 5 now embeds Tomcat 6 instead of Tomcat 5.
context.xml, server.xml and web.xml
configuration files are replaced by
See Apache Tomcat 6.0 Documentation for more information.
No new properties in this file. The only difference is the name of the package for the LoginModule classes.
For applications that uses a jaas.config on the client side the best practice is to start from $JONAS_ROOT/template/conf/conf/jaas.config and to customize it.
These configuration files are now named
For more information see Jetty Documentation
JOnAS 5 now uses a newer version of JGroups. The JGroups
Protocol Stack configuration files format is different. Therefore
customizations made in the old
jgroups-ha.xml files must be updated to the
jonas.properties file has changed
significantly . Some changes do not impact the upgrade process at all
(package name changes), while others must be studied carefully.
In the following, we focus on the parts of the
jonas.properties file that may be impacted during
the upgrade process.
thread and jms services have been suppressed (see Section 126.96.36.199.3, “jms service configuration” below).
ejb service has been renamed to ejb2 service.
ws service has been renamed to jaxrpc service.
wm, wc, ha, ejb3, versioning, depmonitor, cmi,resourcemonitor,jaxws and smartclient are new services in JOnAS 5
With JOnAS 5, the default jonas.services properties are set to:
(in order to learn more about these services see the JOnAS configuration_guide)
ejb2 service replaces the previous ejb service.
Configuration of worker threads has been moved from the ejb service configuration to the Work Manager (wm) service configuration.
See the Work Manager configuration part in Section 188.8.131.52.4, “resource service configuration”
The JORAM resource adapter must be used in replacement of the jms service.
In order to use JMS via the JORAM resource adapter
The resource service must be set in the jonas.services property
joram.xml must be deployed (it must
be located under
JORAM port must be configured in
JMS destinations must be defined in
If for tuning purposes, the size and/or the max size of the worker thread pool used for the message driven beans has been set (jonas.service.ejb.minworkthreads, jonas.service.ejb.maxworkthreads properties) you must update the equivalent settings in the Work Manager configuration (see below).
Configuration of worker threads has been moved from resource service configuration to Work Manager (wm) service configuration.
Work Manager configuration:
###################### JOnAS WorkManager service configuration # # Set the name of the implementation class of the wm service jonas.service.wm.class org.ow2.jonas.workmanager.internal.JOnASWorkManagerService # Set the size of the worker thread pool jonas.service.wm.minworkthreads 3 # Set the maximun size of the worker thread pool jonas.service.wm.maxworkthreads 80 # Set the max # of seconds that a thread will wait for work # This is used to shrink the worker thread pool back to minimum jonas.service.wm.threadwaittimeout 60
The property indicating that the current instance is (or is
not) a master server is no longer a discovery
service property, but instead, a
jonas.properties global property
The discovery service supports two implementations. One of them uses JGroups, the other one uses multicast. Multicast is the default..
For more information about configuring discovery service see discovery service configuration.
There are several ways to use libraries in portable Java EE applications :
placing the library JAR file into the WEB-INF/lib directory of the WAR file,
using the Class-Path attribute in the manifest file to reference one or more library JAR files included in the EAR file.
using the Extension-List attribute in the manifest file to reference one or more library JAR files that are not bundled in the EAR file, but are installed in the lib/ext directory of the Java Runtime Environment (JRE)
There is no guarantee that a library installed in JOnAS_BASE/lib/ext and referenced via the Extension-List attribute in the manifest file will be accessible to your application.
It is worth knowing that tomcat 6, embedded in JOnAS 5, tries to resolve extension dependencies for web applications before deploying them, and that it uses the system property catalina.ext.dirs to try and locate libraries.
The JDBC driver can be installed under $JONAS_BASE/lib/ext or packaged into an OSGi™ bundle, we recommend the latest way.
for accessing to the read-only operation of the MEJB
role allowing access for all operation of the MEJB
Unauthorized access is forbidden
This snippet includes all of the elements needed to specify
security roles in the
web.xml file of a web application client of
<security-constraint> <web-resource-collection> <web-resource-name>Protected Area</web-resource-name> <!-- Define the context-relative URL(s) to be protected --> <url-pattern>/*</url-pattern> <!-- If you list http methods, only those methods are protected --> <http-method>DELETE</http-method> <http-method>GET</http-method> <http-method>POST</http-method> <http-method>PUT</http-method> </web-resource-collection> <auth-constraint> <!-- Anyone with one of the listed roles may access this area --> <role-name>mejb-admin</role-name> </auth-constraint> </security-constraint> <!-- Default login configuration uses BASIC authentication --> <login-config> <auth-method>BASIC</auth-method> <realm-name>JOnAS Realm</realm-name> </login-config> <!-- Security roles referenced by this web application --> <security-role> <role-name>mejb-admin</role-name> </security-role>
If the application to port was pointing to JOnAS java internal classes with org.objectweb.jonas.xxx packages, all references to these packages must be replaced by references to org.ow2.jonas.xxx package.
For example if the application is using the authentication mechanism implemented by the class org.objectweb.jonas.security.realm.web.catalina55.JACC in JOnAS 4 this mechanism is now implemented in JOnAS5 by org.ow2.jonas.web.tomcat6.security.Realm.
org.objectweb.jonas.security.realm.web.jetty50.Standard must be changed by org.ow2.jonas.web.jetty6.security.Realm
org.objectweb.jonas.security.auth.callback.LoginCallbackHandler must be changed by org.ow2.jonas.security.auth.callback.LoginCallbackHandler
org.objectweb.jonas.security.auth.spi.JResourceLoginModule by org.ow2.jonas.security.auth.spi.JResourceLoginModule
org.objectweb.jonas.security.auth.spi.ClientLoginModule by org.ow2.jonas.security.auth.spi.ClientLoginModule