<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="commands.newjc" 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">
  <title>newjc command</title>

  <para>Command that builds all the configurations (ie JONAS_BASE) of the
  <xi:include href="../variables.xml" xpointer="appserver" /> instances for
  the cluster (including also a <xi:include href="../variables.xml"
  xpointer="appserver" /> master to manage the domain, a <xi:include
  href="../variables.xml" xpointer="appserver" /> DB with an embedded HSQLDB
  server, and a cluster daemon). It also creates the configuration files
  needed for mod_jk.</para>

  <section>
    <title>Options</title>

    <cmdsynopsis>
      <command>newjc</command>

      <arg>-auto</arg>
    </cmdsynopsis>

    <variablelist>
      <varlistentry>
        <term>-auto</term>

        <listitem>
          <para>Use the default configuration (silent mode)</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>Description</title>

    <para>The newjc utility builds all the configurations (ie JONAS_BASE) of
    the <xi:include href="../variables.xml" xpointer="appserver" /> instances
    for the cluster (including also a <xi:include href="../variables.xml"
    xpointer="appserver" /> master to manage the domain, a <xi:include
    href="../variables.xml" xpointer="appserver" /> db with an embedded HSQLDB
    server, and a cluster daemon). It also creates the configuration files
    needed for mod_jk.</para>

    <para>At command start, the user must choose:</para>

    <orderedlist>
      <listitem>
        <para>the cluster directory where the <xi:include
        href="../variables.xml" xpointer="appserver" /> configuration
        directories (ie JONAS_BASE) will be created,</para>
      </listitem>

      <listitem>
        <para>the prefix for the new <xi:include href="../variables.xml"
        xpointer="appserver" /> configuration directories
        (<emphasis>ex</emphasis>: prefix jb generates jb1, jb2, ...),</para>
      </listitem>

      <listitem>
        <para>the protocol among jrmp, iiop, irmi,</para>
      </listitem>

      <listitem>
        <para>the database to configure for the <code>db</code> node,</para>
      </listitem>

      <listitem>
        <para>the cluster architecture among bothWebEjb, diffWebEjb. The first
        means that all the nodes are configured with both web and ejb services
        whereas the second one will separate the two tiers,</para>
      </listitem>

      <listitem>
        <para>the number of web instances,</para>
      </listitem>

      <listitem>
        <para>the number of ejb instances.</para>
      </listitem>
    </orderedlist>

    <para>The tool generates the configuration automatically but you can
    customize some of the characteristics of the cluster by modifying the
    following files, in <filename>JONAS_ROOT/conf/newjc</filename>, before
    executing the command:</para>

    <para><itemizedlist>
        <listitem>
          <para><filename>build-jc.properties</filename>: global configuration
          for the cluster,</para>
        </listitem>

        <listitem>
          <para><filename>build-master.properties</filename>: specific
          configuration for the master node,</para>
        </listitem>

        <listitem>
          <para><filename>build-db.properties</filename>: specific
          configuration for the db node.</para>
        </listitem>
      </itemizedlist></para>

    <para>If the <emphasis role="bold">-auto</emphasis> option is used, the
    <envar>$JONAS_BASE</envar> variable must be set before launching the tool;
    it specifies the prefix of the paths to the new directories that will be
    built and that will contain the JONAS_BASE of the cluster members.</para>

    <para>You can add some specific user configuration in the
    <filename>$HOME/jc.config/lib</filename>. If the directory doesn't exits,
    it will be created during the execution of the command.</para>

    <para>A user configuration can be set in the
    <filename>$HOME/jc.config/conf/jonas-newjc.properties</filename> file. If
    this file is present, the parameters it contains will override the default
    parameters defined in
    <filename>JONAS_ROOT/conf/newjc/build-jc.properties</filename>.</para>
  </section>

  <section>
    <title>Review newjc output</title>

    <para><emphasis>newjc</emphasis> creates
    <filename>tomcat_jk.conf</filename> and
    <filename>workers.properties</filename> files under
    <filename>&lt;cluster-directory&gt;/conf/jk</filename>. The #Web section
    of <filename>build-jc.properties</filename> defines configuration
    parameters set by <emphasis>newjc</emphasis> in these files. The file
    <filename>tomcat_jk.conf</filename> contains apache directives supported
    in <filename>httpd.conf</filename> or <filename>apache2.conf</filename>.
    They are isolated in a separate file for modularity, then they must be
    included manually in <filename>httpd.conf</filename> or
    <filename>apache2.conf</filename>. Refer to workers <link
    xlink:href="http://tomcat.apache.org/connectors-doc/generic_howto/workers.html">HowTo</link>
    documentation on the Tomcat site.</para>

    <para><emphasis>newjc</emphasis> generates by default four <xi:include
    href="../variables.xml" xpointer="appserver" /> instances (four
    <xi:include href="../variables.xml" xpointer="appserver" /> bases) in
    directories jb1, jb2, jb3 and jb4 under the cluster directory. Each
    <xi:include href="../variables.xml" xpointer="appserver" /> instance has
    its own configuration files into the <filename>conf</filename> directory
    (as any other <xi:include href="../variables.xml" xpointer="appserver" />
    base). It also generates configurations for cluster daemon
    (<filename>cd</filename> directory), for master node
    (<filename>master</filename> directory), and for db node
    (<filename>db</filename> directory).</para>

    <para>By default, jb1 and jb2 are <xi:include href="../variables.xml"
    xpointer="appserver" /> web container instances and jb3 and jb4 are
    <xi:include href="../variables.xml" xpointer="appserver" /> EJB container
    instances.</para>

    <para><emphasis>newjc</emphasis> generates a script called <emphasis
    role="bold">jcl4sc</emphasis> (<emphasis
    role="bold">jcl4sc.bat</emphasis>) for controlling the cluster examples
    provided with JOnAS named, sampleCluster2 and sampleCluster3. The command
    takes in argument the parameter status, start, stop, halt or kill.</para>

    <para>The pertinent files for the configuration of the cluster are
    described below:</para>

    <variablelist>
      <varlistentry>
        <term>carol.properties - jgroups-cmi.xml</term>

        <listitem>
          <para>The #Carol section of <filename>build-jc.properties</filename>
          defines configuration parameters set by <emphasis>newjc</emphasis>
          in the <filename>carol.properties </filename>and
          <filename>jgroups-cmi.xml</filename> files . This allows JNDI
          replication to support load balancing at the EJB level using the CMI
          protocol.</para>

          <note>
            <para>The multicast address and port must be identically
            configured for all <xi:include href="../variables.xml"
            xpointer="appserver" /> / Tomcat instances.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>jonas.properties</term>

        <listitem>
          <para>The #Services section of
          <filename>build-jc.properties</filename> defines configuration
          parameters set by <emphasis>newjc</emphasis> in the
          <filename>jonas.properties</filename> file.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>tomcat6-server.xml</term>

        <listitem>
          <para>The #Web section of <filename>build-jc.properties</filename>
          defines some configuration parameters set by
          <emphasis>newjc</emphasis> in the <filename>tomcat6-server.xml</filename>
          file . In particular, a connector XML element for AJP1.3 protocol is
          defined, as well as a jvmRoute to support load balancing at the web
          level, via this connector.</para>

          <para>A Cluster XML element was also added. It defines parameters
          for achieving Session replication at the web level with <xi:include
          href="../variables.xml" xpointer="appserver" />.</para>

          <para>Refer to the <link
          xlink:href="http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html">AJP
          Connector</link> and the <link
          xlink:href="http://tomcat.apache.org/tomcat-6.0-doc/config/engine.html">Engine
          Container</link> documentation.</para>

          <note>
            <para>The jvmRoute name generated by newjc is the same as the name
            of the associated worker defined in worker.properties. This will
            ensure the Session affinity.</para>
          </note>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>Tell Apache about mod_jk</title>

    <para>To make apache aware of this new file, edit
    &lt;prefix&gt;/conf/httpd.conf.</para>

    <para>Copy and paste the following line after the Dynamic Shared Object
    (DSO) Support section.</para>

    <screen>Include conf/jk/tomcat_jk.conf </screen>

    <para>Move the jk directory created by newjc under the APACHE
    structure:</para>

    <screen>bash&gt; mv &lt;cluster-directory&gt;/conf/jk $APACHE_HOME/conf</screen>

    <para>Restart apache so that apache can load the jk_module:</para>

    <screen>bash&gt; apachectl stop &amp;&amp; apachectl start</screen>

    <note>
      <para>Some UNIX distributions may locate the module in the folder
      libexec instead of the folder modules.</para>
    </note>
  </section>
</section>