<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="JCR.RegistryService">
  <title>Registry Service</title>

  <section id="JCR.RegistryService.Concept">
    <title>Concept</title>

    <para>The Registry Service is one of the key parts of the infrastructure
    built around eXo JCR. Each JCR that is based on service, applications, etc
    may have its own configuration, settings data and other data that have to
    be stored persistently and used by the approptiate service or application.
    ( We call it "<emphasis role="bold">Consumer</emphasis>").</para>

    <para>The service acts as a centralized collector (Registry) for such
    data. Naturally, a registry storage is JCR based i.e. stored in some JCR
    workspace (one per Repository) as an Item tree under <emphasis
    role="bold">/exo:registry</emphasis> node.</para>

    <para>Despite the fact that the structure of the tree is well defined (see
    the scheme below), it is not recommended for other services to manipulate
    data using JCR API directly for better flexibility. So the Registry
    Service acts as a mediator between a Consumer and its settings.</para>

    <para>The proposed structure of the Registry Service storage is divided
    into 3 logical groups: services, applications and users:</para>

    <programlisting> exo:registry/          &lt;-- registry "root" (exo:registry)
   exo:services/        &lt;-- service data storage (exo:registryGroup)
     service1/
       Consumer data    (exo:registryEntry)
     ...
   exo:applications/    &lt;-- application data storage (exo:registryGroup)
     app1/
       Consumer data    (exo:registryEntry)
     ...
   exo:users/           &lt;-- user personal data storage (exo:registryGroup)
     user1/
       Consumer data    (exo:registryEntry)
     ...</programlisting>

    <para>Each upper level eXo Service may store its configuration in eXo
    Registry. At first, start from xml-config (in jar etc) and then from
    Registry. In configuration file, you can add force-xml-configuration
    parameter to component to ignore reading parameters initialization from
    RegistryService and to use file instead:</para>

    <programlisting language="xml">&lt;value-param&gt;
  &lt;name&gt;force-xml-configuration&lt;/name&gt;
  &lt;value&gt;true&lt;/value&gt;
&lt;/value-param&gt;</programlisting>
  </section>

  <section id="JCR.RegistryService.API">
    <title>The API</title>

    <para>The main functionality of the Registry Service is pretty simple and
    straightforward, it is described in the Registry abstract class as the
    following:</para>

    <programlisting language="java">public abstract class Registry
{

   /**
    * Returns Registry node object which wraps Node of "exo:registry" type (the whole registry tree)
    */
   public abstract RegistryNode getRegistry(SessionProvider sessionProvider) throws RepositoryConfigurationException,
      RepositoryException;

   /**
    * Returns existed RegistryEntry which wraps Node of "exo:registryEntry" type
    */
   public abstract RegistryEntry getEntry(SessionProvider sessionProvider, String entryPath)
      throws PathNotFoundException, RepositoryException;

   /**
    * creates an entry in the group. In a case if the group does not exist it will be silently
    * created as well
    */
   public abstract void createEntry(SessionProvider sessionProvider, String groupPath, RegistryEntry entry)
      throws RepositoryException;

   /**
    * updates an entry in the group
    */
   public abstract void recreateEntry(SessionProvider sessionProvider, String groupPath, RegistryEntry entry)
      throws RepositoryException;

   /**
    * removes entry located on entryPath (concatenation of group path / entry name)
    */
   public abstract void removeEntry(SessionProvider sessionProvider, String entryPath) throws RepositoryException;

}</programlisting>

    <para>As you can see it looks like a simple CRUD interface for the
    RegistryEntry object which wraps registry data for some Consumer as a
    Registry Entry. The Registry Service itself knows nothing about the
    wrapping data, it is Consumer's responsibility to manage and use its data
    in its own way.</para>

    <para>To create an Entity Consumer you should know how to serialize the
    data to some XML structure and then create a RegistryEntry from these data
    at once or populate them in a RegistryEntry object (using
    RegistryEntry(String entryName) constructor and then obtain and fill a DOM
    document).</para>

    <para>Example of RegistryService using:</para>

    <programlisting language="java">    RegistryService regService = (RegistryService) container
    .getComponentInstanceOfType(RegistryService.class);

    RegistryEntry registryEntry = regService.getEntry(sessionProvider,
            RegistryService.EXO_SERVICES + "/my-service");

    Document doc = registryEntry.getDocument();
    
    String mySetting = getElementsByTagName("tagname").item(index).getTextContent();
     .....</programlisting>
  </section>

  <section id="JCR.RegistryService.Configuration">
    <title>Configuration</title>

    <para>RegistryService has two optional params: value parameter <emphasis
    role="bold">mixin-names</emphasis> and properties parameter <emphasis
    role="bold">locations</emphasis>. The mixin-names is used for adding
    additional mixins to nodes exo:registry, exo:applications, exo:services,
    exo:users and exo:groups of RegistryService. This allows the top level
    applications to manage these nodes in special way. Locations is used to
    mention where exo:registry is placed for each repository. The name of each
    property is interpreted as a repository name and its value as a workspace
    name (a system workspace by default).</para>

    <programlisting language="xml">&lt;component&gt;
   &lt;type&gt;org.exoplatform.services.jcr.ext.registry.RegistryService&lt;/type&gt;
   &lt;init-params&gt;
      &lt;values-param&gt;
         &lt;name&gt;mixin-names&lt;/name&gt;
         &lt;value&gt;exo:hideable&lt;/value&gt;      
      &lt;/values-param&gt;
      &lt;properties-param&gt;         
      &lt;name&gt;locations&lt;/name&gt;
         &lt;property name="db1" value="ws2"/&gt;
      &lt;/properties-param&gt;
   &lt;/init-params&gt;
&lt;/component&gt;</programlisting>
  </section>
</section>
