1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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>The IContributionService is a service provided at the workbench level that
provides mechanisms that clients may use to work with user interface
contributions. Currently, this is limited to providing sorters for particular
contribution types but this may be expanded on in the future. An instance of
this service is present for the entire lifetime of 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>
|
