# 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

priorityLevel (workbench|activeContexts|activeShell|activeWorkbenchWindow|activeEditorId|activePartId|activeSite) >

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.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html