Howto: JOnAS Versions Migration Guide

 

The content of this guide is the following:

JOnAS 3.1 to JOnAS 3.1.4

Applications developed for JOnAS 3.1 do not require changes; however, they should be redeployed (GenIC). The migration affects only certain customized configuration files and build.xml files.

The main changes are in the area of communication protocols support, due to the integration of CAROL. This implies the following configuration changes:

Refer to the JOnAS Configuration Guide for details about Communication Protocols configuration.

Other configuration changes are due to security enhancements:

Refer to the JOnAS Configuration Guide for details about Security configuration.

The preferred steps for migrating from JOnAS 3.1 are the following:

  1. Create a new JOnAS_BASE (e.g. through the ANT create_jonasbase target).
  2. Copy the new as well as any customized files from the old JONAS_BASE to the new one, conforming to the new configuration rules (jndi.properties replaced by carol.properties, security context propagation and realm specified in jonas.properties, new realm specification in server.xml, changes in your build.xml files, content of tomcat-users.xml, jonas-users.properties or jettyRealm.properties should migrate into jonas-realm.xml).

Details for migrating a configuration are provided in the following sections.

carol.properties

Modify this file according to the content of the old jndi.properties file. If the OBJECTWEB_ORB was RMI, set carol.protocols to jrmp; if the OBJECTWEB_ORB was JEREMIE, set carol.protocols to jeremie. Then, configure the URL with host name and port number. Example:

        carol.protocols=jrmp
        carol.jrmp.url=rmi://localhost:1099
    

jonas.properties

If EJB security was used, the security context propagation should be activated. A realm resource can be chosen to be accessed from Java; this is now specified in the jonas.properties file:

       jonas.security.propagation              true
       jonas.service.security.ejbrealm         memrlm_1
       jonas.services  registry,jmx,jtm,dbm,security,jms,ejb,web,ear
    

server.xml

Choose the memory, database, or ldap realm resource for Tomcat authentication.

      <Realm className="org.objectweb.jonas.security.realm.JRealmCatalina41" debug="99" 
             resourceName="memrlm_1"/>
    

web-jetty.xml

This file is located in the WEB-INF directory of a WAR file and contains a reference to the JOnAS Realm to be used for authentication.

  <Call name="setRealmName">
    <Arg>Example Basic Authentication Area</Arg>
  </Call>
  <Call name="setRealm">
    <Arg>
      <New class="org.objectweb.jonas.security.realm.JRealmJetty42">
        <Arg>Example Basic Authentication Area</Arg>
        <Arg>memrlm_1</Arg>
      </New>
    </Arg>
  </Call>
    

Deployment

For existing scripts that call GenIC for deploying EJBs, the -secpropag option no longer exists (security propagation is activated from the jonas.properties file as illustrated previously), and a new option -protocols specifies a comma-separated list of protocols (chosen within jeremie, jrmp, iiop, cmi) for which stubs will be generated. The default value is jrmp,jeremie.

      GenIC -protocols jrmp,jeremie,iiop
    

Refer to the following for the deployment ANT task.

build.xml files

The build.xml files for building JOnAS examples have been upgraded according to the new configuration scheme. Existing build.xml files must be updated the same way:

JOnAS 3.0 to JOnAS 3.1

Applications developed for JOnAS 3.0 can be redeployed without any changes.

The differences in the execution environment are the following:

JOnAS is still available as a "single ejb container" as before. Additionally, two new packagings as "J2EE server" are available:

For these two new packagings, it is no longer necessary to set the environment variable CATALINA_HOME or JETTY_HOME. These packagings have JOnAS examples compiled for use with RMI.

The location and the policy for JOnAS configuration has changed:

The location and the policy for deploying applications has changed:

JOnAS 2.6.4 to JOnAS 3.0

Application with entity beans CMP 1.1

The standard deployment descriptor must be updated for applications deployed in previous versions of JOnAS using entity beans that have container-managed persistence CMP 1.1. For such entity beans, a <cmp-version> tag with value 1.x must be added. For example a deployment descriptor that looks like the following:

    <persistence-type>container</persistence-type>
    <cmp-field>
      <field-name>fieldOne</field-name>
    </cmp-field>
    <cmp-field>
      <field-name>fieldTwo</field-name>
    </cmp-field>
    
must be changed as follows:
    <persistence-type>container</persistence-type>
    <cmp-version>1.x</cmp-version>
    <cmp-field>
      <field-name>fieldOne</field-name>
    </cmp-field>
    <cmp-field>
      <field-name>fieldTwo</field-name>
    </cmp-field>
    
The EJB 2.0 specification states that the default value of the <cmp-version> tag is 2.x.

JOnAS 2.6 to JOnAS 2.6.1

Installation procedure

Before using JOnAS when it is installed on a host, the ant install must be run in the JOnAS_ROOT directory to rebuild global libraries based on your environment (RMI/JEREMIE, web environment). This must be run again if the orb (i.e. from RMI to JEREMIE) is switched, or if the web environment (i.e. switching from CATALINA to JETTY) changes.

EJB container creation

It is still possible to create an EJB container from an EJB deployment descriptor identified by its xml file name in JOnAS version 2.6.1 (as required by JOnAS users with versions prior to JOnAS 2.6).

JOnAS 2.5 to JOnAS 2.6

Use of Make discontinued for building

The make tool is no longer used to build JOnAS and the JOnAS examples. Common makefiles previously used to build the JOnAS examples via make are no longer delivered in $JONAS_ROOT/gmk.
Ant is the only build tool used in JOnAS 2.6.

Building with Ant 1.5

In JOnAS 2.6, the required version of Ant is 1.5 (instead of Ant 1.4).
In addition, starting with this version, an ant task ejbjar for JOnAS is delivered in the JOnAS distribution. Refer to the JOnAS example to see how this new task is used.

New jonas command

A new jonas command is delivered that provides the capability to:

The EJBServer, JonasAdmin and CheckEnv commands are now deprecated.
Refer to the JOnAS Commands Reference Guide in the JOnAS documentation for details.

EJB container creation

In previous versions of JOnAS, an EJB container could be created from an ejb-jar file or from an EJB deployment descriptor identified by its xml file name.
In JOnAS version 2.6, an EJB container can only be created from an ejb-jar file.
This means that an xml file name can no longer be specified as:

Tomcat 4.0.x Support

Tomcat version 4.0.1 is no longer supported. The current supported versions are Tomcat 4.0.3 and Tomcat 4.0.4.

Tomcat Service and Web Container Service

JOnAS 2.6 is a full-featured J2EE application server, thus Tomcat can be used with JOnAS as the Web container. This functionality is set up via the JOnAS service web. In earlier version of JOnAS, a service tomcat was provided. This service tomcat is now deprecated because it was not compliant with J2EE specification. Note that if the tomcat service was used previously and the web container service is now being used, the war files (and expanded directories) that were deployed here (they are now deployed in JONAS_ROOT/webapps) should be suppressed from the CATALINA_HOME/webapps directory.

Refer to the section "Integrating Tomcat and JOnAS" for details.

JOnAS 2.4.4 to JOnAS 2.5

Tomcat 4.0.x Support

JOnAS 2.5 supports two versions of Tomcat for the tomcat service: Tomcat 3.3.x (as in JOnAS 2.4.4) and Tomcat 4.0.x. The default support of JOnAS 2.4.4 is for Tomcat 3.3.x, therefore nothing needs to be changed if the tomcat service was being used with JOnAS 2.4.4. For Tomcat 4.0.x, the jonas.service.tomcat.class property of jonas.properties file to org.objectweb.jonas.tomcat.EmbeddedTomcatImpl40 must be set. Refer to the How to use Tomcat with JOnAS document for more details.

trace.properties

Starting with JOnAS 2.5, the Objectweb Monolog logging API is used for JOnAS traces. The JOnAS traces configuration file trace.properties has changed. Refer to the Configuration Guide in the JOnAS documentation for details.

JOnAS 2.4.3 to JOnAS 2.4.4

The main differences between these two versions are the two new services provided in JOnAS 2.4.4: registry and tomcat.
JOnAS 2.4.3 from JOnAS 2.4.4
jonas services - jonas.services  
  jmx,security,jtm,dbm,resource,
  jms,ejb
- jonas.services
  registry,tomcat,jmx,security,jtm,dbm,
  resource,jms,ejb
Registry service configuration - - jonas.service.registry.class 
  org.objectweb.jonas.registry.RegistryServiceImpl
- jonas.service.registry.mode 
  automatic
Tomcat service configuration - - jonas.service.tomcat.class 
  org.objectweb.jonas.tomcat.EmbeddedTomcatImpl33
- jonas.service.tomcat.args 

JOnAS 2.3 to JOnAS 2.4

Introduction

This chapter is intended for JOnAS users migrating applications from JOnAS 2.3 to JOnAS 2.4 and later versions. This migration does not affect EJB components' files. However, two configuration files are slightly different: the jonas.properties file and the jonathan.xml file.

Upgrading the jonas.properties file

JOnAS EJB servers are configured via the jonas.properties file. This configuration file may be located in three different places:

  1. $JONAS_ROOT/config/jonas.properties
  2. $HOME/jonas.properties: the home directory
  3. ./jonas.properties: the directory from which the EJB server is launched.

An EJB server reads the three potential files in this order listed (1, 2, 3), each one possibly overwriting properties defined in a previous file. Therefore, existing jonas.properties files from previous JOnAS versions must be upgraded in order to retain the configuration settings, by making the following structural changes:

before JOnAS 2.4 from JOnAS 2.4
jonas services (new) - - jonas.services  
  jmx,security,jtm,dbm,resource,jms,ejb
JMX service configuration - - jonas.service.jmx.class 
  org.objectweb.jonas.jmx.JmxServiceImpl
JOnAS EJB service configuration (beans to be loaded) - jonas.beans.descriptors ...
- jonas.service.ejb.class 
  org.objectweb.jonas.container.EJBServiceImpl
- jonas.service.ejb.descriptors  ...
JOnAS DBM service configuration - jonas.datasources   ...
- jonas.service.dbm.class 
  org.objectweb.jonas.dbm.DataBaseServiceImpl
- jonas.service.dbm.datasources   ...
JOnAS JTM service configuration - jonas.tm.remote  false
- jonas.tm.timeout 60
- jonas.service.jtm.class 
  org.objectweb.jonas.jtm.TransactionServiceImpl
- jonas.service.jtm.remote false
- jonas.service.jtm.timeout 60
JOnAS SECURITY service configuration - - jonas.service.security.class
  org.objectweb.jonas.security.JonasSecurityServiceImpl
JOnAS JMS service configuration - jonas.jms.mom 
  org.objectweb.jonas_jms.JmsAdminForJoram
- jonas.jms.collocated true
- jonas.jms.url  joram://localhost:16010
- jonas.jms.threadpoolsize 10
- jonas.jms.topics sampleTopic
- jonas.jms.queues ...
- jonas.service.jms.class 
  org.objectweb.jonas.jms.JmsServiceImpl
- jonas.service.jms.mom 
  org.objectweb.jonas_jms.JmsAdminForJoram
- jonas.service.jms.collocated true
- jonas.service.jms.url  joram://localhost:16010
- jonas.service.ejb.mdbthreadpoolsize 10
- jonas.service.jms.topics sampleTopic
- jonas.service.jms.queues ...
JOnAS RESOURCE service configuration (Resource Adapters to be installed) - - jonas.service.resource.class 
  org.objectweb.jonas.resource.ResourceServiceImpl
- jonas.service.resource.resources ...

The main transformation rule is that most of the properties are now part of a JOnAS service. For each service XXX, the class property jonas.service.XXX.class containing the name of the service class (all these class properties are set in the $JONAS_ROOT/config/jonas.properties file) must be specified, and each additional property p related to the service is named jonas.service.XXX.p. The list of services to be launched with the server is specified in the jonas.services property. These services are EJB (in which are defined the beans to be loaded), JTM (in which are defined the transaction monitor properties), DBM (in which are defined the datasources), SECURITY, JMS (the messaging service), and JMX (a new service for management).

Upgrading the Jonathan configuration file

In the new version of Jonathan, the jonathan.prop has been replaced by jonathan.xml.