<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" 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>Cluster member management</title>
  </info>

  <section>
    <info>
      <title>What is a cluster</title>
    </info>

    <para>A cluster is a group of JOnAS instances. The servers within a
    cluster are called cluster members. A server may be a member of several
    clusters in the domain.</para>

    <para>A cluster is an administration target in the domain: from the common
    administration point of view, the administrator may monitor the cluster
    or apply to it management operations like deploy or undeploy of applications.</para>
  </section>

  <section>
    <info>
      <title>Cluster types</title>
    </info>

    <para>There are two main cluster categories:</para>

    <itemizedlist>
      <listitem>
        <para>Clusters containing instances that are grouped together only to
        facilitate management tasks.</para>
      </listitem>

      <listitem>
        <para>Clusters containing instances that are grouped together to achieve
        objectives like scalability, high availability or failover.</para>
      </listitem>
    </itemizedlist>

    <para>The clusters in the first category, called <xi:include
    href="../clustering-variables.xml" xpointer="element(logical.cluster)" />,
    are created by the domain administrator based on his/her particular needs. The
    grouping of servers (the cluster creation) can be done even though the
    servers are running.</para>

    <para>In the second case, the servers which compose a cluster must have a
    particular configuration that allows them to achieve the expected
    objectives. Once servers are started, the administration framework is able to
    automatically detect that they are cluster members, based on configuration
    criteria. Several cluster types are supported by the JOnAS administration
    framework. They correspond to the different roles a cluster can
    play:</para>

    <itemizedlist>
      <listitem>
        <para><xi:include href="../clustering-variables.xml"
        xpointer="element(jk.cluster)" /> - allow HTTP request load balancing
        and failover based on the mod_jk Apache connector.</para>
      </listitem>

      <listitem>
        <para><xi:include href="../clustering-variables.xml"
        xpointer="element(tomcat.cluster)" /> - allow high availability at
        web level based on the Tomcat 5.5 session replication solution. Tomcat 6 will
        be supported soon.</para>
      </listitem>

      <listitem>
        <para><xi:include href="../clustering-variables.xml"
        xpointer="element(cmi.cluster)" /> - enable JNDI clustering and
        allows load balancing at EJB level, based on the CMI protocol</para>
      </listitem>

      <listitem>
        <para><xi:include href="../clustering-variables.xml"
        xpointer="element(ha.cluster)" /> - allow transaction aware failover
        at EJB level and stateful session bean replication.</para>
      </listitem>

      <listitem>
        <para><xi:include href="../clustering-variables.xml"
        xpointer="element(joram.cluster)" /> - allow JMS destinations
        scalability based on the JORAM distributed solution.</para>
      </listitem>

      <listitem>
        <para><xi:include href="../clustering-variables.xml"
        xpointer="element(joram.ha)" /> - allow JMS destinations high availability
        based on JORAM HA.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <info>
      <title>Logical clusters configuration</title>
    </info>

    <para>An administrator can create a cluster if he/she needs to group some
    servers into a single administration target. There is no predefined
    criteria to explicitly group servers for administration purpose.</para>

    <para>Cluster names and topology can be defined in a static way, using the
    domain configuration file <filename>domain.xml</filename>. Here is an
    example allowing to create a cluster named <literal>mycluster</literal> in
    <literal>sampleDomain</literal> domain, in which servers
    <literal>node1</literal> and <literal>node2</literal> are grouped together
    for administration purpose.</para>

    <screen>&lt;domain xsi:schemaLocation="http://www.objectweb.org/jonas/ns
         http://www.objectweb.org/jonas/ns/jonas-domain_4_9.xsd"&gt;
&lt;name&gt;sampleDomain&lt;/name&gt;
&lt;description&gt;A domain example&lt;/description&gt;
  &lt;cluster&gt;
  &lt;name&gt;mycluster&lt;/name&gt;
  &lt;description&gt;A cluster example&lt;/description&gt;
    &lt;server&gt;
      &lt;name&gt;node1&lt;/name&gt;
      &lt;location&gt;
        &lt;url&gt;service:jmx:rmi://myhost/jndi/jrmp://myhost:2002/jrmpconnector_node1&lt;/url&gt;
      &lt;/location&gt;
    &lt;/server&gt;
    &lt;server&gt;
      &lt;name&gt;node2&lt;/name&gt;
      &lt;location&gt;
        &lt;url&gt;service:jmx:rmi://myhost/jndi/jrmp://myhost:2003/jrmpconnector_node2&lt;/url&gt;
      &lt;/location&gt;
    &lt;/server&gt;
  &lt;cluster&gt;
&lt;domain&gt;</screen>

    <para>Clusters can also be created dynamically via the
          JonasAdmin management console application running on the master.
    </para>
  </section>

  <section>
    <info>
      <title>JkCluster configuration</title>
    </info>

    <para>The configuration of <xi:include href="../clustering-variables.xml"
      xpointer="element(jk.cluster)" /> is described in the <link linkend="clustering.configuration">clustering
      configuration chapter.</link>
      This section explains how to make such a cluster manageable from a domain master node.
    </para>


      <para>To allow cluster member discovery and dynamic cluster creation,
      the <filename>workers.properties</filename> file required by mod_jk
      should be copied to the master's JONAS_BASE/conf directory.</para>

      <para>At start-up, the master reads the
      <filename>workers.properties</filename> file content. For each balanced
      worker it checks if there is a running server in the domain having the
      appropriate configuration allowing the server to play that worker
      role.</para>

      <para>Suppose that the master detects a server in the domain
      corresponding to worker1. Then, it constructs a <xi:include
      href="../clustering-variables.xml" xpointer="element(jk.cluster)" /> named
      <literal>loadbalancer</literal>. This name is given by the load
      balancer worker's name. At this time, the cluster is composed of one
      member named <literal>worker1</literal>. The member name is given by the
      balanced worker's name.</para>

      <para>After a while, a new JOnAS server is started in the domain having
      the configuration corresponding to the <literal>worker2</literal>. The
      master detects the new member named worker2 and updates the cluster's
      member list.</para>

      <para>Here is the <literal>loadbalancer</literal> <xi:include
      href="../clustering-variables.xml" xpointer="element(jk.cluster)" /> with
      workers started, as it appears in the jonasAdmin console of the master:</para>

      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata align="center"
                       fileref="../../../../resources/images/clustering/domain.jk.cluster.png"
                       width="70%" scalefit="1">
            </imagedata>
          </imageobject>
        </mediaobject>
      </informalfigure>
      <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata align="center"
                       fileref="../../../../resources/images/clustering/domain.jk.cluster.member.png"
                       width="70%" scalefit="1">
            </imagedata>
          </imageobject>
        </mediaobject>
      </informalfigure>
    </section>

  <section>
    <info>
      <title>TomcatCluster configuration</title>
    </info>

    <para>The configuration of <xi:include href="../clustering-variables.xml"
      xpointer="element(tomcat.cluster)" /> is described in the <link linkend="clustering.configuration">clustering
      configuration chapter.</link>
    </para>

    <para><note>
        <para>the <property>clusterName</property> attribute is mandatory (and
        not set by default in <filename>tomcat6-server.xml</filename> file). It must be unique
        in the domain and is used for identifying the cluster.</para>
      </note></para>

    <para>For example, lets consider the two JOnAS servers which play the role of
    <literal>worker1</literal> and <literal>worker2</literal> in the
    <literal>myloadbalancer</literal> <xi:include
    href="../clustering-variables.xml" xpointer="element(jk.cluster)" />. Suppose
    that these servers, named <literal>node1</literal> and
    <literal>node2</literal> are configured as members of the
    <literal>myTomcatCluster</literal> <xi:include
    href="../clustering-variables.xml" xpointer="element(tomcat.cluster)" />. The
    master detects automatically the Tomcat cluster membership and creates a
    <xi:include href="../clustering-variables.xml"
    xpointer="element(tomcat.cluster)" /> named
    <literal>myTomcatCluster</literal>. It adds <literal>node1</literal> and
    <literal>node2</literal> to the cluster's member list.</para>

    <para>Here is myTomcatCluster cluster with node1 and node2 members
    running, as it appears in the console</para>

    <para><informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata align="center"
                       fileref="../../../../resources/images/clustering/myTomcatCluster.gif"
                       width="70%" scalefit="1">
            </imagedata>
          </imageobject>
        </mediaobject>
      </informalfigure></para>
  </section>

  <section>
    <info>
      <title>CmiCluster configuration</title>
    </info>

    <para>The configuration of <xi:include href="../clustering-variables.xml"
      xpointer="element(cmi.cluster)" /> is described in the <link linkend="clustering.configuration">clustering
      configuration chapter.</link>
    </para>

    <para>The CMI cluster is automatically detected from the master node (CMI MBeans discovery). As a result,
    the following information is provided:
    </para>

    <informalfigure>
        <mediaobject>
          <imageobject>
            <imagedata align="center"
                       fileref="../../../../resources/images/clustering/domain.cmi.cluster.png"
                       width="70%" scalefit="1">
            </imagedata>
          </imageobject>
        </mediaobject>
    </informalfigure>

  </section>
</section>
