# Howto: JOnAS Versions Migration Guide

The content of this guide is the following:

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

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:

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

- 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 your 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 your Jonathan configuration file

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