<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="services.versioning.config.web" 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>Focus: versioned Web Applications</title>
  </info>

  <para>When the first version of the EAR is deployed:</para>

  <itemizedlist>
    <listitem>
      <para>The application gets deployed on the URI <emphasis
      role="bold">/javaee5-earsample-1.0.0</emphasis>.</para>
    </listitem>

    <listitem>
      <para>The virtual URI <emphasis role="bold">/javaee5-earsample
      </emphasis> is created.</para>
    </listitem>

    <listitem>
      <para>The real URI <emphasis
      role="bold">/javaee5-earsample-1.0.0</emphasis> gets bound to the virtual
      URI <emphasis role="bold">/javaee5-earsample</emphasis>.</para>
    </listitem>
  </itemizedlist>

  <para>Therefore, when a user accesses the <emphasis
  role="bold">/javaee5-earsample</emphasis> URI, the content seen is the same
  as the one on <emphasis
  role="bold">/javaee5-earsample-1.0.0</emphasis>.</para>

  <para>We now deploy the second version of the application, version <emphasis
  role="bold">1.0.1</emphasis>, via the JOnAS Web Admin panel. When the second
  version is deployed, it is bound to the virtual URI as <emphasis
  role="bold">Reserved</emphasis> (this is the default policy and can be
  modified via JMX at any time). This means that the only way of accessing the
  <emphasis role="bold">1.0.1</emphasis> version of the application is to type
  as URI <emphasis role="bold">/javaee5-earsample-1.0.1</emphasis>. All
  visitors of <emphasis role="bold">/javaee5-earsample</emphasis> will still
  access the version <emphasis role="bold">1.0.0</emphasis>.</para>

  <para><mediaobject>
      <imageobject>
        <imagedata fileref="../../../../resources/images/admin-webmodule-virtual.png"
                   width="85%"></imagedata>
      </imageobject>
    </mediaobject></para>

  <para>To change the access policies of each version of the virtual URI (the
  only URI end users are expected to access), go to the list of <emphasis
  role="bold">Web Container</emphasis>s in the JOnAS Web Admin panel. If you
  set the version <emphasis role="bold">1.0.0</emphasis> as <emphasis
  role="bold">Disabled</emphasis> and the version <emphasis
  role="bold">1.0.1</emphasis> as <emphasis
  role="bold">Default</emphasis>:</para>

  <itemizedlist>
    <listitem>
      <para>The user that was on <emphasis
      role="bold">/javaee5-earsample</emphasis> when the default version was
      <emphasis role="bold">1.0.0</emphasis> will stay on version <emphasis
      role="bold">1.0.0</emphasis> until her/his session expires (i.e. the
      browser window is closed).</para>
    </listitem>

    <listitem>
      <para>Any user that connects to <emphasis
      role="bold">/javaee5-earsample</emphasis> for the first time will visit
      version <emphasis role="bold">1.0.1</emphasis>.</para>
    </listitem>
  </itemizedlist>

  <para>Since each version of the application is on a different Web context,
  it will be generating headers (<filename>Cookie</filename>,
  <filename>Location</filename>) and Web content with the versioned context
  path (it will for example try to load an image from
  <filename>/javaee5-earsample-1.0.0/images/jonas.gif</filename> instead of
  <filename>/javaee5-earsample/images/jonas.gif</filename>). To avoid this,
  the versioning service will:</para>

  <itemizedlist>
    <listitem>
      <para>Rewrite all returned cookies and replace the versioned path with
      the user path. Similarly, cookie paths will be changed when passing the
      <filename>HTTPRequest</filename> object to the Web application.</para>
    </listitem>

    <listitem>
      <para>If it exists, replace the versioned path with the user path in any
      <filename>Location</filename> (HTTP redirection) header in a
      response.</para>
    </listitem>

    <listitem>
      <para>Replace all versioned paths with the user path for all Web
      responses with the <filename>Content-Type</filename>s listed in the
      <filename>jonas.service.versioning.filteredContentTypes</filename>
      parameter of the versioning service. By default, that parameter is set
      to HTML, CSS, JavaScript and XML files.</para>
    </listitem>
  </itemizedlist>
</section>