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

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

  <itemizedlist>
    <listitem>
      <para>All EJBs that register on the JNDI directory register with a
      prefixed name, which is their original name prefixed by <emphasis
      role="bold">javaee5_earsample_version1.0.0/</emphasis>. For example, the
      <emphasis role="bold">myStateless</emphasis> bean gets registered as
      <emphasis
      role="bold">javaee5_earsample_version1.0.0/myStateless</emphasis>.</para>
    </listitem>

    <listitem>
      <para>For each EJB, the original JNDI name is also registered and points
      exactly to the same JNDI link.</para>
    </listitem>
  </itemizedlist>

  <para>Therefore, when a user looks up for the <emphasis
  role="bold">myStateless</emphasis> bean, the reference received is the same
  as the one received when <emphasis
  role="bold">javaee5_earsample_version1.0.0/myStateless</emphasis> is looked
  up.</para>

  <para>The behaviours of the Web and EJB services when the version <emphasis
  role="bold">1.0.1</emphasis> is deployed are similar, except for one very
  important point: when multiple applications are packaged together, the only
  versions of the applications they've been tested against are the versions
  inside the same EAR. Therefore, blindly accessing the <emphasis
  role="bold">Default</emphasis> version of the EJBs could have unexpected
  results. This is why the concept of versioned EJB clients has been
  created:</para>

  <itemizedlist>
    <listitem>
      <para>All EJB clients in a versioned EAR automatically become versioned
      EJB clients. Their target version is the version of the host EAR, which
      implies that intra-EAR accesses are always done to the same
      version.</para>
    </listitem>

    <listitem>
      <para>External EJB clients can also specify the versions for the EJB
      they need to access.</para>
    </listitem>

    <listitem>
      <para>Non-versioned external EJB clients will access the <emphasis
      role="bold">Private</emphasis>, <emphasis
      role="bold">Reserved</emphasis>, <emphasis
      role="bold">Disabled</emphasis> or <emphasis
      role="bold">Default</emphasis> versions as usual.</para>
    </listitem>
  </itemizedlist>

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

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

  <para>As with the versioned Web Applications, to change the access policies
  of each version of the virtual JNDI container (which knows the JNDI names
  end users are expected to access), go to the list of <emphasis
  role="bold">EJB 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>All clients that know about the versioned JNDI names (remember
      that this will always be the case in a versioned EAR application) will
      always access the version they specify.</para>
    </listitem>

    <listitem>
      <para>References to <emphasis role="bold">myStateless</emphasis>
      obtained before this operation will stay on version <emphasis
      role="bold">1.0.0</emphasis>.</para>
    </listitem>

    <listitem>
      <para>Any user that looks up<emphasis role="bold">
      myStateless</emphasis> for the first time will get a reference to
      version <emphasis role="bold">1.0.1</emphasis>.</para>
    </listitem>
  </itemizedlist>
</section>