<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="Services" 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>Creating a New JOnAS Service</title>
  </info>

  <section xml:id="Services-Target">
    <info>
      <title>Target audience and rationale</title>
    </info>

    <para>This chapter is intended for advanced JOnAS users who require that
    some "external" services run along with the JOnAS server. A service is
    something that may be initialized, started, and stopped. JOnAS itself
    already defines a set of services, some of which are cornerstones of the
    JONAS Server. The JOnAS pre-defined services are listed in <link
    xlink:href="configuration_guide.html#config.services"> Configuring JOnAS
    services </link> .</para>

    <para>Java EE application developers may need to access other services,
    for example another Web container or a Versant container, for their
    components. Thus, it is important that such services be able to run along
    with the application server. To achieve this, it is possible to define
    them as JOnAS services.</para>

    <para>This chapter describes how to define a new JOnAS service and how to
    specify which service should be started with the JOnAS server.</para>
  </section>

  <section xml:id="Services-Intro">
    <info>
      <title>Introducing a new service</title>
    </info>

    <para>The customary way to define a new JOnAS service is to encapsulate it
    in a class whose interface is known by JOnAS. More precisely, such a class
    provides a way to start and stop the service. Then, the
    <filename>jonas.properties</filename> file must be modified to make JOnAS
    aware of this service.</para>

    <section>
      <info>
        <title>Defining the service interface and implementation</title>
      </info>

      <para>A JOnAS service is represented by a class that implements its
      service interface and extends the class
      <classname>org.ow2.jonas.lib.service.AbsServiceImpl</classname>, and
      thus must implement at least the following methods:</para>

      <itemizedlist>
        <listitem>
          <para><function>public void doStart() throws
          ServiceException;</function></para>
        </listitem>

        <listitem>
          <para><function>public void doStop() throws
          ServiceException;</function></para>
        </listitem>
      </itemizedlist>

      <para>These methods will be called by JOnAS for starting and stopping
      the service.</para>

      <para>The service interface should look like the following:<screen>package com.company.jonas.myservice;

/**
 * Defines the "business" interface of the service (no life-cycle methods).
 */
public interface IMyService {
    void doSomething();
}
</screen></para>

      <para>The service class should look like the following:</para>

      <screen language="java">package com.company.jonas.myservice.internal;

import com.company.jonas.myservice.IMyService;

import org.ow2.jonas.lib.service.AbsServiceImpl;
import org.ow2.jonas.service.ServiceException;

.....

public class DefaultMyService extends AbsServiceImpl implements IMyService {

    /** A configurable property. */
    private String property;

    @Override
    protected void doStart() throws ServiceException {
        // Do something on start-up
        // All the configuration and service dependencies has been injected at this time
    }

    @Override
    protected void doStop() throws ServiceException {
        // Do something on shutdown
        // Service dependencies are still available
    }

    public void doSomething() {
        // Business code ...
    }

    public void setProperty(String property) {
        this.property = property;
    }
}
</screen>
    </section>

    <section>
      <info>
        <title>Building the OSGi bundle</title>
      </info>

      <para>A JOnAS service must be packaged in an OSGi bundle in order to be
      deployed on the JOnAS OSGi platform. It implies to create a standard
      packaging structure. An OSGi bundle is like a classic JAR file plus a
      specific MANIFEST file. To ease the service creation, configuration and
      management of dynamic dependencies to other JOnAS services, it is
      recommanded to use <link
      xlink:href="http://felix.apache.org/site/apache-felix-ipojo.html">iPOJO</link>
      to build your services. This guide will present the iPOJO
      solution.</para>

      <para>The JAR structure of the bundle must contain the following
      parts:<informaltable>
          <tgroup cols="2">
            <tbody>
              <row>
                <entry>com/company/jonas/myservice</entry>

                <entry>contains the service interface(s)</entry>
              </row>

              <row>
                <entry>com/company/jonas/myservice/internal</entry>

                <entry>contains the service implementation classe(s)</entry>
              </row>

              <row>
                <entry>META-INF/MANIFEST.MF</entry>

                <entry>OSGi manifest file</entry>
              </row>

              <row>
                <entry>metadata.xml</entry>

                <entry>iPOJO metadata file</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable></para>

      <para>The OSGi MANIFEST should contain the following attributes:</para>

      <screen>Import-Package: org.ow2.jonas.lib.service, org.ow2.jonas.service, ...
Export-Package: com.company.jonas.myservice
Private-Package: com.company.jonas.myservice.internal
Bundle-Version: 5.1.0
Bundle-ManifestVersion: 2
Bundle-Name: MyService
Bundle-SymbolicName: com.company.jonas.myservice</screen>

      <para>If the project is built with <link
      xlink:href="http://maven.apache.org/">Maven</link>, it is possible to
      generate this file during the project compilation thanks to the <link
      xlink:href="http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html">maven-bundle-plugin</link>.
      This plugin is based on the <link
      xlink:href="http://www.aqute.biz/Code/Bnd">BND</link> tool which can
      also be used separately.</para>

      <section>
        <title>Building with maven</title>

        <para>Even if it's not mandatory to use maven to build OSGi bundles,
        the JOnAS team use it extensively because of the large number of
        integrated <trademark>OSGi</trademark> build tools.</para>

        <section>
          <title>Maven project structure</title>

          <para>The maven project that will contains the new service's code is
          structured just like any well known maven project:</para>

          <para><screen>&lt;myservice&gt;/
  src/
    main/
      java/
        a/b/&lt;myservice&gt;/
          ...
      resources/
        META-INF/
          &lt;myservice&gt;.bnd (optional)
        metadata.xml
    test/
      ...
  pom.xml
</screen><itemizedlist>
              <listitem>
                <para><filename class="directory">src/main/java/</filename>
                contains all the Java source code that have been written for
                the new service (interface + implementation + any other new
                classes)</para>
              </listitem>

              <listitem>
                <para><filename
                class="directory">src/main/resources/</filename> contains the
                iPOJO component description file named metadata.xml, plus an
                optional Bnd descriptor that will be used to describe the
                bundle's content (for advanced usages)</para>
              </listitem>

              <listitem>
                <para><filename class="directory">src/test/</filename>
                contains all the unit tests that may have been written to unit
                test the service implementation (optional altough
                recommanded)</para>
              </listitem>

              <listitem>
                <para><filename>pom.xml</filename> is the maven project's
                module descriptor</para>
              </listitem>
            </itemizedlist></para>
        </section>

        <section>
          <title>Maven project descriptor (pom.xml)</title>

          <para><programlisting language="java" linenumbering="numbered">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;

  &lt;groupId&gt;com.company.jonas&lt;/groupId&gt;
  &lt;artifactId&gt;myservice&lt;/artifactId&gt;
  &lt;version&gt;1.0.0&lt;/version&gt;
  &lt;packaging&gt;bundle&lt;/packaging&gt;

  &lt;name&gt;JOnAS Service&lt;/name&gt;

  &lt;properties&gt;
    &lt;jonas.version&gt;5.1.2&lt;/jonas.version&gt;
    &lt;ipojo.version&gt;1.4.0&lt;/ipojo.version&gt;
  &lt;/properties&gt;

  &lt;dependencies&gt;
    &lt;!-- Imports the AbsService and required interfaces in our module --&gt;
    &lt;dependency&gt;
      &lt;groupId&gt;org.ow2.jonas&lt;/groupId&gt;
      &lt;artifactId&gt;jonas-commons&lt;/artifactId&gt;
      &lt;version&gt;${jonas.version}&lt;/version&gt;
      &lt;scope&gt;provided&lt;/scope&gt;
    &lt;/dependency&gt;
  &lt;/dependencies&gt;

  &lt;build&gt;
    &lt;plugins&gt;
      &lt;!-- Creates the bundle --&gt;
      &lt;plugin&gt;
        &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
        &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
        &lt;extensions&gt;true&lt;/extensions&gt;
        &lt;configuration&gt;
          &lt;instructions&gt;
            &lt;_include&gt;-target/classes/META-INF/${project.artifactId}.bnd&lt;/_include&gt;
          &lt;/instructions&gt;
        &lt;/configuration&gt;
      &lt;/plugin&gt;

      &lt;!-- Manipulate the bundle (iPOJO) --&gt;
      &lt;plugin&gt;
        &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
        &lt;artifactId&gt;maven-ipojo-plugin&lt;/artifactId&gt;
        &lt;version&gt;${ipojo.version}&lt;/version&gt;
        &lt;executions&gt;
          &lt;execution&gt;
            &lt;goals&gt;
              &lt;goal&gt;ipojo-bundle&lt;/goal&gt;
            &lt;/goals&gt;
          &lt;/execution&gt;
        &lt;/executions&gt;
      &lt;/plugin&gt;
    &lt;/plugins&gt;
  &lt;/build&gt;

&lt;/project&gt;
</programlisting>Here we go into more details about the different sections of
          this file.</para>

          <para><screen>  &lt;groupId&gt;com.company.jonas&lt;/groupId&gt;
  &lt;artifactId&gt;myservice&lt;/artifactId&gt;
  &lt;version&gt;1.0.0&lt;/version&gt;
  &lt;packaging&gt;<emphasis>bundle</emphasis>&lt;/packaging&gt;
</screen><itemizedlist>
              <listitem>
                <para><literal>groupId</literal>,
                <literal>artifactId</literal> and <literal>version</literal>
                elements are identifying uniquely the bundle in the maven
                repository</para>
              </listitem>

              <listitem>
                <para><literal>packaging</literal> defines the type of the
                artifact produces by this module. In this case, an
                <trademark>OSGi</trademark> bundle.</para>
              </listitem>
            </itemizedlist><screen>  &lt;properties&gt;
    &lt;jonas.version&gt;5.1.2&lt;/jonas.version&gt;
    &lt;ipojo.version&gt;1.4.0&lt;/ipojo.version&gt;
  &lt;/properties&gt;
</screen>The <literal>properties</literal> section defines re-usables
          key/value pairs. Here, it is used to store the JOnAS version that
          will be used to compile the module against. It also defines the
          ipojo version to be used.</para>

          <important>
            <para>Notice that there is a relationship between JOnAS and iPOJO
            version:</para>

            <itemizedlist>
              <listitem>
                <para>JOnAS 5.1.x uses iPOJO 1.4.0</para>
              </listitem>

              <listitem>
                <para>JOnAS 5.2.x uses iPOJO 1.6.x</para>
              </listitem>
            </itemizedlist>
          </important>

          <screen>  &lt;dependencies&gt;
    &lt;!-- Imports the AbsService and required interfaces in our module --&gt;
    &lt;dependency&gt;
      &lt;groupId&gt;<emphasis>org.ow2.jonas</emphasis>&lt;/groupId&gt;
      &lt;artifactId&gt;<emphasis>jonas-commons</emphasis>&lt;/artifactId&gt;
      &lt;version&gt;<emphasis>${jonas.version}</emphasis>&lt;/version&gt;
      &lt;scope&gt;<emphasis>provided</emphasis>&lt;/scope&gt;
    &lt;/dependency&gt;
  &lt;/dependencies&gt;
</screen>

          <para>The <literal>dependencies</literal> section of the POM
          declares library dependencies of the module. In this case, the new
          service requires <literal>jonas-commons</literal> because it extends
          the <classname>AbsServiceImpl</classname> class (that is in the
          <literal>jonas-commons</literal> module). The
          <literal>scope</literal> element is used to limit the transitive
          maven dependency resolution mechanism.</para>

          <screen>      &lt;!-- Creates the bundle --&gt;
      &lt;plugin&gt;
        &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
        &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
        <emphasis>&lt;extensions&gt;true&lt;/extensions&gt;</emphasis> &lt;!-- Do not forget the extensions element ! --&gt;
        &lt;configuration&gt;
          &lt;instructions&gt;
            &lt;_include&gt;-target/classes/META-INF/${project.artifactId}.bnd&lt;/_include&gt;
          &lt;/instructions&gt;
        &lt;/configuration&gt;
      &lt;/plugin&gt;
</screen>

          <para>The <literal>build/plugins</literal> section contains the
          definition (and configuration) of all the plugin(s) that will be
          invoked during the build.</para>

          <para>This snippet show the configuration to be used for the
          maven-bundle-plugin (in charge of the manifest and bundle
          generation): it simply states that it must read a <filename
          class="extension">.bnd</filename> file (located in
          <filename>src/main/resources/META-INF/***.bnd</filename>) named
          after the project's artifactId value. If this file is not present,
          <link
          xlink:href="http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html#ApacheFelixMavenBundlePlugin%28BND%29-defaultbehavior">default
          values</link> will be used.</para>

          <screen>      &lt;!-- Manipulate the bundle (iPOJO) --&gt;
      &lt;plugin&gt;
        &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
        &lt;artifactId&gt;maven-ipojo-plugin&lt;/artifactId&gt;
        &lt;version&gt;${ipojo.version}&lt;/version&gt;
        &lt;executions&gt;
          &lt;execution&gt;
            &lt;goals&gt;
              &lt;goal&gt;ipojo-bundle&lt;/goal&gt;
            &lt;/goals&gt;
          &lt;/execution&gt;
        &lt;/executions&gt;
      &lt;/plugin&gt;
</screen>

          <para>This important section hooks iPOJO in the build process. It
          will reads the <filename>src/main/resources/metadata.xml</filename>
          file as input. Then, it manipulate the bundle (modify the classes,
          update the manifest) and save it on disk.</para>
        </section>

        <section>
          <title>iPOJO component descriptor (metadata.xml)</title>

          <para>iPOJO is a Service Component Runtime aiming to simplify OSGi
          application development. You have to create the iPOJO component
          which will define your JOnAS service. This component must declare
          the provided and required services, the start/stop callback methods
          and the service properties.</para>

          <para>The iPOJO metadata file should look like the following:</para>

          <screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;ipojo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="org.apache.felix.ipojo"
       xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/1.4.0/core.xsd" &gt;

  &lt;component classname="com.company.jonas.myservice.internal.DefaultMyService"
             immediate="false"&gt;
    &lt;provides specifications="com.company.jonas.myservice.IMyService" /&gt;

    &lt;!-- Required dependencies --&gt;
    &lt;requires optional="false"
              specification="org.ow2.jonas.properties.ServerProperties"&gt;
      &lt;callback type="bind" method="setServerProperties" /&gt;
    &lt;/requires&gt;

    &lt;!-- LifeCycle Callbacks --&gt;
    &lt;callback transition="validate" method="start" /&gt;
    &lt;callback transition="invalidate" method="stop" /&gt;

    &lt;!-- Configuration properties --&gt;
    &lt;properties propagation="true"&gt;
      &lt;property name="property" method="setProperty" /&gt;
    &lt;/properties&gt;
  &lt;/component&gt;

&lt;/ipojo&gt;</screen>

          <para><emphasis role="bold">iPOJO component
          description</emphasis><itemizedlist>
              <listitem>
                <para>The component
                <emphasis><literal>classname</literal></emphasis> represents
                the service implementation class</para>
              </listitem>

              <listitem>
                <para>The <emphasis><literal>provides</literal></emphasis>
                element list all OSGi services provided by the component, here
                only the service interface</para>
              </listitem>

              <listitem>
                <para>In this example, the component requires the
                <emphasis><classname>ServerProperties</classname></emphasis>
                service which will be injected to the component instance
                during activation</para>
              </listitem>

              <listitem>
                <para>Two callbacks are defined, one for the component
                validation during service startup and one for the component
                invalidation for the service shutdown</para>
              </listitem>

              <listitem>
                <para>Property names must match service properties defined in
                the <filename>jonas.properties</filename> file. The property
                value will be injected to the component instance via
                setters</para>
              </listitem>
            </itemizedlist></para>
        </section>

        <section>
          <title>Build execution</title>

          <para>Simply type <code>mvn clean install</code> to launch the
          build, that will delete the <filename
          class="directory">target/</filename> directory (that contains only
          generated/compiled stuff) and then compile and package everything,
          including generating the bundle with its manifest and manipulating
          it with iPOJO.</para>

          <para><screen><userinput>&gt;$ mvn clean install
</userinput><computeroutput>[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building JOnAS Service 1.0.0
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- maven-resources-plugin:2.4.2:resources (default-resources) @ myservice ---
[INFO] Copying 1 resource
[INFO] 
[INFO] --- maven-compiler-plugin:2.3:compile (default-compile) @ myservice ---
[INFO] Compiling 1 source file to /home/sauthieg/sandboxes/playground/myservice/target/classes
[INFO] 
[INFO] --- maven-resources-plugin:2.4.2:testResources (default-testResources) @ myservice ---
[INFO] skip non existing resourceDirectory /home/sauthieg/sandboxes/playground/myservice/src/test/resources
[INFO] 
[INFO] --- maven-compiler-plugin:2.3:testCompile (default-testCompile) @ myservice ---
[INFO] No sources to compile
[INFO] 
[INFO] --- maven-surefire-plugin:2.5:test (default-test) @ myservice ---
[INFO] No tests to run.
[INFO] 
[INFO] --- maven-bundle-plugin:2.1.0:bundle (default-bundle) @ myservice ---
[INFO] 
[INFO] --- maven-ipojo-plugin:1.4.0:ipojo-bundle (default) @ myservice ---
[INFO] Start bundle manipulation
[INFO] Metadata file : /home/sauthieg/sandboxes/playground/myservice/target/classes/metadata.xml
[INFO] Input Bundle File : /home/sauthieg/sandboxes/playground/myservice/target/myservice-1.0.0.jar
[INFO] Bundle manipulation - SUCCESS
[INFO] 
[INFO] --- maven-install-plugin:2.3:install (default-install) @ myservice ---
[INFO] Installing /home/sauthieg/sandboxes/playground/myservice/target/myservice-1.0.0.jar to /home/sauthieg/.m2/repository/com/company/jonas/myservice/1.0.0/myservice-1.0.0.jar
[INFO] 
[INFO] --- maven-bundle-plugin:2.1.0:install (default-install) @ myservice ---
[INFO] Installing com/company/jonas/myservice/1.0.0/myservice-1.0.0.jar
[INFO] Writing OBR metadata
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 8.088s
[INFO] Finished at: Tue Jul 06 10:37:43 GMT+01:00 2010
[INFO] Final Memory: 9M/315M
[INFO] ------------------------------------------------------------------------
</computeroutput></screen></para>
        </section>
      </section>
    </section>

    <section>
      <info>
        <title>Preparing Service Installation</title>
      </info>

      <section>
        <title>Bundle Repository</title>

        <para>The generated bundle has to be placed in a maven repository that
        is available to the JOnAS instance that will host the service.</para>

        <para>2 simples solutions:<itemizedlist>
            <listitem>
              <para>Bundle was locally produced using maven, so it's already
              available in the local developer's repository (usually in
              <filename class="directory">~/.m2/repository/</filename>). This
              repository has to be declared to the JOnAS instance.</para>

              <para>The easiest way to declare a repository is to edit the
              <filename>$JONAS_BASE/conf/initial-repositories.xml</filename>
              and make sure that a similar entry is present:</para>

              <para><screen>  &lt;repository id="maven2-local-repository"&gt;
    &lt;type&gt;maven2&lt;/type&gt;
    &lt;url&gt;<emphasis>file:///home/john/.m2/repository</emphasis>&lt;/url&gt;
  &lt;/repository&gt;
</screen></para>
            </listitem>

            <listitem>
              <para>Bundle is not already present in a maven repository. It's
              necessary to place it in the appropriate location (according to
              its maven coordinates: groupId, artifactId, version,
              ...):<screen><filename>$JONAS_ROOT/repositories/maven2-internal/&lt;groupId&gt;/&lt;artifactId&gt;/&lt;version&gt;/&lt;artifactId&gt;-&lt;version&gt;.jar</filename></screen><note>
                  <para>groupId is expressed with '.' as separator in POMs,
                  but '.' are to be replaced with '/' in the location</para>
                </note>The path follows the Maven repository structure. By
              default, each JOnAS service is located in the
              <filename>$JONAS_ROOT/repositories/maven2-internal</filename>
              directory. This directory can be seen as a Maven local
              repository where JOnAS looks for <trademark>OSGi</trademark>
              bundles</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Service Deployment Plan</title>

        <para>After the setup of the maven repository hosting the new service
        bundle, a deployment plan (XML file) referencing this resource has to
        be created. This deployment plan must be placed in the
        <filename>$JONAS_ROOT/repositories/url-internal</filename> directory .
        The file name must be the same than the service name:
        <filename>myservice.xml</filename> in the example.</para>

        <important>
          <para>Deployment plan filename HAS TO BE equals to the service name
          used in the <filename>jonas.properties</filename>.</para>
        </important>

        <para>Here is an example of deployment plan that will trigger the
        installation of a bundle available as a maven artifact.</para>

        <screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;deployment-plan xmlns="http://jonas.ow2.org/ns/deployment-plan/1.0"
                 xmlns:m2="http://jonas.ow2.org/ns/deployment-plan/maven2/1.0"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="deployment-plan-1.0.xsd"
                 atomic="false"&gt;

  &lt;deployment id="com.company.jonas:myservice:jar"
              xsi:type="m2:maven2-deploymentType"
              reloadable="false"
              start="true"
              reference="true"
              startlevel="1"
              starttransient="true"&gt;
    &lt;m2:groupId&gt;com.company.jonas&lt;/m2:groupId&gt;
    &lt;m2:artifactId&gt;myservice&lt;/m2:artifactId&gt;
    &lt;m2:version&gt;1.0.0&lt;/m2:version&gt;
  &lt;/deployment&gt;

&lt;/deployment-plan&gt;
</screen>

        <para>As the service name and the deployment plan name are equal,
        JOnAS will automatically try to deploy this deployment plan during the
        service startup. This will trigger the deployment of the
        <trademark>OSGi</trademark> bundle.</para>

        <para>More information about deployment plans <link
        xlink:href="deployment-plans_guide.html">here</link>.</para>
      </section>
    </section>

    <section xml:id="Services-Modif">
      <info>
        <title>Modifying the jonas.properties file</title>
      </info>

      <para>The service is defined and its initialization parameters specified
      in the <filename>jonas.properties</filename> file. First, choose a name
      for the service (e.g. "<literal>myservice</literal>"), then do the
      following:</para>

      <itemizedlist>
        <listitem>
          <para>add this name to the <filename>jonas.services</filename>
          property; this property defines the set of services
          (comma-separated) that will be started with JOnAS.</para>
        </listitem>

        <listitem>
          <para>add a <classname>jonas.service.myservice.class</classname>
          property specifying the service implementation class.</para>
        </listitem>

        <listitem>
          <para>add <classname>jonas.service.myservice.XXX</classname>
          properties which specify the service configuration. These properties
          will be set to the implementation class before the service
          startup.</para>
        </listitem>
      </itemizedlist>

      <para>This is illustrated as follows:</para>

      <screen>jonas.services                  .......,myservice 
jonas.service.myservice.class       com.company.jonas.myservice.internal.DefaultMyService
jonas.service.myservice.property    value</screen>
    </section>
  </section>

  <section xml:id="Services-Using">
    <info>
      <title>Using the new service</title>
    </info>

    <para>When started, the new JOnAS service will espose an OSGi service as
    defined in the iPOJO component declaration which will be accessible
    through the OSGi registry. The specification of this service is defined by
    the Java interface and could be concretely looked up by specifying the
    <emphasis>com.company.jonas.myservice.IMyService</emphasis> interface.
    There are many ways to get the OSGi service reference:</para>

    <para><orderedlist>
        <listitem>
          <para>Getting the OSGi service using the BundleContext:<screen>BundleContext bundleContext = …
ServiceReference serviceReference = bundleContext.getServiceReference(IMyService.class.getName());
IMyService myService = (IMyService) bundleContext.getService(serviceReference);</screen></para>
        </listitem>

        <listitem>
          <para>Getting the OSGi service using iPOJO. iPOJO components can
          declare service requirements which will be dynamically injected to
          the component instance.</para>
        </listitem>

        <listitem>
          <para>Using another Service Component Runtime (Declarative Service,
          Dependency Manager, ...)</para>
        </listitem>
      </orderedlist></para>
  </section>

  <section xml:id="Services-Advan">
    <info>
      <title>Advanced understanding</title>
    </info>

    <para>Refer to the JOnAS sources for more details about the classes
    mentioned in this section.</para>

    <section>
      <info>
        <title>JOnAS built-in services</title>
      </info>

      <para>The existing JOnAS services are the following:</para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Service name</entry>

              <entry>Service class</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>registry</entry>

              <entry>CarolRegistryService</entry>
            </row>

            <row>
              <entry>jmx</entry>

              <entry>JOnASJMXService</entry>
            </row>

            <row>
              <entry>wc</entry>

              <entry>JOnASWorkCleanerService</entry>
            </row>

            <row>
              <entry>wm</entry>

              <entry>JOnASWorkManagerService</entry>
            </row>

            <row>
              <entry>ejb2</entry>

              <entry>JOnASEJBService</entry>
            </row>

            <row>
              <entry>ejb3</entry>

              <entry>EasyBeansService</entry>
            </row>

            <row>
              <entry>versioning</entry>

              <entry>VersioningServiceImpl</entry>
            </row>

            <row>
              <entry>web</entry>

              <entry>Tomcat6Service / Jetty6Service</entry>
            </row>

            <row>
              <entry>jaxrpc</entry>

              <entry>AxisService</entry>
            </row>

            <row>
              <entry>wsdl-publisher</entry>

              <entry>DefaultWSDLPublisherManager</entry>
            </row>

            <row>
              <entry>jaxws</entry>

              <entry>CXFService / Axis2Service</entry>
            </row>

            <row>
              <entry>ear</entry>

              <entry>JOnASEARService</entry>
            </row>

            <row>
              <entry>dbm</entry>

              <entry>JOnASDataBaseManagerService</entry>
            </row>

            <row>
              <entry>jtm</entry>

              <entry>JOTMTransactionService</entry>
            </row>

            <row>
              <entry>mail</entry>

              <entry>JOnASMailService</entry>
            </row>

            <row>
              <entry>resource</entry>

              <entry>JOnASResourceService</entry>
            </row>

            <row>
              <entry>security</entry>

              <entry>JonasSecurityServiceImpl</entry>
            </row>

            <row>
              <entry>discovery</entry>

              <entry>JgroupsDiscoveryServiceImpl /
              MulticastDiscoveryServiceImpl</entry>
            </row>

            <row>
              <entry>cmi</entry>

              <entry>CmiServiceImpl</entry>
            </row>

            <row>
              <entry>ha</entry>

              <entry>HaServiceImpl</entry>
            </row>

            <row>
              <entry>depmonitor</entry>

              <entry>DeployableMonitorService</entry>
            </row>

            <row>
              <entry>resourcemonitor</entry>

              <entry>JOnASResourceMonitorService</entry>
            </row>

            <row>
              <entry>smartclient</entry>

              <entry>SmartclientServiceImpl</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>

    <section>
      <info>
        <title>The ServiceException</title>
      </info>

      <para>The <classname>org.ow2.jonas.service.ServiceException</classname>
      exception is defined for Services. Its type is
      <classname>java.lang.RuntimeException</classname> and it can encapsulate
      any <classname> java.lang.Throwable </classname> .</para>
    </section>
  </section>
</chapter>
