<?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" xml:id="commands.newjb" >
  <title>newjb command</title>

  <para>Build a new <envar>JONAS_BASE</envar> directory.</para>

  <section>
    <title>Synopsis</title>

    <cmdsynopsis>
      <command>newjb</command>
    </cmdsynopsis>
  </section>

  <section>
    <title>Description</title>

    <para>The newjb utility builds a new <envar>JONAS_BASE</envar> directory
    that allows the conformance tests to be launched. At the start, the user
    must choose:</para>

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

      <listitem>
        <para>the database</para>
      </listitem>

      <listitem>
        <para>the web container among tomcat, jetty</para>
      </listitem>
    </itemizedlist>

    <para>The tool generates the configuration automatically.</para>

    <para>The <envar>$JONAS_BASE</envar> variable must be set before launching
    the tool; it specifies the path to the new directory that will be
    built.</para>

    <para>The <filename>$HOME/jb.config/lib</filename> directory must be
    created before launching the tool. It can contain some specific user
    configuration (see below).</para>

    <para>The tool relies on <xi:include href="../variables.xml"
    xpointer="appserver" /> 's ant tasks
    (<filename>$JONAS_ROOT/templates/newjb/build-jb.xml</filename>) and thus builds a
    configuration compatible with the <xi:include href="../variables.xml"
    xpointer="appserver" /> version. First, a <envar>JONAS_BASE</envar> with
    default values is built, and then the configuration files are modified
    with the values defined in the centralized configuration file of newjb
    (see below).</para>

    <para>A default configuration file is provided in
    <filename>$JONAS_ROOT/templates/newjb/build-jb.properties</filename>. It contains the
    variable parameters used by the tool, such as port number and database
    properties.</para>

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

    <para>By default, only the HSQL database can be configured with this tool.
    For other databases, the specific drivers must be stored in the
    <filename>$HOME/jb.config/lib</filename> directory before the run and the
    properties must be set in the
    <filename>$HOME/jb.config/conf/jonas-newjb.properties</filename>
    file.</para>

    <para>The default script (<filename>$JONAS_ROOT/build-jb.xml</filename>)
    and its configuration
    (<filename>$JONAS_ROOT/templates/newjb/build-jb.properties</filename>) can be used as an
    example for creating a configuration tool corresponding to user's specific
    requirements.</para>
  </section>
</section>
