View source for Papyrus/Papyrus Developer Guide/Service Registry

= ServiceRegistry  =

The ServiceRegistry is one of the main Papyrus component. The idea is that each Papyrus feature should be a service registered to the ServiceRegistry. 

The ServiceRegistry should be accessible from any code. It allows to retrieve the components you need to perform your task. <br> 

This page describe the new ServiceRegistry, released on september 2012.<br> 

= Features<br>  =

The services framework allow to register and then to retrieve services in a ServicesRegistry. A service is an instance of Java classes providing any kind of behavior. This instance can be retrieved by an unique identifier. <br>Services are registered in the ServicesRegistry with a unique identifier (ID). This ID is also used to retrieve a service from the ServicesRegistry. Usually, the ID is the Class name or the interface name of the service. 

A ServicesRegistry is used as a namespace: all registered services have a unique ID inside the namespace/ServiceRegistry.<br>An application can have more than one ServicesRegistry, each one owning is own set of services, which can be different from a Registry to the other. 

A ServicesRegistry can have parents that are also ServicesRegistry. This is useful to have hierarchical search of services: When a service is required from a ServicesRegistry, this later first look inside its namespace. If the service is not found, the ServicesRegistry delegates the search to its parents. 

The ServicesRegistry namespace can be associated to a unique identifier. On another hand, the declaration of a service can specify to which namespace the service should belong. This allows to create set of services, and to let a ServicesRegistry load the services associated to a namespace. For example, the Papyrus application can declare "papyrus services", and another application can declare its own services. 

The ServicesRegistry namespace can extends other namespaces. In this case, the resulting namespace is a kind of union (with no double) of services found in the different namespaces. This mechanism allows to overload services declared in one of the extended namespace. As example, this mechanism can be used to declare one core ServicesRegistry containing the minimal services required by an application without UI, and one extended ServicesRegistry containing all the services required by the full application with UI. 

The ServicesRegistry namespace can be declared in an Eclipse extension, or in a Service Model. The ServicesRegistry can then be initialized by simply specifying which namespace should be loaded. A ServicesRegistry can load more than one declared namespace. 

A service is described with a ServiceDescriptor. This descriptor specifies the instance classname, some initialization, the registry namespace, some data and services required by the described service. The descriptor can be declared programmatically, in an Eclipse extension, or in a Service Model.<br> 

= Status  =

*The new ServiceRegistry is not used yet in Papyrus. 
*A class allowing to read old Papyrus service declarations is needed (implementing IServiceDescriptorsWithIdProvider) 
*Declaring services with java annotations is not implemented yet.

= Usage Examples<br>  =


== Services declaration in plugin.xml ==

The following example is an excerpt from the test plugin (resources/plugin.xml). It show how to declare registry a<br>


<source lang="xml">
   <extension point="org.eclipse.papyrus.infra.core.serviceregistry.service">
     <servicesSet id="simpleTest">
        <service
              classname="org.eclipse.papyrus.infra.core.serviceregistry.FakeServiceA"
              priority="1"
              startKind="startup">
        </service>
        <service
              classname="org.eclipse.papyrus.infra.core.serviceregistry.FakeServiceC"
              priority="1"
              startKind="lazy">
           <dependsOn
                 serviceId="org.eclipse.papyrus.infra.core.serviceregistry.FakeServiceA">
           </dependsOn>
        </service>
        <extendedServiceSet
              serviceSetId="papyrusWizard">
        </extendedServiceSet>
     </servicesSet>
     <registry
           id="simpleTestRegistry"
           isUnique="false">
        <serviceSets
              serviceSetId="simpleTest">
        </serviceSets>
    </registry>
     <servicesSet
           id="papyrusWizard">
        <service
              classname="org.eclipse.papyrus.infra.core.serviceregistry.FakeServiceB"
              priority="1"
              startKind="startup">
        </service>
     </servicesSet>
     <registry
           id="papyrusWizardRegistry"
           isUnique="false">
        <serviceSets
              serviceSetId="papyrusWizard">
        </serviceSets>
     </registry>
 ...
</source>


== Getting the ServiceRegistry from code ==

This example shows how to create a ServiceRegistry. This should be done once only in an application.

<source lang="java">
  // Get an object that will read services declaration from Eclipse 
  // extensions (declared in plugin.xml)
  // We can have several providers if needed.
  // For example, we could develop a provider compatible with the 
  // old ServiceRegistry declaration scheme (TODO)
  IServiceDescriptorsWithIdProvider declarationsProvider = new ExtensionServiceDescriptorsWithIdProvider();
  // Create ServiceRegistry factory
  ServiceRegistryFactory factory = new ServiceRegistryFactory(declarationsProvider);	
  // Create ServiceRegistry from factory
  ServicesRegistry registry = factory.getServicesRegistry("simpleTestRegistry");
  // Start registered services
  registry.startNewServices();
</source>