<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="services.versioning.config.about" 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>About the versioning service</title>
  </info>

  <para>This service has been designed for dynamic redeployment of
  applications, without any application downtime and without users' sessions
  being lost:</para>

  <itemizedlist>
    <listitem>
      <para>Deployment of a new version of an application does not require the
      undeployment of any previous version.</para>
    </listitem>

    <listitem>
      <para>Users that were on a previous version keep on using that version
      as long as their session on that version is active (for example, as long
      as they have not finished buying items on the previous version of the
      online trade web site). This guarantees that no user data will be lost,
      and that if there is any problem with the new version the old version is
      still available instantly.</para>
    </listitem>

    <listitem>
      <para>New versions of the application can be deployed using various
      strategies, for instance allow testing of the new version by a small
      community to ensure its readiness for production.</para>
    </listitem>
  </itemizedlist>

  <para>The versioning service achieves this by adding virtual contexts to all
  services that provide support for versioning. To use the versioning
  service:</para>

  <orderedlist>
    <listitem>
      <para>Enable the versioning service in
      <filename>jonas.properties</filename></para>
    </listitem>

    <listitem>
      <para>Define the <emphasis role="bold">Implementation-Version</emphasis>
      attribute in your deployable file's (whether <filename>war</filename>,
      <filename>jar</filename> or <filename>ear</filename>)
      <filename>MANIFEST</filename>. Note that:</para>

      <itemizedlist>
        <listitem>
          <para>ANT, Maven as well as most IDEs can set any
          <filename>MANIFEST</filename> attribute automatically.</para>
        </listitem>

        <listitem>
          <para>If the archive that will be deployed is an
          <filename>ear</filename>, the <emphasis
          role="bold">Implementation-Version</emphasis> defined in the
          <filename>MANIFEST</filename> of the ear will be used for all
          archives the <filename>ear</filename> contains.</para>
        </listitem>
      </itemizedlist>
    </listitem>
  </orderedlist>

  <para>When the versioning service is enabled, application resources (web
  pages, EJBs, etc.) are accessed the following way:</para>

  <itemizedlist>
    <listitem>
      <para>Each versioned application has a user (virtual) address. Each
      version of an application is renamed and bound to that virtual address.
      Each bound version has a policy (that can be changed in time in order to
      manage the deployment strategy):</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Private</emphasis>: Can only be accessed
          by clients that satisfy some prerequisites; for example belong to a
          certain IP address group or provide a certain credential.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Reserved</emphasis>: Not accessible
          using the virtual address, therefore can only be accessed directly
          (using the versioned address).</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Disabled</emphasis>: Only accessible by
          clients that have been using this version in the past (until their
          session expires). This guarantees that users will not lose their
          session data during a redeployment.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Default</emphasis>: Version accessed by
          all clients that don't fit in any other policy.</para>
        </listitem>
      </itemizedlist>
    </listitem>

    <listitem>
      <para>A user can access the application resource indirectly (using the
      virtual address) or directly (using the versioned address).</para>
    </listitem>

    <listitem>
      <para>If the user tries to access the application resource indirectly
      (using the virtual address), the versioning system:</para>

      <itemizedlist>
        <listitem>
          <para>First checks if that user is defined as a user that can access
          a version of the application with the <emphasis
          role="bold">Private</emphasis> access policy. If that is the case,
          the user is routed to that private version of the
          application.</para>
        </listitem>

        <listitem>
          <para>Then checks if that user already has a session in a version of
          the application with the <emphasis role="bold">Disabled</emphasis>
          access policy. If that is the case, the user is routed to that
          disabled version of the application.</para>
        </listitem>

        <listitem>
          <para>If neither of these cases are true, routes the user to the
          version of the application with the <emphasis
          role="bold">Default</emphasis> access policy. If the application
          does not define any default version, the user will see
          "<emphasis>resource not found</emphasis>" message.</para>
        </listitem>
      </itemizedlist>
    </listitem>
  </itemizedlist>

  <para>This can be schematized as follows:</para>

  <para><mediaobject>
      <imageobject>
        <imagedata width="85%" fileref="../../../../resources/images/versioning-general-schema.png"></imagedata>
      </imageobject>
    </mediaobject></para>

  <para>The current limitations of the versioning service are:</para>

  <itemizedlist>
    <listitem>
      <para>Only the Tomcat Web Container supports the versioning service.
      That support is fully functional, recognition of users is based on the
      session ID (via cookie or GET).</para>
    </listitem>

    <listitem>
      <para>Both EJB2 and EJB3s support the versioning service. That support
      is fully functional, EJB lookups in the same EAR always redirect to the
      same version.</para>
    </listitem>

    <listitem>
      <para>Web Service support for the versioning service is in design
      phase.</para>
    </listitem>

    <listitem>
      <para>The Private context policy has not been implemented.</para>
    </listitem>
  </itemizedlist>

  <para>As this service allows seamless and interruptionless upgrade and test
  of all applications, it is strongly recommended for all applications to
  refer version identifiers in their manifest files. Remember that ANT, Maven
  as well as most IDEs can set any <filename>MANIFEST</filename> attribute
  automatically.</para>

  <para>We will now detail the way versioning works by creating two versions
  of the <emphasis role="bold">Java EE 5 Sample Application</emphasis> in the
  <phrase xml:id="appserver">JOnAS</phrase> <filename>examples</filename>
  folder: version 1.0.0 and version 1.0.1. Since the application is an EAR, we
  only need to refer the version identifier in the EAR file. </para>
</section>