Registry Service

1 Registry Service

2 Concept

The Registry Service is one of the key parts of the infrastructure built around eXo JCR. Each JCR based service, applications etc may have its own configuration and settings data and other data that have to be stored persistently and used by the approptiate service or application (let's 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.It 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. First time start from xml-config (in jar etc). Each next will be 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>

3 The API

The main functionality of the Registry Service is pretty simple and straightforward, it is described in the Registry abstract class as 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 mainly 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 have an idea 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();
     .....

4 Configuration

RegistryService has only one optional properties parameter locations. It 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>
        <properties-param>
        <name>locations</name>
        <property name="db1" value="ws2"/>
        </properties-param>
      </init-params>
  </component>