Chapter 10. Registry Service

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 "Consumer").

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 /exo:registry node.

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.

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

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

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:

<value-param>
  <name>force-xml-configuration</name>
  <value>true</value>
</value-param>

10.2. The API

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

public abstract class Registry {
  
  /**
   * Returns the Registry object which wraps the Node of the "exo:registry" type
   */
  public abstract RegistryNode getRegistry(SessionProvider sessionProvider) 
      throws RepositoryConfigurationException, RepositoryException;
  
  /**
   * Returns the existing RegistryEntry which wraps the Node of the "exo:registryEntry" type  
   */
  public abstract RegistryEntry getEntry(SessionProvider sessionProvider, String groupName,
      String entryName) throws RepositoryException;

  /**
   * Creates a new RegistryEntry
   */
  public abstract void createEntry(SessionProvider sessionProvider,
      String groupName, RegistryEntry entry) throws RepositoryException;

  /**
   * Replaces a RegistryEntry
   */
  public abstract void recreateEntry(SessionProvider sessionProvider,
      String groupName, RegistryEntry entry) throws RepositoryException;

  /**
   * Removes a RegistryEntry
   */
  public abstract void removeEntry(SessionProvider sessionProvider,
      String groupName, String entryName) throws RepositoryException;

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.

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).

Example of RegistryService using:

    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();
     .....

10.3. Configuration

RegistryService has two optional params: value parameter mixin-names and properties parameter locations. 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).

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

Chapter 10. Registry Service

10.1. Concept

10.2. The API

10.3. Configuration