| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <TITLE> |
| Services |
| </TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| <h2>Services</h2> |
| <p>The workbench defines a number of services that can be retrieved from the |
| <a href="../reference/api/org/eclipse/ui/services/IServiceLocator.html">org.eclipse.ui.services.IServiceLocator</a>. |
| Services provide a way for components to retrieve information about the workbench |
| without always having to go to the global singleton: <code>PlatformUI.getWorkbench()</code>. |
| For example: |
| </p> |
| <pre> |
| IHandlerService handlerService = (IHandlerService) getSite() |
| .getService(IHandlerService.class); |
| </pre> |
| <p> |
| Some services provide 2 optional abilities, which are usually specified in the |
| service interface javadoc:</p> |
| <ul> |
| <li>Services that support listeners can clean up the listeners automatically |
| when the component's |
| <a href="../reference/api/org/eclipse/ui/services/IServiceLocator.html">org.eclipse.ui.services.IServiceLocator</a> |
| (used to get the service) is disposed.</li> |
| <li>Services can provide more localized services depending on which component they |
| are requested from.</li> |
| </ul> |
| <p>See <a href="workbench_cmd_handlers.htm" |
| class="XRef">Associating a handler programmically with a command...</a> |
| for an example of the activation localization provided by the |
| <a href="../reference/api/org/eclipse/ui/handlers/IHandlerService.html">org.eclipse.ui.handlers.IHandlerService</a>. |
| </p> |
| <h3> |
| Services Provided by the Workbench |
| </h3> |
| <p> |
| The services provided to by the workbench now includes some of the most |
| common services that an |
| <a href="../reference/api/org/eclipse/ui/IWorkbenchPart.html">org.eclipse.ui.IWorkbenchPart</a> |
| would require. Support for service related optional abilities are specified in the service javadoc. |
| The availability of the service is at and below the level specified.</p> |
| <table border="1"> |
| <tr> |
| <th>Service</th> |
| <th>Description</th> |
| <th>Availability</th> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/keys/IBindingService.html">IBindingService</a> |
| </td> |
| <td>Provides services related to the binding architecture (e.g., keyboard |
| shortcuts) within the workbench.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/commands/ICommandService.html">ICommandService</a> |
| </td> |
| <td>Provides services related to the command architecture within the workbench.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/commands/ICommandImageService.html">ICommandImageService</a> |
| </td> |
| <td>Provides a look-up facility for images associated with commands.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/contexts/IContextService.html">IContextService</a> |
| </td> |
| <td>Provides services related to contexts in the Eclipse workbench, like context |
| activation and definitions.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/model/IContributionService.html">IContributionService</a> |
| </td> |
| <td>Instances of this service are capable of providing standard mechanisms that |
| clients may use to order, display, and generally work with contributions to |
| the Workbench.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/services/IEvaluationService.html">IEvaluationService</a> |
| </td> |
| <td>Evaluate a core expression against the workbench application context and |
| report updates using a Boolean property. Also provides the main source for |
| the workbench application context.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/swt/IFocusService.html">IFocusService</a> |
| </td> |
| <td>Tracks focusGained and focusLost events for a Control registered with this |
| service, and provides the control and its registered ID as variables to the |
| application evaluation context for evaluation by the various services.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/handlers/IHandlerService.html">IHandlerService</a> |
| </td> |
| <td>Provides services related to activating and deactivating handlers within the |
| workbench.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/menus/IMenuService.html">IMenuService</a> |
| </td> |
| <td>Provides services related to the menu architecture within the workbench. It |
| can be used to populate MenuManagers and ToolBarManagers by components.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/IPageService.html">IPageService</a> |
| </td> |
| <td>A page service tracks the page and perspective lifecycle events |
| within a workbench window.</td> |
| <td>Workbench Window</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/IPartService.html">IPartService</a> |
| </td> |
| <td>A part service tracks the creation and activation of parts within a |
| workbench window.</td> |
| <td>Workbench Window</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/progress/IProgressService.html">IProgressService</a> |
| </td> |
| <td>The progress service is the primary interface to the workbench progress support.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/progress/IWorkbenchSiteProgressService.html">IWorkbenchSiteProgressService</a> |
| </td> |
| <td>The part progress service is an IProgressService that adds API for jobs |
| that change the state in a IWorkbenchPartSite while they are being run.</td> |
| <td>Part Site</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/ISaveablesLifecycleListener.html">ISaveablesLifecycleListener</a> |
| </td> |
| <td>Parts that implement |
| <a href="../reference/api/org/eclipse/ui/ISaveablesSource.html">org.eclipse.ui.ISaveablesSource</a> |
| should notify their |
| <code>ISaveablesLifecycleListener</code>, available as a service from their site, about |
| <a href="../reference/api/org/eclipse/ui/Saveable.html">org.eclipse.ui.Saveable</a> |
| objects that have been added to or removed from the |
| part. Implementations of <code>ISaveablesSource</code> that are |
| not parts should retrieve this service from the |
| <a href="../reference/api/org/eclipse/ui/IWorkbench.html">org.eclipse.ui.IWorkbench</a> |
| object.</td> |
| <td>Globally</td> |
| </tr> |
| |
| <tr> |
| <td><a href="../reference/api/org/eclipse/ui/ISelectionService.html">ISelectionService</a> |
| </td> |
| <td>A selection service tracks the selection within an a workbench window.</td> |
| <td>Workbench Window</td> |
| </tr> |
| |
| </table> |
| |
| <h3> |
| Contributing a Service |
| </h3> |
| <p> |
| Plug-in developers providing a framework in eclipse may also want to provide a service. |
| This can be done using the |
| <a href="../reference/extension-points/org_eclipse_ui_services.html">org.eclipse.ui.services</a> |
| extension point. Define a service factory based on |
| <a href="../reference/api/org/eclipse/ui/services/AbstractServiceFactory.html">org.eclipse.ui.services.AbstractServiceFactory</a> |
| and then specify what services the factory can return. |
| A factory can create more than one type of service, but multiple factories cannot |
| contribute to the same service type. |
| </p> |
| <pre> |
| <serviceFactory |
| factoryClass="org.eclipse.ui.examples.contributions.model.PersonServiceFactory"> |
| <service |
| serviceClass="org.eclipse.ui.examples.contributions.model.IPersonService"/> |
| </serviceFactory> |
| </pre> |
| <p> |
| The create method of the |
| <a href="../reference/api/org/eclipse/ui/services/AbstractServiceFactory.html">org.eclipse.ui.services.AbstractServiceFactory</a> |
| passes in 3 parameters:</p> |
| <ul> |
| <li><code>serviceInterface</code> - the interface class that needs to be created</li> |
| <li><code>parentLocator</code> - an |
| <a href="../reference/api/org/eclipse/ui/services/IServiceLocator.html">org.eclipse.ui.services.IServiceLocator</a> |
| that can be used to get the parent service for <code>serviceInterface</code></li> |
| <li><code>locator</code> - the |
| <a href="../reference/api/org/eclipse/ui/services/IServiceLocator.html">org.eclipse.ui.services.IServiceLocator</a> |
| that requested this service be created. It can be used to retrieve dependent services.</li> |
| </ul> |
| <p> |
| Workbench services are organized so there is a global service providing the |
| needed functionality, and a chain of children services. The children services provide |
| the listener cleanup and any data needed to localize the service request. |
| </p> |
| <p>A service |
| factory should return the global service when the <code>parentLocator</code> returns |
| <code>null</code> when asked for the <code>serviceInterface</code>. The global service |
| may be the implementation, or a proxy to a plugin provided manager or OSGi service. |
| </p> |
| <pre> |
| Object parentService = parentLocator.getService(IPersonService.class); |
| if (parentService == null) { |
| return new PersonService(locator); |
| } |
| return new PersonServiceSlave(locator, (IPersonService) parentService); |
| |
| // or ... |
| Object parentService = parentLocator.getService(IPersonService.class); |
| if (parentService == null) { |
| return Activator.getDefault().getPersonManager(); |
| } |
| return new PersonServiceSlave(locator, (IPersonService) parentService); |
| |
| // |
| // or as a front to an OSGi service. |
| Object parentService = parentLocator.getService(IPersonService.class); |
| if (parentService == null) { |
| PersonServiceProxy proxy = new PersonServiceProxy(locator, |
| Activator.getDefault().getBundle().getBundleContext(), |
| 0); |
| proxy.findService(); |
| return proxy; |
| } |
| PersonServiceProxy proxy = new PersonServiceProxy(locator, |
| Activator.getDefault().getBundle().getBundleContext(), |
| ((PersonServiceProxy)parentService).getLevel()+1); |
| proxy.findService(); |
| return proxy; |
| </pre> |
| <p>In the OSGi service snippet above, instead of having each child <code>IPersonService</code> know |
| its parent, each <code>IPersonService</code> talks directly to the OSGi service and uses |
| the parent to calculate its "level" which allows it to localize any functionality |
| it provides. |
| </p> |
| |
| </BODY> |
| </HTML> |
