<?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="java.config">
  <title id="java.config.title">Server-side Configuration</title>
  
  <section id="ModClusterListener">
    <title>JBoss AS</title>
    <!--para>
      As of JBoss AS 6.0, mod_cluster is integrated into the <emphasis>all</emphasis> and <emphasis>default</emphasis> profiles by default.
    </para>
    <para>
      Using JBoss AS 5.x, you must copy the <code>mod_cluster.sar</code> directory from the server-side binary distribution into your target profile's deploy directory.
    </para-->
    <para>mod_cluster is supported in AS7 via the modcluster subsystem See  <link linkend="java.AS7config">AS7</link>.</para>
    <para>In other AS version mod_cluster's configuration resides within the following file:</para>
    <para><code>$JBOSS_HOME/server/$PROFILE/deploy/mod_cluster.sar/META-INF/mod_cluster-jboss-beans.xml</code> file.</para>
    <para>
      The entry point for mod_cluster's server-side configuration is the <code>ModClusterListener</code> bean, which delegates web container (i.e. JBoss Web) specific events to a container agnostic event handler.
    </para>
    <para>In general, the <code>ModClusterListener</code> bean defines:</para>
    <orderedlist>
      <listitem>
        <para>
          A <code>ContainerEventHandler</code> in which to handle events from the web container.
          There are two available implementations, the choice of which dictates the mode in which mod_cluster will operate: <link linkend="HAModClusterService">clustered</link> or <link linkend="ModClusterService">non-clustered</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          A reference to the JBoss mbean server.
        </para>
      </listitem>
    </orderedlist>
    <para>e.g.</para>
<programlisting><![CDATA[<bean name="ModClusterListener" class="org.jboss.modcluster.container.jbossweb.JBossWebEventHandlerAdapter"> 
  <constructor> 
    <parameter class="org.jboss.modcluster.container.ContainerEventHandler"> 
      <inject bean="ModClusterService"/><!-- Non-clustered mode --> 
      <!--inject bean="HAModClusterService"/--><!-- Clustered mode --> 
    </parameter> 
    <parameter class="javax.management.MBeanServer"> 
      <inject bean="JMXKernel" property="mbeanServer"/> 
    </parameter> 
  </constructor> 
</bean>]]></programlisting>
    <section id="ModClusterService">
      <title>Non-clustered mode</title>
      <para>
        In non-clustered mode, each JBoss AS node communicates with the load balancer directly, and do not communicate with each other.
        Non-clustered mode is configured via the <code>ModClusterService</code> bean.
      </para>
      <para>In general, the <code>ModClusterService</code> bean defines:</para>
      <orderedlist>
        <listitem>
          <para>
            An object containing mod_cluster's <link linkend="ModClusterConfig">configuration properties</link>.
          </para>
        </listitem>
        <listitem>
          <para>
            An object responsible for calculating the load balance factor for this node.
            This is described in detail in the chapter entitled <link linkend="java.load" endterm="java.load.title"/>.
          </para>
        </listitem>
      </orderedlist>
      <para>e.g.</para>
<programlisting><![CDATA[<bean name="ModClusterService" class="org.jboss.modcluster.ModClusterService" mode="On Demand"> 
  <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=ModCluster",exposedInterface=org.jboss.modcluster.ModClusterServiceMBean.class)</annotation> 
  <constructor> 
    <parameter class="org.jboss.modcluster.config.ModClusterConfig"> 
      <inject bean="ModClusterConfig"/> 
    </parameter> 
    <parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider"> 
      <inject bean="DynamicLoadBalanceFactorProvider"/> 
    </parameter> 
  </constructor> 
</bean>]]></programlisting>
    </section>
    <section id="HAModClusterService">
      <title>Clustered mode</title>
      <para>
        In clustered mode, a single JBoss node (the HA singleton master) communicates with the load balancer on behalf of the other nodes in the cluster.
        Clustered mode is configured via the <code>HAModClusterService</code> bean.
        This mode offers the following advantages over non-clustered mode:
      </para>
      <orderedlist>
        <listitem>
          <para>The state of the load balancer will be kept in sync on each node in the cluster.</para>
        </listitem>
        <listitem>
          <para>mod_cluster will proactively notify the load balancer of view changes (i.e. crashed members), allowing the load balancer to gracefully reconfigure itself thus avoiding costly failover processing.</para>
        </listitem>
        <listitem>
          <para>
            Clustered-mode allows load balancing group management, adding the ability to enable, disable, or gracefully stop all nodes sharing the same load balancing group.
            Once a given session is associated with a specific node, subsequent requests for the same session will always prefer to be routed to a node with the same load balancing group.
            Grouping nodes in this way is useful for limiting the number of nodes to which a given session must replicate to support high-availability.
            When used in conjunction with sessions affinity, a load balancing group effectively narrows the set of preferred failover nodes to members of the same load balancing group.
            A load balancing group is conceptually similar to a <emphasis>domain</emphasis> in mod_jk.
          </para>
        </listitem>
      </orderedlist>
      <para>In general, HAModClusterService defines:</para>
      <orderedlist>
        <listitem>
          <para>
            An object containing mod_cluster's <link linkend="ModClusterConfig">configuration properties</link>.
          </para>
        </listitem>
        <listitem>
          <para>
            An object responsible for calculating the load balance factor for this node.
            This is described in detail in the chapter entitled <link linkend="java.load" endterm="java.load.title"/>.
          </para>
        </listitem>
        <listitem>
          <para>
            An <code>HAPartition</code>, the JBoss clustering group communication building block.
            The default HAPartition is defined in:
            <code>$JBOSS_HOME/server/$PROFILE/deploy/cluster/hapartition-jboss-beans.xml</code>
          </para>
        </listitem>
        <listitem>
         <para>A policy for determining which group member should be designated as the singleton master.</para>
        </listitem>
      </orderedlist>
      <para>e.g.</para>
<programlisting><![CDATA[<bean name="HAModClusterService" class="org.jboss.modcluster.ha.HAModClusterService" mode="On Demand">
  <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=ModCluster",exposedInterface=org.jboss.modcluster.ha.HAModClusterServiceMBean.class)</annotation>
  <constructor>
    <parameter class="org.jboss.modcluster.config.ha.HAModClusterConfig">
      <inject bean="ModClusterConfig"/>
    </parameter>
    <parameter class="org.jboss.modcluster.load.LoadBalanceFactorProvider">
      <inject bean="DynamicLoadBalanceFactorProvider"/>
    </parameter>
    <parameter class="org.jboss.ha.framework.interfaces.HAPartition">
      <inject bean="HAPartition"/>
    </parameter>
    <parameter class="org.jboss.ha.framework.interfaces.HASingletonElectionPolicy">
      <bean class="org.jboss.ha.singleton.HASingletonElectionPolicySimple"/>
    </parameter>
  </constructor>
</bean>]]></programlisting>
    </section>
    
    <section id="ModClusterConfig">
      <title>Configuration Properties</title>
      <para>
        The <code>ModClusterConfig</code> bean enumerates the configuration properties used by mod_cluster.
        For the complete list of configuration properties and their default values, see the chapter entitled <link linkend="java.properties" endterm="java.properties.title"/>.
      </para>
      <para>e.g.</para>
<programlisting><![CDATA[
<bean name="ModClusterConfig" class="org.jboss.modcluster.config.ha.HAModClusterConfig" mode="On Demand">
  <!-- Specify configuration properties here -->
</bean>]]></programlisting>
    </section>
    
    <section>
      <title>Connectors</title>
      <para>
        Like mod_jk and mod_proxy_balancer, mod_cluster requires a connector in your server.xml to which to forward web requests.
        Unlike mod_jk and mod_proxy_balancer, mod_cluster is not confined to AJP, but can use HTTP as well.
        While AJP is generally faster, an HTTP connector can optionally be secured via SSL.
        If multiple possible connectors are defined in your server.xml, 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 HTTP connector with the highest max threads.</para>
        </listitem>
      </orderedlist>
    </section>

    <section id="jvm-route">
      <title>Node Identity</title>
      <para>
        Like mod_jk and mod_proxy_balancer, mod_cluster identifies each node via a unique <ulink url="http://docs.jboss.org/jbossweb/2.1.x/config/engine.html">jvm route</ulink>.
        By default, mod_cluster uses the following algorithm to assign the jvm route for a given node:
      </para>
      <orderedlist>
        <listitem>
          <para>
            Use the value from <code>server.xml</code>, <code><![CDATA[<Engine jvmRoute="..."/>]]></code>, if defined.
          </para>
        </listitem>
        <listitem>
          <para>
            Generate a jvm route using the configured <link linkend="java.properties.jvmRouteFactory" endterm="java.properties.jvmRouteFactory"/>.
            The default implementation does the following:
            <orderedlist numeration="loweralpha">
              <listitem><para>Use the value of the <code>jboss.mod_cluster.jvmRoute</code> system property, if defined.</para></listitem>
              <listitem><para>Generate a UUID.</para></listitem>
            </orderedlist>
          </para>
        </listitem>
      </orderedlist>
      <para>
        While UUIDs are ideal for production systems, in a development or testing environment, it is useful to know which node served a given request just by looking at the jvm route.
        In this case, you can utilize the <code>org.jboss.modcluster.SimpleJvmRouteFactory</code>.
        The factory generates jvm routes of the form:
      </para>
      <para><emphasis>bind-address</emphasis>:<emphasis>port</emphasis>:<emphasis>engine-name</emphasis></para>
    </section>
  </section>

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

    <para>
      mod_cluster's entire configuration for JBoss Web or Tomcat resides entirely within <code>$CATALINA_HOME/conf/server.xml</code>.
    </para>
    <para>
      This limits the adds the following constraints to mod_cluster's feature set:
    </para>
    <itemizedlist>
      <listitem>
        <para>Only non-clustered mode is supported</para>
      </listitem>
      <listitem>
        <para><link linkend="java.load">Only one load metric</link> can be used to calculate a load factor.</para>
      </listitem>
    </itemizedlist>

    <section>
      <title>Lifecycle Listener</title>
      <para>
        The entry point for JBoss Web and Tomcat configuration is the ModClusterListener.
        All mod_cluster <link linkend="java.properties">configuration properties</link> are defined as attributes of the <code><![CDATA[<Listener/>]]></code> element.
        For the complete list of configuration properties and their default values, see the chapter entitled <link linkend="java.properties" endterm="java.properties.title"/>.
      </para>
      <para>e.g.</para>
      <programlisting><![CDATA[<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>]]></programlisting>
    </section>

    <section>
      <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/nexus/content/groups/public-jboss/org/jboss/logging/jboss-logging-spi/">jboss-logging-spi.jar</ulink>
      to $CATALINA_HOME/lib.</para>
    </section>
  </section>

  <section>
    <title>Migrating from 1.1.x</title>
    <para>
      In mod_cluster 1.2.x the web containers now are separed cleanly, that requires you to change
      standalone and mbean configuration a little.
    </para>
    <section>
      <title>mod_cluster-jboss-beans.xml</title>
      <para>
        The JBoss microcontainer configuration for mod_cluster 1.1.x is *not* compatible with the configuration for 1.2.x.
        you need to change the ModClusterListener mbean class to:
        "org.jboss.modcluster.container.jbossweb.JBossWebEventHandlerAdapter".
      </para>
    </section>
    <section>
      <title>server.xml</title>
      <para>
       You need to change the  <![CDATA[<Listener/>]]> element className to:
       "org.jboss.modcluster.container.catalina.standalone.ModClusterListener".
      </para>
    </section>
  </section>

  <section>
    <title>Migrating from 1.0.x</title>
    <para>
      In mod_cluster 1.0.x, you were required to make several manual configuration changes to the jbossweb service before mod_cluster would be usable.
      mod_cluster 1.1.x eliminates much of this hassle - and is designed to be fully functional out of the box.
    </para>
    <section>
      <title>Dependency with JBoss Web</title>
      <para>
        In 1.0.x, mod_cluster needed to be deployed <emphasis>before</emphasis> JBoss Web.
        This ensured that mod_cluster was available to handle web application deployment lifecycle events during triggered during server startup.
        To achieve this, you had to add an explicit dependency on mod_cluster to jbossweb's jboss-beans.xml config file.
      </para>
      <para>
        mod_cluster 1.1.x reverses this dependency, such that mod_cluster now depends on JBoss Web.
        Consequently, you no longer need to make any changes to JBoss Web's jboss-beans.xml file.
      </para>
      <para>
        As an additional consequence of this dependency reversal, mod_cluster can now be hot-deployed or undeployed to a running server without consequence to the JBoss Web service.
      </para>
    </section>
    <section>
      <title>server.xml</title>
      <section>
        <title>Lifecycle listener</title>
        <para>
          mod_cluster 1.0.x required you to add a lifecycle <![CDATA[<Listener/>]]> element to server.xml.
        </para>
        <section>
          <title>JBoss AS</title>
          <para>
            The <link linkend="ModClusterListener">ModClusterListener</link> bean now registers itself with the JBoss Web server upon deploying the mod_cluster service; and deregisters itself upon undeploy.
            Consequently, you no longer need to manually add a <![CDATA[<Listener/>]]> to server.xml.
          </para>
        </section>
        <section>
          <title>JBoss Web &amp; Tomcat</title>
          <para>
            You still need to use a lifecycle <![CDATA[<Listener/>]]> element in server.xml, but it's location has changed.
            In 1.1.x, the ModClusterListener class was refactored into the catalina container SPI implementation package, and the old location was deprecated.
          </para>
        </section>
      </section>
      <section>
        <title>JVM Route</title>
        <para>
          In mod_cluster 1.0.x, you needed to add a unique jvmRoute to the <![CDATA[<Engine/>]]> element within server.xml.
          In 1.1.x, this is now optional.
          The auto-assignment of a jvm route is described in the <link linkend="jvm-route">previous section</link>.
        </para>
      </section>
      <section>
        <title>Connector bind address</title>
        <para>
          In mod_cluster 1.0.x, you had the option of manually setting the connector bind address, to restrict the network interface on which mod_cluster would listen for proxied requests from the load balancer.
          In mod_cluster 1.1.x, this no longer necessary.
          mod_cluster will set the bind address automatically, based on the interface on which mod_cluster's internal connection was established.
        </para>
      </section>
    </section>
    <section>
      <title>mod_cluster-jboss-beans.xml</title>
      <para>
        The JBoss microcontainer configuration for mod_cluster 1.0.x is *not* compatible with the configuration for 1.1.x.
        If you had customized your mod_cluster 1.0.x configuration, please start with the default configuration contained in the 1.1.x mod_cluster.sar and reapply any changes.
      </para>
      <section>
        <title>Configuration changes</title>
        <para>
          The following configuration properties were renamed between 1.0.x and 1.1.x:
        </para>
        <informaltable frame="all">
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Deprecated property name</entry>
                <entry>Replacement property name</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>domain</entry>
                <entry>loadBalancingGroup</entry>
              </row>
              <row>
                <entry>masterPerDomain</entry>
                <entry>masterPerLoadBalancingGroup</entry>
              </row>
              <row>
                <entry>sslKeyStorePass</entry>
                <entry>sslKeyStorePassword</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
    </section>
  </section>
</chapter>
