<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="Win32Service" 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>Execute JOnAS as a Windows Service</title>
  </info>

  <para>This document describes the procedures necessary to run JOnAS as a
  system service on Microsoft Windows platforms.</para>

  <section>
    <info>
      <title>Instructions</title>
    </info>

    <para>The procedure uses the Tanuki Java Service Wrapper open source
    project which must be downloaded and installed separately.</para>

    <section>
      <info>
        <title>Download and Install Apache ANT</title>
      </info>

      <orderedlist>
        <listitem>
          <para>Download <link xlink:href="http://ant.apache.org/"> Apache ANT
          </link> version 1.7.1 or later.</para>
        </listitem>

        <listitem>
          <para>Unzip the package to a directory in the local
          filesystem.</para>
        </listitem>

        <listitem>
          <para>Set <code> ANT_HOME </code> environment variable to the root
          directory for Apache ANT.</para>

          <para>For example, if the package for ANT version 1.7.1 is unzipped
          into <code> C:\Program Files </code>, then set <code> ANT_HOME =
          C:\Program Files\apache-ant-1.7.1</code></para>
        </listitem>

        <listitem>
          <para>Add <code> %ANT_HOME%\bin </code> to your <code> PATH </code>
          environment variable.</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <info>
        <title>Download and Install Java Service Wrapper</title>
      </info>

      <orderedlist>
        <listitem>
          <para>Download <link
          xlink:href="http://wrapper.tanukisoftware.org/doc/english/index.html">
          Tanuki Java Service Wrapper </link> version 3.3.9 or later (the
          "Community Edition" is sufficient for executing JOnAS as a Windows
          Service).</para>
        </listitem>

        <listitem>
          <para>Unzip the package to a directory in the local
          filesystem.</para>
        </listitem>

        <listitem>
          <para>Set <code> WRAPPER_HOME </code> environment variable to the
          root directory for Java Service Wrapper.</para>

          <para>For example, if the package for Wrapper version 3.3.9 is
          unzipped into <code> C:\Program Files </code>, then set <code>
          WRAPPER_HOME = C:\Program
          Files\wrapper-windows-x86-32-3.3.9</code></para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <info>
        <title>Create the JOnAS Windows service</title>
      </info>

      <para>Before JOnAS can be run as a Windows service, it is necessary to
      create a Java Service Wrapper configuration file. Prior to executing the
      steps in this section, it is necessary to create a JONAS_BASE directory
      as described in the JOnAS <link
      xlink:href="configuration_guide.html">Configuration Guide </link>
      .</para>

      <orderedlist>
        <listitem>
          <para>Verify that JAVA_HOME is set as a system environment
          variable.</para>
        </listitem>

        <listitem>
          <para>Verify that JONAS_ROOT, JONAS_BASE and WRAPPER_HOME
          environment variables are set.</para>
        </listitem>

        <listitem>
          <para>Set %JONAS_ROOT%\templates\windows_service as the current
          directory.</para>
        </listitem>

        <listitem>
          <para>Set environment variables required for JOnAS execution (see
          list below).</para>
        </listitem>

        <listitem>
          <para>Execute <code> ant
          [-Djonas.name=&lt;server_name&gt;]</code></para>

          <note>
            <para>The <code> -Djonas.name=&lt;server_name&gt; </code>
            parameter is optional. If not specified, the default server name
            is 'jonas'.</para>
          </note>
        </listitem>
      </orderedlist>

      <para>Once this is done, the <code>wrapper.conf</code> file inside your
      JONAS_BASE will be filled with all launch options required by
      JOnAS.</para>

      <note>
        <para>Do not change the <code>wrapper.conf</code> file as it will be
        regenared everytime you run the Apache ANT task. To put your own,
        personalized options, use the <code>wrapper_extra.conf</code> file in
        JONAS_BASE instead.</para>
      </note>
    </section>

    <section>
      <info>
        <title>Personalise JOnAS options</title>
      </info>

      <para>To add options to your JOnAS server running as a Windows service,
      modify the <code>wrapper_extra.conf</code> file in JONAS_BASE.</para>

      <note>
        <para>Once this file is changed, you'll need to restart the JOnAS
        service to see the effects. You do not need to reinstall the service,
        thought.</para>
      </note>
    </section>

    <section>
      <info>
        <title>Test the JOnAS Windows service</title>
      </info>

      <para>After the %JONAS_BASE% directory has been updated for use with
      Java Service Wrapper, the Windows service configuration can be tested by
      executing the command:<literallayout>
          jonas ntservice console
        </literallayout></para>

      <para>Once you see that JOnAS is running, simply press CTRL + C to stop
      it.</para>
    </section>

    <section>
      <info>
        <title>Install the JOnAS Windows service</title>
      </info>

      <para>Once you're assured the Windows service is operational, install in
      onto Windows using the following command:<literallayout>
          jonas ntservice install
        </literallayout></para>
    </section>

    <section>
      <info>
        <title>Start the JOnAS Windows service</title>
      </info>

      <para>To start the JOnAS Windows service, you can use the Windows
      Services control panel item or launch the following
      command:<literallayout>
          jonas ntservice start
        </literallayout></para>

      <note>
        <para>By default, JOnAS will be started automatically each time
        Windows is started. After installing the service, it can be started
        manually to avoid the need to reboot Windows.</para>
      </note>
    </section>

    <section>
      <info>
        <title>Stop the JOnAS Windows service</title>
      </info>

      <para>To stop the JOnAS Windows service, you can use the Windows
      Services control panel item or launch the following
      command:<literallayout>
          jonas ntservice stop
        </literallayout></para>
    </section>

    <section>
      <info>
        <title>Restart the JOnAS Windows service</title>
      </info>

      <para>To restart the JOnAS Windows service, you can use the Windows
      Services control panel item or launch the following
      command:<literallayout>
          jonas ntservice restart
        </literallayout></para>
    </section>

    <section>
      <info>
        <title>Uninstall the JOnAS Windows service</title>
      </info>

      <para>To uninstall the JOnAS Windows service, use the following
      command:<literallayout>
          jonas ntservice uninstall
        </literallayout></para>

      <note>
        <para>Do not re-create the JOnAS Windows service before uninstalling
        it; else JOnAS might lose the reference to the Windows service entry
        and therefore never manage to uninstall the service.</para>
      </note>
    </section>
  </section>
</chapter>