<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="config.protocol" 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>Configuring the communication protocol and JNDI</title>
  </info>

  <para><xi:include href="../variables.xml" xpointer="appserver" /> provides a
  multi-protocol support through the integration of the CAROL
  component.</para>

  <para>Supported communication protocols are the following:</para>

  <itemizedlist>
    <listitem>
      <para>RMI/JRMP is the JRE implementation of RMI on the JRMP protocol.
      This is the default communication protocol.</para>
    </listitem>

    <listitem>
      <para>RMI/IIOP is the <link
      xlink:href="http://www.jacorb.org/">JacORB</link> implementation of RMI
      over the IIOP protocol.</para>
    </listitem>

    <listitem>
      <para>IRMI is an RMI implementation that can be used with Open Source
      JDK that doesn't provide <interfacename>com.sun.*
      </interfacename>classes.</para>
    </listitem>
  </itemizedlist>

  <para>For each of these protocols, the clustering of RMI objects can be
  enabled with the component CMI.</para>

  <section>
    <info>
      <title>Choosing the Protocol</title>
    </info>

    <para>The choice of the protocol is made in the
    <property>carol.protocols</property> property of <filename>
    carol.properties</filename> file in <filename
    class="directory">JONAS_BASE/conf</filename> directory.</para>

    <screen>carol.protocols=jrmp</screen>

    <section>
      <info>
        <title>configuring jrmp protocol</title>
      </info>

      <para><screen>carol.protocols=jrmp <co xml:id="protocolchoice" />
carol.jrmp.url=rmi://localhost:1099 <co xml:id="registryurl" />
carol.jvm.rmi.local.call=false <co xml:id="localcall" />
carol.jvm.rmi.local.registry=false <co xml:id="localregistry" />
carol.jrmp.server.port=0 <co xml:id="serverport" />
carol.jrmp.interfaces.bind.single=false <co xml:id="bindsingle" /></screen>
      <calloutlist>
          <callout arearefs="protocolchoice">
            <para>choice of the protocol or list of protocols</para>
          </callout>

          <callout arearefs="registryurl">
            <para>connexion url to the RMI registry the hostname (localhost)
            and port number must be changed if needed. In a distributed
            configuration changing the hostname is mandatory.</para>
          </callout>

          <callout arearefs="localcall">
            <para>if true local calls are optimized: calls to methods of the
            remote interface are treated as call to local methods (it is not
            always possible depending on the packaging of the
            application).</para>
          </callout>

          <callout arearefs="localregistry">
            <para>if true a local Naming context is used. This must be used
            only with a collocated registry and it is mandatory when the
            jonas.security.manager property of jonas.properties is set to
            true.</para>
          </callout>

          <callout arearefs="serverport">
            <para>exported objects will listen on this port for remote method
            invocations. 0 means random port. Specify a port may be useful
            when the server run behind a firewall.</para>
          </callout>

          <callout arearefs="bindsingle">
            <para>if true use only a single interface (choosen from the url)
            when creating the registry. False means use all interfaces
            available.</para>
          </callout>
        </calloutlist></para>
    </section>

    <section>
      <info>
        <title>configuring RMI/IIOP protocol</title>
      </info>

      <para>The JacORB implementation of RMI over the IIOP is used. The
      configuration file of JacORB is the <filename
      class="directory">$JONAS_BASE/conf/jacorb.properties
      </filename>file.</para>

      <para>As for the other protocols RMI over IIOP is ready to used in the
      default distribution. It is only for tuning purpose that the <filename
      class="directory">$JONAS_BASE/conf/jacorb.properties </filename>file
      must be customized.</para>

      <para>By default the CORBA Naming service is run using the port 2001 (as
      it is set in the <filename>carol.properties </filename>file)</para>

      <para>So the only thing to do for working in RMI over IIOP is to set the
      property protocols in carol.properties:</para>

      <screen>carol.protocols=iiop
# RMI IIOP URL
carol.iiop.url=iiop://localhost:2001
carol.iiop.server.port=0 <co xml:id="iiop.server.port" />
carol.iiop.server.sslport=2003 <co xml:id="iiop.server.sslport" />
carol.iiop.PortableRemoteObjectClass=org.ow2.jonas.registry.carol.delegate.JacORBPRODelegate  <co
          xml:id="iiop.delegate" /></screen>

      <calloutlist>
        <callout arearefs="iiop.server.port">
          <para>0 means random port</para>
        </callout>

        <callout arearefs="iiop.server.sslport">
          <para>this port is used only if SSL mode is enabled (default
          configuration = not used).Is used to set the SSL port of the objects
          listener</para>
        </callout>

        <callout arearefs="iiop.delegate">
          <para>delegate used by JOnAS for rmi-iiop protocol.</para>
        </callout>
      </calloutlist>
    </section>

    <section>
      <info>
        <title>configuring irmi protocol</title>
      </info>

      <para><screen>carol.protocols=irmi
carol.irmi.url=rmi://localhost:1098 <co xml:id="irmi.url" />
carol.irmi.server.port=0 <co xml:id="irmi.server.port" />
carol.irmi.interfaces.bind.single=false <co xml:id="irmi.interfaces" /></screen>
      <calloutlist>
          <callout arearefs="irmi.url">
            <para>for irmi the default port is 1098</para>
          </callout>

          <callout arearefs="irmi.server.port">
            <para>exported objects will listen on this port for remote method
            invocations:0 means random port.<caution>
                <para>if the port is set to n the port 'n + 1' will be used by
                the JMX server.So, for the firewall configuration, you have to
                open the port numbers 'n' and 'n+1'</para>
              </caution></para>
          </callout>

          <callout arearefs="irmi.interfaces">
            <para>if true use only a single interface when creating the
            registry (specified in carol.irmi.url property). Default
            configuration = false(use all interfaces available)</para>
          </callout>
        </calloutlist></para>
    </section>

    <section>
      <info>
        <title>enabling clustering of RMI objects</title>
      </info>

      <para>CMI is the component to use for clustering purpose. It is embedded
      in the component CAROL.</para>

      <para>CMI is just composed of wrappers and interceptors and is fully
      independant of the implementation of protocol. CMI relies on <link
      xlink:href="http://www.jgroups.org/javagroupsnew/docs/index.html">JGroups</link>
      group-communication protocol for ensuring the replication of the cluster
      view. CMI provides jndi high availability, the load-balancing and
      fail-over at the EJB level.</para>

      <para>For using CMI with a protocol (in addition to the activation of
      service cmi), a property must be added in
      <filename>carol.properties</filename>:</para>

      <screen>carol.jrmp.cmi=true <co xml:id="cmi.activ.jrmp" />
carol.iiop.cmi=true
carol.irmi.cmi=false <co xml:id="cmi.activ.irmi" /></screen>

      <calloutlist>
        <callout arearefs="cmi.activ.jrmp">
          <para>Enable clustering with jrmp</para>
        </callout>

        <callout arearefs="cmi.activ.irmi">
          <para>Disable clustering with imi</para>
        </callout>
      </calloutlist>

      <note>
        <para>By default, the property is set at true.</para>
      </note>
    </section>

    <section>
      <info>
        <title>multi protocol configuration</title>
      </info>

      <para>JOnAS can be configured to use several protocols simultaneously.
      To do this, just specify a comma-separated list of protocols in the
      carol.protocols property of the <filename>carol.properties</filename>
      file. For example:</para>

      <screen>carol.protocols=iiop,jrmp
carol.jrmp.url=rmi://localhost:1099
carol.iiop.url=iiop://localhost:2001</screen>

      <caution>
        <para>When iiop is used in a multiprotocol configuration, it must
        appear at the first position in the protocol list.</para>
      </caution>
    </section>
  </section>
</section>
