<?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>Server and services configuration</title>
  </info>

  <para><filename>$JONAS_BASE/conf/jonas.properties</filename> is the key file
  for configuring <xi:include href="../variables.xml"
  xpointer="appserver" />.</para>

  <para>This file is used for:</para>

  <itemizedlist>
    <listitem>
      <para>setting some global properties for the <xi:include
      href="../variables.xml" xpointer="appserver" /> instance</para>
    </listitem>

    <listitem>
      <para>choosing the list of <xi:include href="../variables.xml"
      xpointer="appserver" /> services to be launched at startup</para>
    </listitem>

    <listitem>
      <para>customizing each services</para>
    </listitem>
  </itemizedlist>

  <section xml:id="global.properties">
    <info>
      <title>Global properties</title>
    </info>

    <para><screen>#  Name of the JOnAS server
#  default value is "jonas"
jonas.name    jonas

#  Name of the JOnAS domain
#  default value is "jonas"
domain.name    jonas

#  Enable the Security context propagation (for jrmp)
jonas.security.propagation    true

#  Enable the Security manager
#  default value is true (if not set)
#  Setting this to false implies a collocated registry and setting in carol.properties:
#  carol.jvm.rmi.local.registry=true
jonas.security.manager    false

#  Enable csiv2
jonas.csiv2.propagation    true

#  Enable the Transaction context propagation
jonas.transaction.propagation    true

#  Set the name of log configuration file
jonas.log.configfile    trace

#  Set the work directory used by JOnAS (relative or absolute)
#  A relative directory name will be prefixed by JONAS_BASE/
#  An absolute path will be used directly
jonas.workdirectory    work

#  Set to true if the server is a master
jonas.master    false

#  Set to true in order to execute the JOnAS Server in development mode.
#
#  WAR archive deployment case in development mode (for single or EAR packaged WARs):
#  Each modified WAR archive will be unpacked in the working directory of the JOnAS Server
#  in a different folder to avoid file locks. This is especially useful in a Windows environment.
jonas.development    true</screen></para>

    <note>
      <para>setting <property>jonas.security.manager</property> to
      <literal>false</literal> implies a colocated registry and implies to set
      in <filename>carol.properties</filename>:</para>

      <screen>carol.jvm.rmi.local.registry=true</screen>
    </note>
  </section>

  <section xml:id="adminClient.properties">
    <info>
      <title>Admin Client properties</title>
    </info>

    <para><screen>#
###################### JOnAS Admin Client configuration
#
#  If JMX security is enabled, the JOnAS Admin Client requires its parameters
#  To be passed using -username and -password arguments. These two parameters
#  pass these arguments to the JOnAS Admin Client internally.
jonas.adminClient.username      jonas
jonas.adminClient.password      jonas</screen></para>

  </section>

  <section>
    <info>
      <title>List of <xi:include href="../variables.xml"
      xpointer="appserver" /> services</title>
    </info>

    <para>Here is the list of default services activated at starting
    time:</para>

    <screen><emphasis>jonas.services</emphasis>    jtm, db, security, resource, ejb3, jaxws, web, ear, depmonitor</screen>

    <para>The possible services are:</para>

    <para><screen xml:id="config.jonas_proerties.allservices">registry, jmx, security, jtm, db, mail, wc, dbm, wm, resource, cmi, ha, versioning, ejb2, ejb3, jaxrpc, jaxws, web, ear, depmonitor, discovery, resourcemonitor, smartclient, wsdl-publisher</screen></para>

    <variablelist>
      <varlistentry>
        <term>cmi</term>

        <listitem>
          <para>this service provides support for the clustering of RMI
          objects.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>db</term>

        <listitem>
          <para>this service is used for launching a Java database
          implementation. By default, HSQLDB java database is used.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>dbm</term>

        <listitem>
          <para>this service is needed by application components that require
          access to one or several relational databases. It may be an
          alternative to the usage of a <acronym>JDBC</acronym> resource
          adapter via the resource service.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>depmonitor</term>

        <listitem>
          <para>this service is used to control the application's deployment
          process in JOnAS.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>discovery</term>

        <listitem>
          <para>this service allows dynamic administration of management
          domains.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ear</term>

        <listitem>
          <para>this service provides support for <xi:include
          href="../variables.xml" xpointer="j2ee" /> applications (<filename
          class="extension">.ear</filename> files).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ejb2</term>

        <listitem>
          <para>this service provides support for EJB 2.x components
          (EjbJars).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ejb3</term>

        <listitem>
          <para>this service provides supports for EJB 3.0 components
          (EjbJars).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ha</term>

        <listitem>
          <para>this service provides high-availability replication mechanims
          for stateful session beans (EJB 2.x only).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>jaxrpc</term>

        <listitem>
          <para>this service provides support for JAX-RPC 1.1 webservices
          (J2EE 1.4 style, based on <filename>webservices.xml</filename>
          deployment descriptors).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>jaxws</term>

        <listitem>
          <para>this service provides support for JAX-WS 2.0 webservices (Java
          EE 5.0 style based on JWS annotations).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>jmx</term>

        <listitem>
          <para>this service is needed in order to administrate the JOnAS
          servers and the JOnAS services via a JMX-based administration
          console. It is automatically launched before all the other services
          when starting <xi:include href="../variables.xml"
          xpointer="appserver" />.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>jtm</term>

        <listitem>
          <para>this service provides support of distributed transactions
          management.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>mail</term>

        <listitem>
          <para>this service is required by applications that need to send
          e-mail messages.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>registry</term>

        <listitem>
          <para>this service is used for binding remote objects and resources
          that will later be accessed via JNDI. It is automatically launched
          before all the other services when starting <xi:include
          href="../variables.xml" xpointer="appserver" />.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>resource</term>

        <listitem>
          <para>this service provides support for resource adapters conformant
          to the <xi:include href="../variables.xml" xpointer="j2ee" />
          Connector Architecture Specification.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>resourcemonitor</term>

        <listitem>
          <para>this service is related to the deployment plans. It allows to
          reload resources deployed through deployment plans by checking
          periodically repositories where are located original
          resources.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>smartclient</term>

        <listitem>
          <para>this service lets remote clients download classes and other
          resources necessary for connecting to JOnAS services (JNDI context
          factories, EJB3 interceptors, ...) directly from the JOnAS server
          they're dealing with.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>security</term>

        <listitem>
          <para>this service is needed for enforcing security at
          runtime.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>versioning</term>

        <listitem>
          <para>this service has been designed for dynamic redeployment of
          applications,without any application downtime and without users'
          sessions being lost.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>wc</term>

        <listitem>
          <para>this service cleans up periodically the work directory of the
          JOnAS server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>web</term>

        <listitem>
          <para>this service provides support for web components (as Servlets
          and JSP). JOnAS provides two implementations of this service, one
          based on Tomcat and another on Jetty.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>wm</term>

        <listitem>
          <para>this service provides a JCA WorkManager implementation
          (offering a manageable Thread Pool for resource adapters
          components).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>wsdl-publisher</term>

        <listitem>
          <para>this service provides an alternate WSDL publishing mechanism
          (compared to the usual URL based publishing).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <info>
      <title>Service startup policies</title>
    </info>

    <para><xi:include href="../variables.xml" xpointer="appserver" /> will try
    to start declared services in the order in which they appear in the list
    except for the <emphasis>depmonitor</emphasis> service which is always
    started at the end. If some services require other ones (even non declared
    in the list), service requirements will be started first.</para>

    <para>To simplify the declaration of <xi:include href="../variables.xml"
    xpointer="appserver" /> services and to ensure that all service
    requirements are fulfilled, some services declare explicitly their
    dependencies in order to start them automatically.</para>

    <para>The picture below describes mandatory dependencies beetwen
    <xi:include href="../variables.xml" xpointer="appserver" /> services. A
    link between two services means that a service requires another one. Note
    on the right side services without dependency links.</para>

    <para><imagedata
    fileref="../../../resources/images/service-dependencies.png" /></para>

    <caution>
      <para>Optional service dependencies are not described in this picture.
      They have to be declared in the list of JOnAS services when
      required.</para>
    </caution>

    <itemizedlist>
      <listitem>
        <para><emphasis role="">registry</emphasis> and <emphasis
        role="">jmx</emphasis> services can be omitted from the list because
        they are automatically launched.</para>
      </listitem>

      <listitem>
        <para>As an example, starting the <emphasis>web</emphasis> service
        involves the startup of the <emphasis>security</emphasis> service.
        Declaring the <emphasis>web</emphasis> service in the list of
        <xi:include href="../variables.xml" xpointer="appserver" /> services
        without declaring the <emphasis>security</emphasis> service may be a
        solution.</para>
      </listitem>

      <listitem>
        <para>As an example, starting the <emphasis>resource</emphasis>
        service involves the startup of the <emphasis>wm</emphasis> and the
        <emphasis>jtm</emphasis> services. Declaring the
        <emphasis>resource</emphasis> service in the list of <xi:include
        href="../variables.xml" xpointer="appserver" /> services without
        declaring the <emphasis>wm</emphasis> and the <emphasis>jtm</emphasis>
        service may be a solution.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <info>
      <title>Customizing services</title>
    </info>

    <para>Configuration parameters for services follow a strict naming
    convention: a service <emphasis role="bold">XX</emphasis> will be
    configured via a set of properties:</para>

    <informalexample>
      <para><property>jonas.service.XX.foo</property> something</para>

      <para><property>jonas.service.XX.bar</property> else</para>

      <para>each service <emphasis role="bold"> XX</emphasis> must contain the
      property <property>jonas.service.XX.class</property> indicating the name
      of the java class that implements the service:</para>

      <para>jonas.service.XX.class aa.bb.XXImpl</para>

      <para>This allow experimented user to replace built-in service by an
      alternative implementation.</para>
    </informalexample>

    <informalexample>
      <para>For example here is the part of
      <filename>jonas.properties</filename> file related to the customization
      of the <emphasis role="bold">jtm</emphasis> service:</para>

      <para><screen>
###################### JOnAS JTM Transaction service configuration
#  Set the name of the implementation class of the jtm service
jonas.service.jtm.class    org.ow2.jonas.tm.jotm.JOTMTransactionService

#  Set the Transaction Manager launching mode.
#  If set to 'true', TM is remote: TM must be already launched in an other JVM.
#  If set to 'false', TM is local: TM is going to run into the same JVM
#  than the jonas Server.
jonas.service.jtm.remote    false

#  Set the default transaction timeout, in seconds.
jonas.service.jtm.timeout    60
            </screen></para>
    </informalexample>

    <para>see <xref linkend="config.services" /> for a complete description of
    the services configuration.</para>
  </section>

  <section>
    <info>
      <title>Development vs Production mode</title>
    </info>

    <para><xi:include href="../variables.xml" xpointer="appserver" /> may be
    configured to be in development mode and in production mode. This can be
    defined by setting the <emphasis role="bold">jonas.development</emphasis>
    global property. Activating one of this mode changes some server
    behaviours as described in the following section.</para>

    <section xml:id="development.mode">
      <info>
        <title>Development mode</title>
      </info>

      <para>This is the default mode. <itemizedlist>
          <listitem>
            <para>Starts automatically the workcleaner
            (<emphasis>wc</emphasis>) service.</para>
          </listitem>

          <listitem>
            <para>Allows to start automatically services which are required to
            initiate the deployment of the Java EE archives. Ex: deploying the
            sample.war will trigger the startup of the
            <emphasis>web</emphasis> service.</para>

            <para>List of services that may be started dynamically depending
            on the deployed Java EE archives:</para>

            <screen>web (WARs), ejb2 (EJB2s), ejb3 (EJB3s), resource (RARs), ear (EARs)</screen>

            <note>
              <para>Known limitations: if an application needs some additional
              services to work like for example Web Services support
              (<emphasis>jarxrpc</emphasis> or <emphasis>jaxws</emphasis>
              services), the administrator have to add those kind of services
              manually in the static description of <xi:include
              href="../variables.xml" xpointer="appserver" /> services.</para>
            </note>
          </listitem>

          <listitem>
            <para>In case of the development property of the
            <emphasis>depmonitor</emphasis> service is set to inherit, the
            period scan of directories managed by the
            <emphasis>depmonitor</emphasis> (by default the <filename>deploy/
            </filename>directory) service will be enabled.</para>
          </listitem>

          <listitem>
            <para>WAR archive deployment case (for single or EAR packaged
            WARs). Each WAR archive is unpacked in the working directory of
            the <xi:include href="../variables.xml" xpointer="appserver" />
            server in a different folder to avoid file locks. This is
            especially useful in a Windows environment.</para>
          </listitem>

          <listitem>
            <para>Necessary to enable the onDemand feature of the
            <emphasis>web</emphasis> service.</para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <info>
        <title>Production mode</title>
      </info>

      <para>This mode is recommended in industrial production context.</para>

      <para><itemizedlist>
          <listitem>
            <para>In case of the development property of the depmonitor
            service is set to inherit, the period scan of directories managed
            by the depmonitor (by default the <filename>deploy/
            </filename>directory) service will be disabled.</para>
          </listitem>

          <listitem>
            <para>WAR archive deployment case (for single or EAR packaged
            WARs). Each WAR archive is unpacked in the working directory of
            the <xi:include href="../variables.xml" xpointer="appserver" />
            server in the same folder.</para>
          </listitem>

          <listitem>
            <para>Force the disabling of the onDemand feature of the
            <emphasis>web</emphasis> service.</para>
          </listitem>
        </itemizedlist></para>
    </section>
  </section>
</section>
