<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" 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" xml:lang="en"><info><title>Distributed Message Beans</title></info>
  
  <para>
    JOnAS release 4.1 dramatically simplifies the use of a distributed JORAM platform from within JOnAS servers. For example, such a configuration allows a bean hosted by JOnAS instance "A" to send messages on a JORAM queue, to which a MDB hosted by JOnAS instance "B" listens.
  </para>
  <para>
    This advancement is due to the following:
  </para>
  <itemizedlist>
    <listitem><para>
      JORAM Resource Adapter allows a much more refined configuration than     the JMS service did.
    </para></listitem>
    <listitem><para>
      JORAM provides a distributed JNDI server which allows JOnAS instances     to share information.
    </para></listitem>
  </itemizedlist>
  <para>
    Before going through this chapter, it is highly recommended that the 
    <link xlink:href="Config.html#Config-JORAM-RA">
      JORAM Resource Adapter
    </link>
     configuration guide be reviewed.
  </para>
  <section><info><title>Scenario and general architecture</title></info>
    
    <para>
      The following scenario and general settings are proposed:
    </para>
    <itemizedlist>
      <listitem><para>
        Two instances of JOnAS are run (JOnAS "A" and JOnAS "B"). JOnAS A hosts     a simple bean providing a method for sending a message on a JORAM queue.     JOnAS B hosts a message-driven bean listening on the same JORAM   queue.
      </para></listitem>
      <listitem><para>
        Each JOnAS instance has a dedicated collocated JORAM server: server     "s0" for JOnAS A, "s1" for JOnAS B. Those two servers are aware of each     other.
      </para></listitem>
      <listitem><para>
        The queue is hosted by JORAM server s1.
      </para></listitem>
      <listitem><para>
        An additional JNDI service is provided by the JORAM servers that will     be used for storing the shared information (basically, the queue's naming     reference).
      </para></listitem>
    </itemizedlist>
  </section>
  <section><info><title>Common configuration</title></info>
    
    <para>
      The JORAM servers are part of the same JORAM platform described by the following 
      <code>
        a3servers.xml
      </code>
       configuration file:
    </para>
    <screen>
&lt;?xml version="1.0"?&gt;
&lt;config&gt;
    &lt;domain name="D1"/&gt;
    &lt;server id="0" name="S0" hostname="hostA"&gt;
      &lt;network domain="D1" port="16301"/&gt;
      &lt;service class="org.objectweb.joram.mom.proxies.ConnectionManager"
               args="root root"/&gt;
      &lt;service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService"
               args="16010"/&gt;
      &lt;service class="fr.dyade.aaa.jndi2.distributed.DistributedJndiServer"
               args="16400 0"/&gt;
    &lt;/server&gt;
    &lt;server id="1" name="S1" hostname="hostB"&gt;
      &lt;network domain="D1" port="16301"/&gt;
      &lt;service class="org.objectweb.joram.mom.proxies.ConnectionManager"
               args="root root"/&gt;
      &lt;service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService"
               args="16010"/&gt;
      &lt;service class="fr.dyade.aaa.jndi2.distributed.DistributedJndiServer"
               args="16400 0 1"/&gt;

    &lt;/server&gt;
&lt;/config&gt;    </screen>
    <para>
      This configuration describes a platform made up of two servers, "s0" and "s1", hosted by machines "hostA" and "hostB", listening on ports 16010, providing a distributed JNDI service (more info on JORAM's JNDI may be found 
      <link xlink:href="http://joram.objectweb.org/current/doc/joram4_0_JNDI.pdf">
        here
      </link>
      ).
    </para>
    <para>
      Each JOnAS server must hold a copy of this file in its 
      <code>
        conf/
      </code>
       directory. In its 
      <code>
        jonas.properties
      </code>
       file, each must declare the 
      <code>
        joram_for_jonas_ra.rar
      </code>
       as a resource to be deployed (and each should remove 
      jms
       from its list of services).
    </para>
  </section>
  <section><info><title>Specific configuration</title></info>
    
    <para>
      JOnAS A
       embeds JORAM server 
      s0
      . The 
      <code>
        jonas-ra.xml
      </code>
       descriptor packaged in the 
      <code>
        joram_for_jonas_ra.rar
      </code>
       archive file must provide the following information:
    </para>
    <screen>
&lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;HostName&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;hostA&lt;/jonas-config-property-value&gt;
&lt;/jonas-config-property&gt;      </screen>
    <para>
      The other default settings do not need to be changed.
    </para>
    <para>
      JOnAS B
       embedds JORAM server 
      s1
      . The 
      <code>
        jonas-ra.xml
      </code>
       descriptor packaged in the 
      <code>
        joram_for_jonas_ra.rar
      </code>
       archive file must provide the following properties values:
    </para>
    <screen>
&lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;ServerId&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;1&lt;/jonas-config-property-value&gt;
&lt;/jonas-config-property&gt;
&lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;ServerName&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;s1&lt;/jonas-config-property-value&gt;
&lt;/jonas-config-property&gt;
&lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;HostName&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;hostB&lt;/jonas-config-property-value&gt;
&lt;/jonas-config-property&gt;    </screen>
    <para>
      The other default settings do not need to be changed.
    </para>
    <para>
      The 
      shared queue
       will be hosted by JORAM server s1. It must then be declared in the JOnAS B's 
      <code>
        joramAdmin.xml
      </code>
       file as follows:
    </para>
    <screen>

        &lt;Queue name="sharedQueue"&gt;
          &lt;freeReader/&gt;
          &lt;freeWriter/&gt;
          &lt;jndi name="scn:comp/sharedQueue"/&gt;
        &lt;/Queue&gt;
    </screen>
    <para>
      The 
      <code>
        scn:comp/
      </code>
       prefix is a standard way to specify which JNDI provider should be used. In this case, the shared queue will be bound to JORAM's distributed JNDI server, and may be retrieved from both JOnAS A and JOnAS B. To provide this mechanism, both JOnAS servers must provide access to a standard 
      <code>
        jndi.properties
      </code>
       file. For JOnAS A, the file looks as follows, and should be placed in its 
      <code>
        conf/
      </code>
       directory:
    </para>
    <screen>
java.naming.factory.url.pkgs    org.objectweb.jonas.naming:fr.dyade.aaa.jndi2
scn.naming.factory.host         hostA
scn.naming.factory.port         16400    </screen>
    <para>
      For JOnAS B, the file looks as follows, and should be placed in the right 
      <code>
        conf/
      </code>
       directory:
    </para>
    <screen>
java.naming.factory.url.pkgs    org.objectweb.jonas.naming:fr.dyade.aaa.jndi2
scn.naming.factory.host         hostB
scn.naming.factory.port         16400    </screen>
  </section>
  <section><info><title>And now, the beans!</title></info>
    
    <para>
      The 
      simple bean
       on JOnAS A needs to connect to its local JORAM server and access the remote queue. The following is an example of consistent resource definitions in the deployment descriptors:
    </para>
    <para>
      Standard deployment descriptor:
    </para>
    <screen>
&lt;resource-ref&gt;
  &lt;res-ref-name&gt;jms/factory&lt;/res-ref-name&gt;
  &lt;res-type&gt;javax.jms.ConnectionFactory&lt;/res-type&gt;
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;
&lt;resource-env-ref&gt;
  &lt;resource-env-ref-name&gt;jms/sharedQueue&lt;/resource-env-ref-name&gt;
  &lt;resource-env-ref-type&gt;javax.jms.Queue&lt;/resource-env-ref-type&gt;
&lt;/resource-env-ref&gt;    </screen>
    <para>
      Specific deployment descriptor:
    </para>
    <screen>
&lt;jonas-resource&gt;
  &lt;res-ref-name&gt;jms/factory&lt;/res-ref-name&gt;
  &lt;jndi-name&gt;CF&lt;/jndi-name&gt;
&lt;/jonas-resource&gt;
&lt;jonas-resource-env&gt;
  &lt;resource-env-ref-name&gt;jms/sharedQueue&lt;/resource-env-ref-name&gt;
  &lt;jndi-name&gt;scn:comp/sharedQueue&lt;/jndi-name&gt;
&lt;/jonas-resource-env&gt;    </screen>
    <para>
      The ConnectionFactory is retrieved from the local JNDI registry of the bean. However, the Queue is retrieved from the distributed JORAM JNDI server, because its name starts with the 
      scn:comp/
       prefix. It is the same queue to which the 
      message-driven bean
       on JOnAS B listens. For doing so, its activation properties should be set as follows:
    </para>
    <screen>
&lt;activation-config&gt;
   &lt;activation-config-property&gt;
      &lt;activation-config-property-name&gt;destination&lt;/activation-config-property-name&gt;
      &lt;activation-config-property-value&gt;scn:comp/sharedQueue&lt;/activation-config-property-value&gt;
   &lt;/activation-config-property&gt;
   &lt;activation-config-property&gt;
      &lt;activation-config-property-name&gt;destinationType&lt;/activation-config-property-name&gt;
      &lt;activation-config-property-value&gt;javax.jms.Queue&lt;/activation-config-property-value&gt;
   &lt;/activation-config-property&gt;
&lt;/activation-config&gt;    </screen>
  </section>
</section>