<?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>Management</title>
  </info>

  <section>
    <info>
      <title>Domain management</title>
    </info>

    <para>Each JOnAS instance can be managed through a local jonasAdmin console. The <emphasis>domain management</emphasis>
    enables to manage a set of JOnAS instances from a centralized jonasAdmin console.</para>

    <para>A domain is a set of JOnAS instances that are running under the same management authority. The instances within
    a domain can be standalone, distributed or gathered in a cluster as well. The instances are managed from an unique console
    deployed in a dedicated JOnAS instance named <emphasis>master</emphasis>, configured with the domain management enabled.</para>

    <para>Domain management is composed of the following features:</para>
     <itemizedlist>
      <listitem><emphasis>discovery service</emphasis> for detecting automatically the instances and the clusters.</listitem>
      <listitem><emphasis>JOnAS instance and cluster monitoring</emphasis> for maintaining a JOnAS instance state view and a cluster view as well as
      for tracking some indicators.</listitem>
      <listitem><emphasis>JOnAS instance control</emphasis> for remote starting or remote stopping of the JOnAS instances.</listitem>
      <listitem><emphasis>domain-wide deployment</emphasis> for deploying Java EE modules across a set of JOnAS instances or clusters.</listitem>
      <listitem><emphasis>instance configuration</emphasis> for setting or retrieving a configuration attribute from a JOnAS instance as available through
      a local jonasAdmin console.</listitem>    </itemizedlist>

    <para>Several interfaces are provided:</para>
     <itemizedlist>
      <listitem><emphasis>console</emphasis> with the centralized jonasAdmin console.</listitem>
      <listitem><emphasis>command</emphasis> with the jonas admin command which has been extended to deal with domain.</listitem>
      <listitem><emphasis>JMX</emphasis> through some domain management MBeans.</listitem>
    </itemizedlist>

    <para>The domain management is optional. When enabled, JOnAS instance within a domain must have an uniq name instance.</para>

  </section>

   <section>
    <info>
      <title>Domain management architecture</title>
    </info>

    <para>The domain management relies on:</para>
    <itemizedlist>
      <listitem><emphasis>MBeans objects</emphasis> deployed in each JOnAS instance and accessible through the JMX remote interface.</listitem>
      <listitem><emphasis>One or several management JOnAS instances masters</emphasis> hosting the domain management features.</listitem>
      <listitem><emphasis>Optionaly some cluster daemons</emphasis> enabling to control remotely the JOnAS instances.</listitem>
     </itemizedlist>
    <mediaobject>
      <imageobject role="html">
        <imagedata align="center"
                   fileref="../../../../resources/images/clustering/domainmngt.png"
                   width="80%" scalefit="1">
        </imagedata>
      </imageobject>
    </mediaobject>

    <section>
      <info>
        <title>Master instance</title>
      </info>

      <para>A dedicated JOnAS is assigned with the master role which enables the domain management feature. The jonasAdmin console is deployed
      in this instance and is no more necessary in the others ones.</para>

      <para>The domain management functions are exposed through a set of MBeans that are used by the jonasAdmin console.</para>

      <para>The master instance interacts with the managed JOnAS instances and the cluster daemons through JMX. The master node periodically polls
      the managed instances for providing states and statistics.</para>

      <para>Several master instances can be defined for high availability, only one must be enabled at one point.</para>

    </section>

   <section>
      <info>
        <title>Cluster daemon</title>
      </info>

      <para>The cluster daemon is in charge of controlling the JOnAS instances (start/stop) that are collocated on the same machine. It is an optional component
      in the domain management infrastructure and can be added on an existing configuration.</para>

      <para>It is accessible through a JMX Remote interface and provides the start/stop operations. By default, it relies on the native JOnAS command for
      driving the JOnAS instances. The user may put its own commands for setting a particular environment before starting/stopping a JOnAS node.</para>

    </section>

   <section>
      <info>
        <title>Managed instance</title>
      </info>

      <para>The managed JOnAS instances must respect some conventions for domain management: </para>

      <itemizedlist>
        <listitem>the managed instance must be aware of the domain.</listitem>
        <listitem>the managed instance must have an unique name in the domain.</listitem>
     </itemizedlist>

      <para>Both domain name and instance name are specified in the starting command:
            <literal>jonas start -n <emphasis>instance_name</emphasis> -Ddomain.name=<emphasis>domain_name</emphasis></literal>.</para>

    </section>

   <section>
      <info>
        <title>Discovery service</title>
      </info>

      <para>The discovery service aims at detecting when a new JOnAS instance appears or when a JOnAS instance leaves the domain. It enables
      the master instance to retrieve the managed instances without any prior informations about them.</para>

      <para>Two implementations of the discovery service are available (the choice is done by configuration):</para>
      <itemizedlist>
        <listitem>a <emphasis>IP multicast based</emphasis> implementation.</listitem>
        <listitem>a <emphasis>JGroups based</emphasis> implementation. The group communication protocol stack can be configured on top of UDP
        or TCP.</listitem>
     </itemizedlist>
	 <para>The first one relies on IP multicast whereas the second one uses point to point communication.</para>
     <para>If the managed instances cannot be discovered automatically due to the network configuration or the administration policies, the domain
     topology can be described statically in the <emphasis>domain.xml</emphasis> file.</para>

    </section>

   <section>
      <info>
        <title>Administration interfaces</title>
      </info>

     <para>JOnAS provides different administration interfaces:</para>
      <itemizedlist>
        <listitem>a <emphasis>graphical console</emphasis> with jonasAdmin console that can be centralized if deployed in the master instance.</listitem>
        <listitem>a <literal>jonas admin</literal> command has been extended for supporting the domain management feature (remote control, cluster-wide
        deployment and so on.</listitem>
        <listitem>a <emphasis>JMX interface</emphasis> through the JOnAS MBeans.</listitem>
        <listitem>a <emphasis>EJB interface</emphasis> through the mejb.</listitem>
        <listitem>a <emphasis>Web Service interface</emphasis> through the mejb.</listitem>

     </itemizedlist>

    </section>

  </section>

   <section>
    <info>
      <title>Cluster management</title>
    </info>

    <para>For the management point of view, a cluster is a group of JOnAS instances. The JOnAS instances within a
    cluster are called cluster members. A JOnAS instance 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>

    <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 management domain feature is able to
    automatically detect that they are cluster instances, based on configuration
    criteria and MBeans discovery. Several cluster types are supported by the domain
    management function. 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 HTTP session replication solution.</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 stateful session bean high availability.</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>JASMINe project</title>
    </info>

    <para>Advanced administration features are provided through the <link xlink:href="http://jasmine.ow2.org">JASMINe</link> project:</para>
    <itemizedlist>
      <listitem><emphasis>JASMINe Design</emphasis> for building a cluster configuration through a graphical interface.</listitem>
      <listitem><emphasis>JASMINe Deploy</emphasis> both for deploying the middleware and the applications across a distributed infrastructure.</listitem>
      <listitem><emphasis>JASMINe Monitoring</emphasis> for helping the operator to detect errors and for tracking the performance.</listitem>
      <listitem><emphasis>JASMINe SelfManagement</emphasis> for improving the system reliability and performance automatically.</listitem>
    </itemizedlist>

  </section>

</section>
