<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Migrating from JOnAS 4.x to JOnAS 5</title>
  </info>

  <para><xi:include href="../variables.xml" xpointer="element(appserver)" />
  has been completely rewritten in order to leverage the <xi:include
  href="../variables.xml" xpointer="element(var.osgi/1/1)" />
  technology.</para>

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

  <section>
    <info>
      <title>Before migration</title>
    </info>

    <para>Before begining the migration process, you must be aware of the
    versions of the <xi:include href="../variables.xml"
    xpointer="element(j2ee)" /> API supported by <xi:include
    href="../variables.xml" xpointer="element(j48ee)" />.</para>

    <para>JOnAS 4 is <xi:include href="../variables.xml"
    xpointer="element(j2ee)" /> v1.4 compliant whereas. <xi:include
    href="../variables.xml" xpointer="element(j48ee)" /> is <xi:include
    href="../variables.xml" xpointer="element(j2ee)" /> 5 compliant. This
    means that the supported versions of most APIs have changed.</para>

    <para>Here is a small table describing the differences:</para>

    <xi:include href="versionAPI.xml" />

    <section>
      <info>
        <title>Prerequisites</title>
      </info>

      <para>A JDK 5 is required to build JOnAS 5 but JDK 6<footnote>
          <para>for those using SUN JDK6 the parameter
          -Dsun.lang.ClassLoader.allowArraySyntax=true may be required</para>
        </footnote>may be used for running JOnAS 5.</para>
    </section>
  </section>

  <section>
    <info>
      <title>Upgrading An Application Environment from 4.x to 5.x</title>
    </info>

    <section>
      <info>
        <title>Application environment definition</title>
      </info>

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

      <para>In JOnAS 4.x JONAS_BASE contains :</para>

      <itemizedlist>
        <listitem>
          <para><xi:include href="../variables.xml" xpointer="j2ee" />
          applications to be deployed in the new environment:</para>

          <para>An application consists of several deployable archives: ear,
          ejbjar, war + some associated connectors packaged in rar
          archives.</para>
        </listitem>

        <listitem>
          <para>Configuration files:</para>

          <para>All configuration files are located under <filename
          class="directory">$JONAS_BASE/conf</filename></para>
        </listitem>

        <listitem>
          <para>External libraries:</para>

          <para>Some libraries may be installed under:</para>

          <itemizedlist>
            <listitem>
              <para><filename
              class="directory">$JONAS_BASE/lib/apps</filename></para>

              <para><filename class="directory">(</filename>applicative
              libraries)</para>
            </listitem>

            <listitem>
              <para><filename
              class="directory">$JONAS_BASE/lib/ext</filename></para>
            </listitem>

            <listitem>
              <para><filename
              class="directory">$JONAS_BASE/lib/commons</filename></para>
            </listitem>

            <listitem>
              <para><filename
              class="directory">$JONAS_BASE/lib/tools</filename></para>

              <para>(libraries whoses classes are made available to all JOnAS
              services)</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>For a successful upgrade you must be aware of the JOnAS changes in
      :</para>

      <itemizedlist>
        <listitem>
          <para>the class loader hierarchy see <link
          xlink:href="j2eeprogrammerguide.html#j2ee.pg.classloader">Understanding
          class loader hierarchy </link>for a complete description of the
          classloader mechanism.</para>
        </listitem>

        <listitem>
          <para>deployment process, due to a new deployment
          architecture</para>
        </listitem>

        <listitem>
          <para>configuration files</para>
        </listitem>

        <listitem>
          <para>third party libraries processing</para>
        </listitem>
      </itemizedlist>

      <para>To upgrade an application environment you must first create a new
      application environment and then customize it according to the old
      environment.</para>

      <section>
        <info>
          <title>Creating a new Application environment</title>
        </info>

        <para>To create a new application environnement you must create a new
        JOnAS_BASE.</para>

        <xi:include href="../config/jonasbase_creation.xml" />

        <note>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.</note>
      </section>
    </section>

    <section>
      <info>
        <title>New deployment architecture</title>
      </info>

      <para>With JOnAS 5.x, the following deployment directories have been
      removed :</para>

      <itemizedlist>
        <listitem>
          <para>
            <filename class="directory">apps</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">apps/autoload</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">clients</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">ejbjars</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">ejbjars/autoload</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">rars</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">rars/autoload</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">webapps</filename>
          </para>
        </listitem>

        <listitem>
          <para>
            <filename class="directory">webapps/autoload</filename>
          </para>
        </listitem>
      </itemizedlist>

      <para>The above directories no longer exist in JONAS_BASE and have been
      replaced by a single directory:</para>

      <itemizedlist>
        <listitem>
          <para>
            <filename class="directory">deploy</filename>
          </para>
        </listitem>
      </itemizedlist>

      <para>To deploy a <xi:include href="../variables.xml" xpointer="j2ee" />
      archive in JOnAS 5.x, the only thing required is to put it in the
      <filename>$JONAS_BASE/deploy directory</filename>. This directory is
      periodically scanned in order to deploy new archives. <footnote>
          <para>The periodic scan can be disabled by setting the
          jonas.development property to false in
          <filename>JONAS_BASE/conf/jonas.properties</filename></para>
        </footnote></para>

      <para>The deployment policy has changed in <phrase xml:id="j48ee">JOnAS
      5 since at server starting time the deployment order of the archives
      found in $JONAS_BASE/deploy is the following:</phrase></para>

      <orderedlist>
        <listitem>
          <para>Deployment plan repositories</para>
        </listitem>

        <listitem>
          <para><trademark>OSGi</trademark> bundles</para>
        </listitem>

        <listitem>
          <para>RAR archives</para>
        </listitem>

        <listitem>
          <para>Deployment plan resources</para>
        </listitem>

        <listitem>
          <para>EJB archives</para>
        </listitem>

        <listitem>
          <para>WAR archives</para>
        </listitem>

        <listitem>
          <para>EAR archives</para>

          <para>
            <note>
              <para>For each category, file names are chosen in alphabetical
              order</para>
            </note>
          </para>
        </listitem>
      </orderedlist>

      <para>Here a basic <emphasis>how to</emphasis> that explains how to
      create a very simple deployment plan.</para>

      <xi:include href="../deployment-plans/deployment-plan-sample-example.xml" />

      <para>For more information see the depmonitor service configuration in
      the <link
      xlink:href="configuration_guide.html#services.depmonitor.config">JOnAS
      Configuration Guide.</link></para>
    </section>

    <section>
      <info>
        <title>Script files</title>
      </info>

      <para>The path of the script command files has been changed, and is
      <filename class="directory">$JONAS_ROOT/bin</filename> instead of
      <filename class="directory">$JONAS_ROOT/bin/unix</filename> and
      <filename class="directory">$JONAS_ROOT/bin/nt</filename>.</para>
    </section>

    <section>
      <info>
        <title>Configuration files</title>
      </info>

      <para>JOnAS configuration files have changed. Here we will focus on the
      changes that may impact the upgrade process.</para>

      <section>
        <info>
          <title>carol.properties file</title>
        </info>

        <para>jeremie protocol is no longer supported.</para>

        <para>New properties have been added to configure cmi clusters. Note
        that <emphasis role="bold">cmi</emphasis> is not anymore a protocol
        but a JOnAS service used for clustering.</para>

        <para>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 <link
        xlink:href="configuration_guide.html#config.protocol">JOnAS
        Configuration Guide).</link> .</para>
      </section>

      <section>
        <info>
          <title>clusterd.properties file</title>
        </info>

        <para>With JOnAS 5 the cluster deamon can start the discovery
        service.</para>
      </section>

      <section>
        <info>
          <title>context.xml, server.xml, web.xml</title>
        </info>

        <para>JOnAS 5 now embeds Tomcat 6 instead of Tomcat 5.</para>

        <para><filename>context.xml, server.xml and web.xml</filename>
        configuration files are replaced by
        <filename>tomcat6-context.xml</filename>,
        <filename>tomcat6-server.xml</filename> and
        <filename>tomcat6-web.xml</filename>.</para>

        <para>See <link
        xlink:href="http://tomcat.apache.org/tomcat-6.0-doc/index.html">Apache
        Tomcat 6.0 Documentation</link> for more information.</para>
      </section>

      <section>
        <info>
          <title>jaas.config</title>
        </info>

        <para>No new properties in this file. The only difference is the name
        of the package for the LoginModule classes.</para>

        <para>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.</para>
      </section>

      <section>
        <info>
          <title>jetty5-webdefault.xml &amp; jetty5.xml</title>
        </info>

        <para>These configuration files are now named <filename>jetty6-web.xml
        and </filename><filename>jetty6.xml.</filename></para>

        <para>For more information see <link
        xlink:href="http://docs.codehaus.org/display/JETTY/Jetty+Documentation">Jetty
        Documentation</link></para>
      </section>

      <section>
        <info>
          <title>jgroups-cmi.xml &amp; jgroups-ha.xml</title>
        </info>

        <para>JOnAS 5 now uses a newer version of JGroups. The JGroups
        Protocol Stack configuration files format is different. Therefore
        customizations made in the old <filename>jgroups-cmi.xml</filename>
        and <filename>jgroups-ha.xml</filename> files must be updated to the
        new formats.</para>
      </section>

      <section>
        <info>
          <title>jonas.properties</title>
        </info>

        <para>The <filename>jonas.properties</filename> file has changed
        significantly . Some changes do not impact the upgrade process at all
        (package name changes), while others must be studied carefully.</para>

        <para>In the following, we focus on the parts of the
        <filename>jonas.properties</filename> file that may be impacted during
        the upgrade process.</para>

        <section>
          <info>
            <title>jonas.services property</title>
          </info>

          <para><emphasis role="bold">thread</emphasis> and <emphasis
          role="bold">jms</emphasis> services have been suppressed (see <xref
          linkend="migration.jonas5.jms" /> below).</para>

          <para><emphasis role="bold">ejb</emphasis> service has been renamed
          to <emphasis role="bold">ejb2</emphasis> service.</para>

          <para><emphasis role="bold">ws</emphasis> service has been renamed
          to <emphasis role="bold">jaxrpc</emphasis> service.</para>

          <para><emphasis role="bold">wm</emphasis>, <emphasis
          role="bold">wc</emphasis>, <emphasis role="bold">ha</emphasis>,
          <emphasis role="bold">ejb3</emphasis>, <emphasis
          role="bold">versioning</emphasis>, <emphasis
          role="bold">depmonitor</emphasis>, <emphasis
          role="bold">cmi</emphasis>,<emphasis
          role="bold">resourcemonitor</emphasis>,<emphasis
          role="bold">jaxws</emphasis> and <emphasis
          role="bold">smartclient</emphasis> are new services in JOnAS
          5</para>

          <para>With JOnAS 5, the default jonas.services properties are set
          to:</para>

          <para><screen>jonas.services    jtm,db,dbm,security,resource,ejb3,jaxws,web,ear,depmonitor</screen></para>

          <para>(in order to learn more about these services see the <link
          xlink:href="configuration_guide.html#config.services">JOnAS
          configuration_guide</link>)</para>
        </section>

        <section>
          <info>
            <title>ejb2 service configuration</title>
          </info>

          <para><emphasis role="bold">ejb2</emphasis> service replaces the
          previous <emphasis role="bold">ejb</emphasis> service.</para>

          <para>Configuration of worker threads has been moved from the
          <emphasis role="bold">ejb</emphasis> service configuration to the
          Work Manager (<emphasis role="bold">wm</emphasis>) service
          configuration.</para>

          <para>See the Work Manager configuration part in <xref
          linkend="resource_service_config" /></para>
        </section>

        <section xml:id="migration.jonas5.jms">
          <info>
            <title>jms service configuration</title>
          </info>

          <para>The JORAM resource adapter must be used in replacement of the
          <emphasis role="bold">jms</emphasis> service.</para>

          <para>In order to use JMS via the JORAM resource adapter</para>

          <orderedlist>
            <listitem>
              <para>The <emphasis role="bold">resource</emphasis> service must
              be set in the jonas.services property</para>
            </listitem>

            <listitem>
              <para><filename>joram.xml </filename>must be deployed (it must
              be located under <filename
              class="directory">$JONAS_BASE/deploy</filename>)</para>
            </listitem>

            <listitem>
              <para>JORAM port must be configured in <filename>the
              $JONAS_BASE/conf/joramAdmin.xml </filename>file</para>
            </listitem>

            <listitem>
              <para>JMS destinations must be defined in <filename>the
              $JONAS_BASE/conf/joramAdmin.xml </filename>file</para>
            </listitem>
          </orderedlist>

          <para>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
          (<property>jonas.service.ejb.minworkthreads</property>,
          <property>jonas.service.ejb.maxworkthreads</property> properties)
          you must update the equivalent settings in the Work Manager
          configuration (see below).</para>
        </section>

        <section xml:id="resource_service_config">
          <info>
            <title>resource service configuration</title>
          </info>

          <para>Configuration of worker threads has been moved from <emphasis
          role="bold">resource</emphasis> service configuration to Work
          Manager (<emphasis role="bold">wm</emphasis>) service
          configuration.</para>

          <para>Work Manager configuration:</para>

          <xi:include href="../services/wm/config.xml"
                      xpointer="screen_wm_service" />
        </section>

        <section>
          <info>
            <title>discovery service configuration</title>
          </info>

          <para>The property indicating that the current instance is (or is
          not) a master server is no longer a <emphasis role="bold">discovery
          </emphasis>service property, but instead, a
          <filename>jonas.properties</filename> global property</para>

          <para><screen>jonas.master false</screen>The <emphasis
          role="bold">discovery</emphasis> service supports two
          implementations. One of them uses JGroups, the other one uses
          multicast. Multicast is the default..</para>

          <para>For more information about configuring discovery service see
          <link
          xlink:href="configuration_guide.html#services.discovery.config">discovery
          service configuration.</link></para>
        </section>
      </section>

      <section>
        <info>
          <title>trace.properties &amp; traceclient.properties</title>
        </info>

        <para>Logger names have changed because of changes in internal JOnAS
        packages name.</para>
      </section>
    </section>

    <section>
      <info>
        <title>libraries</title>
      </info>

      <para>There are several ways to use libraries in portable Java EE
      applications :</para>

      <itemizedlist>
        <listitem>
          <para>placing the library JAR file into the WEB-INF/lib directory of
          the WAR file,</para>
        </listitem>

        <listitem>
          <para>using the Class-Path attribute in the manifest file to
          reference one or more library JAR files included in the EAR
          file.</para>
        </listitem>

        <listitem>
          <para>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)</para>
        </listitem>
      </itemizedlist>

      <para>If the application to migrate follows one of these policies it can
      be used with <xi:include href="../variables.xml"
      xpointer="element(j48ee)" /> without changes.</para>

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

      <para>It is worth knowing that tomcat 6, embedded in <xi:include
      href="../variables.xml" xpointer="element(j48ee)" />, tries to resolve
      extension dependencies for web applications before deploying them, and
      that it uses the system property <property>catalina.ext.dirs</property>
      to try and locate libraries.</para>

      <para>The JDBC driver can be installed under $JONAS_BASE/lib/ext or
      packaged into an <xi:include href="../variables.xml"
      xpointer="element(var.osgi/1/1)" /> bundle, we recommend the latest
      way.</para>
    </section>

    <section>
      <title>Using the Management bean MEJB</title>

      <xi:include href="../admin/mejbaccess.xml" />
    </section>
  </section>

  <section>
    <title>Changes that can affect application code</title>

    <para>If the application to port was pointing to JOnAS java internal
    classes with <emphasis role="bold"> org.objectweb.jonas.xxx
    </emphasis>packages, all references to these packages must be replaced by
    references to <emphasis role="bold">org.ow2.jonas.xxx</emphasis>
    package.</para>

    <para>For example if the application is using the authentication mechanism
    implemented by the class <emphasis
    role="bold">org.objectweb.jonas.security.realm.web.catalina55.JACC</emphasis>
    in JOnAS 4 this mechanism is now implemented in JOnAS5 by <emphasis
    role="bold">org.ow2.jonas.web.tomcat6.security.Realm.</emphasis></para>

    <para><emphasis
    role="bold">org.objectweb.jonas.security.realm.web.jetty50.Standard</emphasis>
    must be changed by <emphasis
    role="bold">org.ow2.jonas.web.jetty6.security.Realm</emphasis></para>

    <para><emphasis
    role="bold">org.objectweb.jonas.security.auth.callback.LoginCallbackHandler</emphasis>
    must be changed by <emphasis
    role="bold">org.ow2.jonas.security.auth.callback.LoginCallbackHandler</emphasis></para>

    <para><emphasis
    role="bold">org.objectweb.jonas.security.auth.spi.JResourceLoginModule</emphasis>
    by <emphasis
    role="bold">org.ow2.jonas.security.auth.spi.JResourceLoginModule</emphasis></para>

    <para><emphasis
    role="bold">org.objectweb.jonas.security.auth.spi.ClientLoginModule</emphasis>
    by <emphasis
    role="bold">org.ow2.jonas.security.auth.spi.ClientLoginModule</emphasis></para>
  </section>
</chapter>
