<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="Services-on-demand-usage" 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>Requiring <xi:include href="variables.xml" xpointer="appserver" />
    services in Java EE applications</title>
  </info>

  <para>In some case, Java EE applications you want to execute need specifics
  <xi:include href="variables.xml" xpointer="appserver" /> services to run
  correctly. If the required services are already started, that means you have
  defined in the jonas.services property of the <xi:include
  href="variables.xml" xpointer="appserver" /> configuration file the list of
  the services you want to start, there is no special things to do. But it may
  be not the case for many reasons. One of them is that you didn't need thoses
  services before deploying your applications.</para>

  <example>
    <title><xi:include href="variables.xml" xpointer="appserver" /> service
    dependency</title>

    <para>An application that sends emails needs the <xi:include
    href="variables.xml" xpointer="appserver" /> mail service to retrieve the
    Session and MimePartDataSource objects.</para>
  </example>

  <section>
    <title>Declaring JOnAS service dependencies</title>

    <para>To ensure that a set of <xi:include href="variables.xml"
    xpointer="appserver" /> services will be started before deploying a Java
    EE application, you have to set the
    <property>Require-JOnAS-Services</property> attribute in the root
    manifest file of the archive. The value of this property is a
    comma-separed list of <xi:include href="variables.xml"
    xpointer="appserver" /> service names. Service names must match with the
    ones defined in the <filename>jonas.properties</filename> configuration
    file. In case of an EAR archive, there is no need to modify the manifest
    files of the embedded JARs, WARs, RARs or CARs archives.</para>

    <example>
      <title>MANIFEST.MF file content</title>

      <programlisting>Manifest-Version: 1.0
...
<emphasis role="bold">Require-JOnAS-Services</emphasis>: mail,web</programlisting>
    </example>

    <section>
      <title>Startup of required services</title>

      <para>During the deployment phase of an Java EE archive, the manifest
      file is analysed to check if the
      <property>Require-JOnAS-Services</property> property exists. For each
      declared service, the server verifies wheither the service is already
      started. If not, two operations should be performed:</para>

      <itemizedlist>
        <listitem>
          <para>Install/start bundles for the required service if
          needed</para>
        </listitem>

        <listitem>
          <para>Create configuration for the required service</para>
        </listitem>
      </itemizedlist>

      <para>After that, the service should be started and the application can
      also be started.</para>

      <note>
        <para>If the application is undeployed, there is at the moment no ways
        to specify if these service dependencies should also be stopped or
        uninstalled.</para>
      </note>
    </section>

    <section>
      <title>Addition of the manifest attribute during maven build</title>

      <para>The addition of the manifest attribute during a maven build can be
      automated by configurating the maven plugin like below.</para>

      <programlisting>  ...
  &lt;configuration&gt;
    &lt;archive&gt;
      &lt;manifestEntries&gt;
        &lt;Require-JOnAS-Services&gt;service1,service12,..,servicen&lt;/Require-JOnAS-Services&gt;
      &lt;/manifestEntries&gt;
    &lt;/archive&gt;
  &lt;/configuration&gt;
  ...</programlisting>

      <para>More info may be found <link
      xlink:href="http://maven.apache.org/guides/mini/guide-manifest.html">here</link>.</para>
    </section>
  </section>
</chapter>
