Services

Identifier:

org.eclipse.ui.services

Since:

3.4

Description:

Define service factories so that services can be contributed declaratively and will be available through IServiceLocator#getService(Class). The implementation of AbstractServiceFactory must be able to return a global service and multiple child services (if applicable).

Services must follow a general contract:

The top level service has no parent.
The child service may use the supplied parent, which can be cast to the service interface.
Any other services needed for initialization should be retrieved from the IServiceLocator.
If the service needs to clean up any state (like listeners) it should implement IDisposable.
Services should clearly specify when they perform cleanup for clients, such as removing listeners automatically on disposal.

Configuration Markup:

<!ELEMENT extension (serviceFactory? , sourceProvider?)+>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

Contribute services to the workbench.

<!ELEMENT serviceFactory (service+)>

<!ATTLIST serviceFactory

factoryClass CDATA #REQUIRED>

Match a service interface to a factory that can supply a hierachical implementation of that service.

factoryClass - The factory that extends AbstractServiceFactory and can create the implementation for the serviceClass.

<!ELEMENT service EMPTY>

<!ATTLIST service

serviceClass CDATA #IMPLIED>

A service this factory can provide.

serviceClass - The interface that represents a service contract.

<!ELEMENT sourceProvider (variable+)>

<!ATTLIST sourceProvider

provider CDATA #REQUIRED>

A Source Provider supplies source variables to the IEvaluationService. It can also notify the IEvaluationService when one or more of the variables change.

provider - This class must provide variables and call the appropriate fireSourceChanged(*) method when any of the variables change.

<!ELEMENT variable EMPTY>

<!ATTLIST variable

name CDATA #REQUIRED

A source variable from this provider. A source provider must declare all variables that it provides.

name - The name of a contributed source variable. It is a good practice to prepend the plugin id to the variable name to avoid collisions with other source providers.
priorityLevel - For conflict resolution used by services like the IHandlerService. The source must select a priority for all contributed variables. workbench is the global default priority. See ISources for relative priority information.

Examples:

Here is a basic definition:


   <extension
         point="org.eclipse.ui.services">
      <serviceFactory
            factoryClass="org.eclipse.ui.tests.services.LevelServiceFactory">
         <service
               serviceClass="org.eclipse.ui.tests.services.ILevelService">
         </service>
      </serviceFactory>
   </extension>

The LevelServiceFactory can return an ILevelService when it is requested from the IServiceLocator:


   ILevelService s = (ILevelService) getSite().getService(ILevelService.class);
   System.out.println(s.getLevel());

In this test example, the factory would instantiate three ILevelService implementations during the first call to getSite().getService(*). The global one in the workbench, one for the workbench window, and one for the site.

API Information:

Please see org.eclipse.ui.services.AbstractServiceFactory, org.eclipse.ui.services.IDisposable, and org.eclipse.ui.services.IServiceWithSources for more information.

Copyright (c) 2007 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0