JOnAS Versions Migration Guide

 

JOnAS 3.1 to JOnAS 3.1.4

Applications developed for JOnAS 3.1 do not need any change, but should be redeployed (GenIC). Only some configuration files and build.xml files that you may have customized are concerned by the migration.

The main changes are due to the integration of CAROL for communication protocols support, this implies the following configuration changes:

See the JOnAS Configuration Guide for more details about Communication Protocols configuration.

Other configuration changes are due to security enhancements:

See the JOnAS Configuration Guide for more details about Security configuration.

The best steps to migrate from JOnAS 3.1 are certainly to

  1. create a new JOnAS_BASE (e.g. through the ANT create_jonasbase target),
  2. copy your new and customized files of your old JONAS_BASE in the new one, by taking care of 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 your configuration are provided below.

carol.properties

You should modify this file according to the content of your old jndi.properties file. If your OBJECTWEB_ORB was RMI, set carol.protocols to jrmp, if your 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 you were using EJB security, the security context propagation should be activated, a realm resource may be choosen 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

You may choose the memory, database or ldap relam resource for Tomcat authentification.

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

web-jetty.xml

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

  <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

If you wrote scripts calling GenIC for deploying EJBs, the -secpropag option does not exist anymore (security propagation is activated from the jonas.properties file as illustrated above), and a new option -protocols specifies a comma separated list of protocols (choosed within jeremie, jrmp, iiop, cmi) for which stubs will be generated; default value is jrmp,jeremie.

      GenIC -protocols jrmp,jeremie,iiop
    

See below 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. The build.xml files that you may have written must be updated the same way:

JOnAS 3.0 to JOnAS 3.1

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

Differences in the execution environment are:

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

For these two new packagings, you don't need to set the environment variable CATALINA_HOME or JETTY_HOME any longer. These packagings have JOnAS examples compiled for use with RMI.

The location and the policy to configurate JOnAS have changed:

The location and the policy to deploy applications have changed:

JOnAS 2.6.4 to JOnAS 3.0

Application with entity beans CMP 1.1

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

    <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:
    <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 specifies that the default value of the <cmp-version> tag is 2.x.

JOnAS 2.6 to JOnAS 2.6.1

Installation procedure

When JOnAS is installed on a host, and before using it, you must run ant install in the JOnAS_ROOT directory to rebuild global libraries depending on your environment (RMI/JEREMIE, web environment). This must be done again if you decide to switch orb (i.e. from RMI to JEREMIE) or if you change your web environment (i.e. switching from CATALINA to JETTY)

EJB container creation

As required by several JOnAS users, in JOnAS version 2.6.1 it is yet possible to create an EJB container from an EJB deployment descriptor identified by its xml file name, as it was possible in versions anterior to JOnAS 2.6.

JOnAS 2.5 to JOnAS 2.6

No more building with Make

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

Building with Ant 1.5

In JOnAS 2.6, the required version of Ant is 1.5 (instead of Ant 1.4).
Furthermore, since this version, an ant task ejbjar for JOnAS is delivered in the JOnAS distribution. Have a look to the JOnAS example to see how to use this new task.

New jonas command

A new jonas command is delivered. This command allows to:

The EJBServer, JonasAdmin and CheckEnv commands are now deprecated.
See 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 you can no more specify an xml file name:

Tomcat 4.0.x Support

Tomcat version 4.0.1 is no more 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 J2EE application server, so Tomcat may be used with JOnAS as Web container. This functionnality 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 to J2EE specification. Not that if you was previously using the tomcat service and are now using the web container service, you should suppress from your CATALINA_HOME/webapps directory the war files (and expanded directories) that were deployed here (they are now deployed in JONAS_ROOT/webapps).

See the 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 behaviour is to use Tomcat 3.3.x, so you have nothing to change if you were using the tomcat service with JOnAS 2.4.4. If you intend to use Tomcat 4.0.x, you have to set the jonas.service.tomcat.class property of jonas.properties file to org.objectweb.jonas.tomcat.EmbeddedTomcatImpl40. See more details in the How to use Tomcat with JOnAS document.

trace.properties

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

JOnAS 2.4.3 to JOnAS 2.4.4

The main difference is that in JOnAS 2.4.4 there are two new services : 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 dedicated to JOnAS users migrating applications from JOnAS 2.3 to JOnAS 2.4 and later versions. EJB components files are not concerned by this migration, however two configuration files are slightly different: the jonas.properties file and the jonathan.xml file.

Upgrading your jonas.properties file

The jonas.properties file allows to configure JOnAS EJB servers. Such a configuration file may be located at three differents places:

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

An EJB server reads the three possible files in this order (1, 2, 3), each one may overwrite properties defined in a previous file. So you may have existing jonas.properties files from previous JOnAS versions that you want to upgrade, in order to keep your configuration settings. You need to perform the following structuration 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, and for each service XXX you must specify 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), and each other 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 you define the beans to be loaded), JTM (in which you define the transaction monitor properties), DBM (in which you define 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.