Howto: JOnAS Versions Migration Guide

The content of this guide is the following:

• JOnAS 3.3.x to JOnAS 4.1
• JOnAS 3.1 to JOnAS 3.1.4
• JOnAS 3.0 to JOnAS 3.1
• JOnAS 2.6.4 to JOnAS 3.0
  1. Application with entity beans CMP 1.1
• JOnAS 2.6 to JOnAS 2.6.1
  1. Installation procedure
  2. EJB container creation
• JOnAS 2.5 to JOnAS 2.6
  1. Use of Make discontinued for building
  2. Building with Ant 1.5
  3. New jonas command
  4. EJB container creation
  5. Tomcat 4.0.x Support
  6. Tomcat Service and Web Container Service
• JOnAS 2.4.4 to JOnAS 2.5
  1. Tomcat 4.0.x Support
  2. trace.properties
• JOnAS 2.4.3 to JOnAS 2.4.4
• JOnAS 2.3 to JOnAS 2.4
  1. Introduction
  2. Upgrading the jonas.properties file
  3. Upgrading the Jonathan configuration file

JOnAS 3.3.x to JOnAS 4.1

Applications developed for JOnAS 3.3.x do not require changes; however, they should be redeployed (GenIC). The main changes occur within the JOnAS configuration files, and it is recommended to report your customizations in the new JOnAS 4.1 configuration files, especially for the ones mentioned below.

Configuration changes

The two most visible configuration changes are the following:

1. HTTP port numbers have moved from the 8000 range to the 9000 range, e.g. the JOnAS server index page with default configuration on a given host is now http://localhost:9000/index.jsp
2. the three RMI communication protocols, jrmp, jeremie and iiop can now be used simultaneously, the incompatibility between Jeremie and rmi/iiop and the "ant installiiop" step have been suppressed. In any case, the "ant install" phase (in JONAS_ROOT) is no longer needed.

Configuration files with significant changes:

• conf/server.xml: this file is a customized Tomcat 5 configuration file, while in JOnAS 3.3.x it was a Tomcat 4 configuration file. Moreover, package names of JOnAS-related security files have changed, e.g. org.objectweb.jonas.security.realm.web.catalina50.JACC replaces org.objectweb.jonas.security.realm.JRealmCatalina41. The JAAS classname realm is org.objectweb.jonas.security.realm.web.catalina50.JAAS.
• conf/jetty5.xml replaces conf/jetty.xml. In the web-jetty.xml files (in war), the package name of the Realm class has changed, e.g. org.objectweb.jonas.security.realm.web.jetty50.Standard replaces org.objectweb.jonas.security.realm.JRealmJetty42 class. The JAAS classname realm is org.objectweb.jonas.security.realm.web.jetty50.JAAS.
• conf/jonas.properties: many changes
  • some properties for web services
  • some package names have changed (e.g. for the Web JOnAS service)
  • the XML validation is activated by default for EJBs
  • new properties for the service 'db' (by default it uses HSQL as java database)
• conf/joram-admin.cfg: this is a new configuration file used for specifying the creation of JMS- administered objects when using the JORAM connector (J2EE CA 1.5 JMS resource adapter). The default file corresponds to the default-administered objects created when using the JOnAS JMS service.

Running EJB 2.1 Message-driven Beans

The use of EJB 2.1 Message-driven beans (MDBs) requires changing the JOnAS configuration. While for EJB 2.0 MDBs the JOnAS JMS service was required, EJB 2.1 MDBs can only be used through a JMS Connector (J2EE CA 1.5 resource adapter). Currently the JOnAS JMS service and the JMS connector cannot work at the same time. Therefore, it is necessary to suppress the "jms" service from the list of JOnAS services (jonas.services in jonas.properties) and to add the JORAM connector in the list of resource adapters to be deployed by the JOnAS resource service (jonas.service.resource.resources in jonas.properties). Note that it is currently not possible to run EJB 2.0 MDBs and EJB 2.1 MDBs simultaneously in the same server. It is anticipated that a JMS connector able to handle both EJB 2.0 and EJB 2.1 MDBs will be available soon, at which time the JOnAS JMS service will become deprecated. For more details, refer to the Configuring JMS Service and Configuring JMS Resource Adapters sections of the Configuration Guide.

Deploying Resource Adapters

The RAConfig Resource Adapter configuration tool did not generate the DOCTYPE information in JOnAS 3.3.x versions. If you are using resource adapters that were customized through RAConfig, it is recommended that the tool be run again on these Resource Adapters.

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:

• The jndi.properties file is replaced by a carol.properties file (in JONAS_BASE/conf or JONAS_ROOT/conf) and is no longer searched for within the classpath.
• The OBJECTWEB_ORB environment variable no longer exists.
• Security context propagation is specified in the jonas.properties file, which replaces the -secpropag option of GenIC or the secpropag attribute of the JOnAS ejb-jar ANT task.
• EJBs can be deployed for several protocols, which is specified by the new option -protocols of GenIC or new attribute protocols of the JOnAS ejb-jar ANT task; previously, the protocol was chosen through the OBJECTWEB_ORB environment variable.
• The ${OBJECTWEB_ORB}_jonas.jar files, i.e. RMI_jonas.jar or JEREMIE_jonas.jar, no longer exist; there is only one jonas.jar file.
• The previous items involve changes in application build.xml files.

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

Other configuration changes are due to security enhancements:

• The files tomcat-users.xml, jonas-users.properties, and jettyRealm.properties, are suppressed and replaced by a jonas-realm.xml file. This file contains the list of users/password/roles for the Memory realm, as well as the access configuration for Database and LDAP realms. Realms declared in this file have corresponding resources bound in the registry, and MBeans to be managed.
• The security service should be launched after the dbm service (order in the jonas.services property).
• A new realm with a reference to the JOnAS resource specified in the jonas-realm.xml file is used in the server.xml file (Tomcat) or in the web-jetty.xml file (Jetty).
• The jonas.properties file contains a new line specifying the jndi name of a resource (ejbrealm) that provides Java access to the user identification repository (memory, ldap, or database) of the corresponding realm (specified in the jonas-realm.xml file). This is primarily used by Java clients that intend to build their SecurityContext.

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:

• <property name="orb" value="${myenv.OBJECTWEB_ORB}" /> is no longer used and must be suppressed.
• In the target building the classpath, replace ${orb}_jonas.jar by jonas.jar.
• In the jonas deployment task, suppress the attributes orb="${orb}" secpropag="yes," and add the attribute protocols="${protocols.names}." The build.properties file of the JOnAS examples now contains protocols.names=jrmp,jeremie.

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 available under three different packagings.
• The location and the JOnAS configuring policy has changed.
• The location and the policy to deploy applications has changed.

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

• jonas3.1-tomcat4.1.24 package
• jonas3.1-jetty4.2.9 package.

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:

• Configuration files are located under $JONAS_ROOT/conf (in previous versions they were located under $JONAS_ROOT/config).
• The old policy used to search for configuration files (working directory, home directory, $JONAS_ROOT/config) is no longer used. The new policy is the following:
  If the environment variable JONAS_BASE is set, configuration files are searched for in $JONAS_BASE/conf, if not, under $JONAS_ROOT/con.

The location and the policy for deploying applications has changed:

• If the environment variable JONAS_BASE is set, the application to be deployed with jadmin or jonas admin are searched for in $JONAS_BASE/(ejbjars|apps|webapps), if not, under $JONAS_ROOT/(ejbjars|apps|webapps).

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>
    

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

JOnAS 2.6 to JOnAS 2.6.1

Installation procedure

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:

• start a JOnASserver,
• stop a JOnASserver,
• administrate a JOnASserver,
• check the JOnASenvironment,
• print the JOnASversion.

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:

• a value of the jonas.service.ejb.descriptors jonas property,
• or an argument of the -a option of the jonas admin command.

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 JONAS_ROOT/conf/trace.properties has changed. Refer to the Configuration Guide in the JOnAS documentation for details.

JOnAS 2.4.3 to JOnAS 2.4.4

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.

• jonas.properties: due to the new JOnAS architecture regarding services (refer to the advanced topic chapter on JOnAS services in the JOnAS documentation), the structure of the properties defined in this file has changed. It is necessary to upgrade a jonas.properties file written for a version 2.x (x<4) to reuse it for JOnAS 2.4.
• jonathan.xml: for applications using the JEREMIE distribution mechanism, it is necessary to upgrade this configuration file, since JOnAS has embedded a new version of Jonathan.

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:

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