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

  <para>The configuration of the <emphasis role="bold">cmi</emphasis> service
  is available through the file
  <filename>$JONAS_BASE/conf/cmi-config.xml</filename>.</para>

  <para>The CMI service can be configured in two modes: <itemizedlist>
      <listitem>
        <para><emphasis>server mode</emphasis> with a cluster view manager
        created locally, i.e. with a local instance of a replicated CMI
        registry.</para>
      </listitem>

      <listitem>
        <para><emphasis>client mode</emphasis> without a local cluster view
        manager, in this case a list of providers urls (i.e. a list of cluster
        view manager urls) is given for accessing to the remote CMI
        registries.</para>
      </listitem>
    </itemizedlist> The <emphasis>server mode</emphasis> is simpler to
  configure, the <emphasis>client mode</emphasis> requires to define
  statically a list of providers urls. The <emphasis>server mode</emphasis>
  starts a Group Communication Protocol instance (e.g. JGroups) and thus
  increases the resources consumption compare to the <emphasis>client
  mode</emphasis>.</para>

  <note>
    <para>The CMI configuration file may contain two parts: a
    <literal>server</literal> element which corresponds to the server mode
    configuration and a <literal>client</literal> element for the client mode
    configuration. If the two are present, only the <literal>server</literal>
    element is loaded which means that the server mode is configured.</para>
  </note>

  <section>
    <info>
      <title>Server mode configuration</title>
    </info>

    <para>The server element contains the following elements:</para>

    <para>
      <example>
        <title>Configuring the cmi service in the server mode</title>

        <screen>
  
&lt;cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:jgroups="http://org.ow2.cmi.controller.server.impl.jgroups"&gt;
    &lt;server&gt;
        &lt;jndi&gt; <co xml:id="cmi.server.jndi" />
            &lt;protocol name="jrmp" noCmi="false" /&gt;
        &lt;/jndi&gt;
        &lt;viewManager  <co xml:id="cmi.server.viewmanager" />
            class="org.ow2.cmi.controller.server.impl.jgroups.JGroupsClusterViewManager"&gt; <co
            xml:id="cmi.server.viewmanager.class" />
            &lt;jgroups:config <co xml:id="cmi.server.viewmanager.jgroups" />
                    delayToRefresh="60000" <co
            xml:id="cmi.server.viewmanager.jgroups.delay" />
                    loadFactor="100" <co
            xml:id="cmi.server.viewmanager.jgroups.loadfactor" />
                    confFileName="jgroups-cmi.xml" <co
            xml:id="cmi.server.viewmanager.jgroups.conffile" />
                    recoTimeout="30000" <co
            xml:id="cmi.server.viewmanager.jgroups.recoto" />
                    groupName="G1"&gt; <co
            xml:id="cmi.server.viewmanager.jgroups.group" />
                &lt;components&gt; <co
            xml:id="cmi.server.viewmanager.jgroups.components" />
                 &lt;event /&gt;
                &lt;/components&gt;
            &lt;/jgroups:config&gt;
        &lt;/viewManager&gt;
    &lt;/server&gt;
&lt;/cmi&gt;

</screen>
      </example>

      <calloutlist>
        <callout arearefs="cmi.server.jndi">
          <para><literal>jndi</literal> element - optional. Enable to specify
          that a protocol must not be clustered with CMI (administration uses,
          ...). Here, the clustering of <literal>jrmp</literal> protocol can
          be disabled by setting <literal>true</literal> to the
          <literal>noCmi</literal> attribute.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager">
          <para><literal>viewManager</literal> element - mandatory. Defines
          the view manager configuration (registry replication, refresh time,
          ...).</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.class">
          <para><literal>class</literal> attribute - mandatory. Specifies the
          protocol implementation to use for replicating the view (CMI
          registry). Here the JGroups implementation is set.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups">
          <para><literal>jgroups:config</literal> element - mandatory. Define
          the JGroups related parameters.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups.delay">
          <para><literal>delayToRefresh</literal> attribute - optional.
          Refresh period of the client view (in ms). For example, it expresses
          the maximum delay for taking into account a load-balancing parameter
          update.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups.loadfactor">
          <para><literal>loadFactor</literal> attribute - optional. Specifies
          the initial load-factor of the current node used in the weigthed
          round robin policy.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups.conffile">
          <para><literal>confFileName</literal> attribute - mandatory.
          Specifies the JGroups's stack configuration filename (found in the
          <filename>$JONAS_BASE/conf</filename> directory).</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups.recoto">
          <para><literal>recoTimeout</literal> attribute - optional. Specifies
          the reconnection timeout after a shunning or an error in the group
          communication protocol (in ms). If the timer expires, an exception
          is thrown.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups.group">
          <para><literal>groupName</literal> attribute - mandatory. Specifies
          the JGroups channel name used by the CMI cluster view replication
          mechanism.</para>
        </callout>

        <callout arearefs="cmi.server.viewmanager.jgroups.components">
          <para><literal>components</literal> element - mandatory. Enable the
          events component into CMI. This element must not be modified.</para>
        </callout>
      </calloutlist>
    </para>

    <note>
      <para>Refer to <link xlink:href="clustering_guide.html#faq.jgroups">the
      clustering guide</link> for issues related to JGroups.</para>
    </note>
  </section>

  <section>
    <info>
      <title>Client mode configuration</title>
    </info>

    <para>The client element contains the following elements:</para>

    <para>
      <example>
        <title>Configuring the cmi service in the client mode</title>

        <screen>
  
&lt;cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;

    &lt;client noCmi="false"&gt; <co xml:id="cmi.client.nocmi" />
    	&lt;jndi&gt; <co xml:id="cmi.client.jndi" />
        	&lt;protocol name="jrmp"&gt;
            	&lt;providerUrls&gt; 
                	&lt;providerUrl&gt;rmi://localhost:1099&lt;/providerUrl&gt;
                	&lt;providerUrl&gt;rmi://localhost:2001&lt;/providerUrl&gt;
            	&lt;/providerUrls&gt;
        	&lt;/protocol&gt;
    	&lt;/jndi&gt;
    &lt;/client&gt;
&lt;/cmi&gt;

</screen>
      </example>

      <calloutlist>
        <callout arearefs="cmi.client.nocmi">
          <para><literal>noCmi</literal> attribute - optional. Enable to
          specify that CMI must be disabled.</para>
        </callout>

        <callout arearefs="cmi.client.jndi">
          <para><literal>jndi</literal> element - mandatory. Specify a list of
          providers URLs for a given protocol. It is not necessary to set the
          whole list of cluster members, a subset is enough. However for
          ensuring high availability, at least two providers URLs must be
          mentionned.</para>
        </callout>
      </calloutlist>
    </para>
  </section>

  <para />
</section>
