oc.cmi-doc.2.0-RC8.source-code.integratorguide.xml Maven / Gradle / Ivy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
  <bookinfo>
    <title>CMI Integrator Guide</title>

    <authorgroup>
      <author>
        <surname>Bouzonnet</surname>

        <firstname>Loris</firstname>
      </author>

      <corpauthor>JOnAS Team</corpauthor>
    </authorgroup>

    <copyright>
      <year>2007</year>

      <holder>OW2 Consortium</holder>
    </copyright>

    <abstract>
      <para>The CMI integration guide is intended for developers wanting to
      integrate CMI into their product.</para>
    </abstract>

    <date>August 2007</date>

    <productname>CMI</productname>

    <productnumber>2.0.0</productnumber>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/logo-cmi.png" />
      </imageobject>
    </mediaobject>

    <pubdate>$Id: integratorguide.xml 1254 2007-08-31 18:43:02Z loris
    $</pubdate>
  </bookinfo>

  <chapter>
    <title>Targeted people</title>

    <para>This guide describes the manner of integrating CMI in an other
    product. So the targeted people are the developers of this product.</para>

    <para>In a first time, the API for them will be introduced and next, some
    examples of real integration will be given.</para>
  </chapter>

  <chapter>
    <title>The API for integrators</title>

    <para>The API can be divided in two independent parts:</para>

    <orderedlist>
      <listitem>
        <para>an API to aggregate the CMI metadata of a clustered
        object;</para>
      </listitem>

      <listitem>
        <para>an API to add data for replication between server-side
        managers.</para>
      </listitem>
    </orderedlist>

    <para><note>
        <para>CMI metadata are added for replication while a bind to the
        context (by interception), so the second API is not in purpose of
        this.</para>
      </note></para>

    <section>
      <title>API to aggregate the CMI metadata</title>

      <para>The context provided by CMI is independent of the manner of
      declaring this informations. So, we need to convert the informations
      contained in annotations (or in a single descriptor of deployment) to
      the internal format, before performing a bind in the context.</para>

      <para>The class org.ow2.carol.cmi.info.CMIInfoExtractor provides
      convenient methods to extract these informations and encapsulate them
      into an instance of the class
      <classname>org.ow2.carol.cmi.info.ClusteredObjectInfo</classname>. The
      method <methodname>extractClusteringInfoFromAnnotatedPOJO(String,
      Class&lt;?&gt;)</methodname> is intended for annotations, and the method
      <methodname>extractClusteringInfoFromDD(String, URL)</methodname> is
      intended for descriptors of deployment.</para>

      <para>Before binding, the information needs to be associated with the
      object. There are two ways:</para>

      <orderedlist>
        <listitem>
          <para>By adding the interface
          <interfacename>org.ow2.carol.cmi.jndi.ClusteredObject</interfacename>
          at the bound object;</para>

          <para>This provides the method
          <methodname>getClusteredObjectInfo()</methodname> to retrieve the
          informations.</para>
        </listitem>

        <listitem>
          <para>By registering the instance of
          <classname>org.ow2.carol.cmi.info.ClusteredObjectInfo</classname>
          into the repository defined by the class
          <classname>org.ow2.carol.cmi.info.CMIInfoRepository</classname>.</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>API to add data for replication on server-side</title>

      <para>TODO: Adding session for load-balancing of sfsb.</para>
    </section>
  </chapter>

  <chapter>
    <title>Examples of integration</title>

    <para>This chapter describes two concrete uses of these API.</para>

    <section>
      <title>EasyBeans</title>

      <para></para>
    </section>

    <section>
      <title>JOnAS</title>

      <para></para>
    </section>
  </chapter>
</book>