<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../User_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="javaconf">
  <title>java configuration</title>

  <sect1>
    <title>JBoss AS</title>

    <para>The entry point for configuring mod_cluster withing JBoss AS is the
    server.xml file within JBoss Web service.  This file is located at
    $JBOSS_HOME/server/<emphasis>profile</emphasis>/deploy/jbossweb.sar/server.xml</para>

    <sect2>
      <title>Lifecycle listener</title>

      <para>mod_cluster leverages a &lt;Listener/&gt; to inform itself of web
      container lifecycle events, e.g. deploy/undeploy of a web application,
      startup/shutdown of the server, etc.</para>

      <para>We use the generic MicrocontainerIntegrationLifecycleListener to
      delegate all lifecycle events to a bean deployed by the JBoss
      microcontainer.</para>

        <para>mod_cluster 1.0.x is wired directly to the Catalina container
        API.  Catalina lifecycle events are delegated directly to
        mod_cluster's core service.<programlisting>&lt;Listener className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener" 
          delegateBeanName="ModClusterService"/&gt;&lt;!-- Non-clustered mode --&gt; 
&lt;!--Listener className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener" 
          delegateBeanName="HAModClusterService"/--&gt;&lt;!-- Clustered mode --&gt;</programlisting></para>

        <para>To ensure that the delegate bean exists before the JBoss Web
        service starts, and that the bean does not get destroyed until the
        service shuts down, we must add an explicit microcontainer dependency
        to the JBoss Web service.  To do this, update the WebServer bean
        contained in
        $JBOSS_HOME/server/<emphasis>profile</emphasis>/deploy/jbossweb.sar/META-INF/jboss-beans.xml
        with the appropriate dependency:<programlisting>&lt;bean name="WebServer" class="org.jboss.web.tomcat.service.deployers.TomcatService"&gt; 
  &lt;!-- ... --&gt; 
  &lt;depends&gt;ModClusterService&lt;/depends&gt;&lt;!-- Non-clustered mode --&gt; 
  &lt;!--depends&gt;HAModClusterService&lt;/depends--&gt;&lt;!-- Clustered mode --&gt; 
  &lt;!-- ... --&gt; 
&lt;/bean&gt;</programlisting></para>

        <para>For details of how to configure
        <link linkend="local">ModClusterService</link>
        or
        <link linkend="HAModClusterService">HAModClusterService</link>
        refer to the appropriate section.</para>
    </sect2>

    <sect2>
      <title>Connectors</title>

      <para>Like mod_jk and mod_proxy_balancer, mod_cluster requires a
      connector in your server.xml on which to forward web requests.
       mod_cluster is not confined to AJP, but can use HTTP as well.  If
      multiple possible connectors are available, mod_cluster uses the
      following algorithm to choose between them: </para>

      <orderedlist>
        <listitem>
          <para>If an native (APR) AJP connector is available, use it</para>
        </listitem>

        <listitem>
          <para>If an AJP connector is available, use it</para>
        </listitem>

        <listitem>
          <para>Otherwise, choose the connector with the highest max
          threads.</para>
        </listitem>
      </orderedlist>

      <para>e.g.<programlisting>&lt;Server&gt; 
  &lt;!-- ... --&gt; 
  &lt;Service name="jboss.web"&gt; 
    &lt;Connector protocol="HTTP/1.1" port="${jboss.web.http.port}" address="${jboss.bind.address}" redirectPort="${jboss.web.https.port}"/&gt; 
    &lt;Connector protocol="AJP/1.3" port="${jboss.web.ajp.port}" address="${jboss.bind.address}" redirectPort="${jboss.web.https.port}"/&gt; 
    &lt;Engine name="jboss.web" defaultHost="localhost"&gt; 
      &lt;!-- ... --&gt; 
    &lt;/Engine&gt; 
  &lt;/Service&gt; 
&lt;/Server&gt;</programlisting></para>
    </sect2>

    <sect2>
      <title>Node Identity</title>

      <para>Like mod_jk and mod_proxy_balancer, mod_cluster identifies each
      node via a unique jvm route.  The is specified using the <ulink
      url="http://tomcat.apache.org/tomcat-6.0-doc/config/engine.html#Common%20Attributes">jvmRoute</ulink>
      attribute of the Engine within server.xml.</para>

      <para>Users must define jvm routes
      manually, perhaps using system property expansion, e.g.
      jvmRoute="${jboss.mod_cluster.jvmRoute}"</para>
    </sect2>

    <sect2 id="local">
      <title>Non-Clustered Mode</title>

      <para>mod_cluster can operate in 2 modes: non-clustered or
      <link linkend="HAModClusterService">clustered</link>.
       In non-clustered mode, each JBoss server node communicates with a httpd
      proxy directly, and do not communicate with each other.  Non-clustered
      mode is powered by the ModClusterService, whose definition varies
      depending on the version of mod_cluster in use.</para>

      <para>In general, ModClusterService defines:</para>

      <orderedlist>
        <listitem>
          <para>A set of
          <link linkend="javaproperties"> configuration properties</link></para>
        </listitem>

        <listitem>
          <para>A mechanism for
          <link linkend="javaload">providing the
          load balance factor</link>  to a proxy</para>
        </listitem>
      </orderedlist>

        <para>In version 1.0.x, all mod_cluster configuration properties are
        members of the ModClusterService bean itself:<programlisting>&lt;bean name="ModClusterService" class="org.jboss.modcluster.ModClusterService" mode="On Demand"&gt; 
  &lt;constructor&gt; 
    &lt;parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"&gt; 
      &lt;inject bean="DynamicLoadBalanceFactorProvider"/&gt; 
    &lt;/parameter&gt; 
  &lt;/constructor&gt; 
  &lt;!-- Configuration properties go here --&gt; 
  &lt;property name="advertise"&gt;true&lt;/property&gt; 
&lt;/bean&gt;</programlisting></para>
    </sect2>

    <sect2 id="HAModClusterService">
      <title>Clustered Mode</title>

      <para>mod_cluster can operate in 2 modes:
      <link linkend="local">non-clustered</link>
      or clustered.  In clustered mode, a single JBoss node (the HA singleton
      master) communicates with the httpd proxy on behalf of the other nodes
      in the cluster.  This mode offers the following advantages over
      non-clustered mode:</para>

      <orderedlist>
        <listitem>
          <para>The state of each proxy will be kept in sync on each node in
          the cluster.</para>
        </listitem>

        <listitem>
          <para>Proxies will be proactively notified of view changes, most
          notably, crashed members, allowing a proxy to gracefully reconfigure
          itself to avoiding failover processing.</para>
        </listitem>

        <listitem>
          <para>Adds domain management functionality, providing the ability to
          enable, disable, or gracefully stop all nodes sharing the same
          domain.  A domain is a logical grouping of nodes, typically
          representing a replication "buddy group".</para>
        </listitem>
      </orderedlist>

      <para>Clustered mode is instrumented using JBoss clustering technologies
      and is configured via the HAModClusterService bean, the definition of
      which varies slightly between mod_cluster versions.</para>

      <para>In general, HAModClusterService defines:</para>

      <orderedlist>
        <listitem>
          <para>A set of
          <link linkend="javaproperties"> configuration properties</link></para>
        </listitem>

        <listitem>
          <para>A mechanism for
          <link linkend="javaload">providing the
          load balance factor</link> to a proxy</para>
        </listitem>

        <listitem>
          <para>An HAPartition, the JBoss clustering group communication
          building block.  The default HAPartition is defined
          in:$JBOSS_HOME/server/<emphasis>profile</emphasis>/deploy/cluster/hapartition-jboss-beans.xml</para>
        </listitem>
      </orderedlist>

        <para><programlisting>&lt;bean name="HAModClusterService" class="org.jboss.modcluster.ha.HAModClusterService" mode="On Demand"&gt; 
  &lt;annotation&gt;@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=ModCluster",exposedInterface=org.jboss.modcluster.ha.HAModClusterServiceMBean.class)&lt;/annotation&gt; 
  &lt;constructor&gt; 
    &lt;parameter class="org.jboss.ha.framework.interfaces.HAPartition"&gt; 
      &lt;inject bean="HAPartition"/&gt; 
    &lt;/parameter&gt; 
    &lt;parameter class="org.jboss.modcluster.config.ha.HAModClusterConfig"&gt; 
      &lt;inject bean="HAModClusterConfig"/&gt; 
    &lt;/parameter&gt; 
    &lt;parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"&gt; 
      &lt;inject bean="DynamicLoadBalanceFactorProvider"/&gt; 
    &lt;/parameter&gt; 
    &lt;parameter class="org.jboss.ha.framework.interfaces.HASingletonElectionPolicy"&gt; 
      &lt;bean class="org.jboss.ha.singleton.HASingletonElectionPolicySimple"/&gt; 
    &lt;/parameter&gt; 
  &lt;/constructor&gt; 
&lt;/bean&gt; 
&lt;bean name="HAModClusterConfig" class="org.jboss.modcluster.config.ha.HAModClusterConfig" mode="On Demand"&gt; 
  &lt;property name="advertise"&gt;true&lt;/property&gt; 
&lt;/bean&gt;</programlisting></para>
    </sect2>
  </sect1>

  <sect1 id="tomcat">
    <title>JBoss Web &amp; Tomcat</title>

    <para>In the absence of the ability for complex configuration,
    mod_cluster's entire configuration for JBoss Web or Tomcat resides
    entirely within $CATALINA_HOME/conf/server.xml.</para>

    <para>This adds the following constraints to mod_cluster's feature
    set:</para>

    <orderedlist>
      <listitem>
        <para>Only non-clustered mode is supported</para>
      </listitem>

      <listitem>
        <para>
        <link inkend="javaload"> Only one
        load metric</link> can be used in the load balance factor
        calculation</para>
      </listitem>
    </orderedlist>

    <sect2>
      <title>Lifecycle Listener</title>

      <para>The entry point for JBoss Web and Tomcat configuration is the
      ModClusterListener.  All mod_cluster
      <link linkend="javaproperties"> configuration
      properties</link> are defined as attributes of the Listener
      element.</para>

        <para><programlisting>&lt;Listener className="org.jboss.modcluster.ModClusterListener" 
          advertise="true"/&gt;</programlisting></para>
    </sect2>

    <sect2>
      <title>Additional Tomcat dependencies</title>

      <para>mod_cluster uses jboss-logging, which exists in JBoss Web, but not
      in Tomcat. Consequently, to use mod_cluster with Tomcat, it is necessary
      to add <ulink
      url="http://repository.jboss.org/jboss/common-logging-spi/">jboss-logging-spi.jar</ulink>
      to $CATALINA_HOME/lib.</para>
    </sect2>
  </sect1>
</chapter>
