org.eclipse.gmf.runtime.common.core.service
Class Service
java.lang.Object
org.eclipse.gmf.runtime.common.core.service.AbstractProvider
org.eclipse.gmf.runtime.common.core.service.Service
-
All Implemented Interfaces:
- java.util.EventListener,
IProvider,
IProviderChangeListener
-
Direct Known Subclasses:
-
ActionFilterService,
ContributionItemService,
DiagramEventBrokerService,
DragDropListenerService,
EditorService,
ElementSelectionService,
GlobalActionHandlerService,
IconService,
MarkerNavigationService,
ModelingAssistantService,
ParserService,
PropertiesService,
StatusLineService,
TransferAdapterService,
ViewService
-
public abstract class Service
- extends
AbstractProvider
- implements
IProvider,
IProviderChangeListener
A Service does some specific piece of work for clients by
delegating the actual work done to one or more service providers. Client
requests are made using
IOperation
s.
Modeling platform services should subclass this class.
Each service provider has a
ProviderPriority that is
declared in its extension descriptor. It is the
ExecutionStrategy that
determines how service provider priorities are used to select a provider to
service each client request. For example, if the
ExecutionStrategy.FIRST
is used, the provider with the highest priority will give an answer to the
request.
A Service may choose to have the following performance
optimizations:
- optimized, so that providers that provide for an operation are cached
the first time they are retrieved and the cache used when an operation is
executed. If the service is not optimized, all of the service providers may
be considered each time an operation is executed.
- optmistic, so that an optimized service always trusts the contents of
its cache to contain providers that provide for the given operation. If the
optimized service is not optimistic, it double-checks the contents of the
cache to make sure that the cached providers still provide for the operation.
-
See Also:
-
org.eclipse.gmf.runtime.common.core.service
|
Constructor Summary
|
protected
|
Service
()
Constructs a new service that is not optimized. |
protected
|
Service
(boolean optimized)
Constructs a new service that is (not) optimized as specified. |
protected
|
Service
(boolean optimized,
boolean optimistic)
Constructs a new service that is (not) optimized as specified. |
|
Methods inherited from class java.lang.Object
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
|
INVALID_ELEMENT_MESSAGE_PATTERN
protected static final java.lang.String INVALID_ELEMENT_MESSAGE_PATTERN
- A pattern for error messages indicating an invalid XML element.
-
See Also:
-
Constant Field Values
Service
protected Service()
- Constructs a new service that is not optimized.
Service
protected Service(boolean optimized)
- Constructs a new service that is (not) optimized as specified.
If the service is optimized, the service providers that provide for an
operation are cached the first time they are retrieved. When an operation
is executed, this cache is used to find the service providers for the
execution. If the service is not optimized, all of the service providers
may be considered each time an operation is executed.
-
Parameters:
-
optimized - true if the new service is optimized,
false otherwise.
Service
protected Service(boolean optimized,
boolean optimistic)
- Constructs a new service that is (not) optimized as specified.
If the service is optimized, the service providers that provide for an
operation are cached the first time they are retrieved. When an operation
is executed, this cache is used to find the service providers for the
execution. If the service is not optimized, all of the service providers
may be considered each time an operation is executed.
If the optimized service is optimistic, it always trusts the contents of
its cache to contain providers that provide for the given operation. If
the optimized service is not optimistic, it double-checks the contents of
the cache to make sure that the cached providers still provide for the
operation.
The value of optimistic is meaningless if
optimized is false.
-
Parameters:
-
optimized - true if the new service is optimized,
false otherwise. -
optimistic - true if the new service uses optmistic caching,
false otherwise.
createPriorityCache
protected java.util.Map createPriorityCache()
- Creates a map for caching service providers keyed by
the values returned in
getCachingKey(IOperation).
-
-
-
Returns:
- the new map
getCachingKey
protected java.lang.Object getCachingKey(
IOperation operation)
- Gets the key used to cache service providers that provide for
operation in the map created by
createPriorityCache().
-
-
-
Parameters:
-
operation - IOperation for which the key will be retrieved
-
Returns:
- the key into the service providers cache
isOptimized
protected final boolean isOptimized()
- Answers whether or not this service is optimized by caching its service
providers.
If the service is optimized, the service providers that provide for an
operation are cached the first time they are retrieved. When an operation
is executed, this cache is used to find the service providers for the
execution. If the service is not optimized, all of the service providers
may be considered each time an operation is executed.
-
-
-
Returns:
-
true if the new service is optimized,
false otherwise.
isOptimistic
protected final boolean isOptimistic()
- Answers whether or not this service uses optimistic caching. This value
is only meaningful if
isOptimized()returns true.
If the optimized service is optimistic, it always trusts the contents of
its cache to contain providers that provide for the given operation. If
the optimized service is not optimistic, it double-checks the contents of
the cache to make sure that the cached providers still provide for the
operation.
-
-
-
Returns:
-
true if the new service uses optmistic caching,
false otherwise.
clearCache
protected final void clearCache()
- Clears the service provider cache (if this service is optimized).
-
-
getProviders
protected final java.util.List getProviders(
ExecutionStrategy strategy,
ProviderPriority priority,
IOperation operation)
- Retrieves a list of providers of the specified
priority
that provide for the specified operation.
If the service is optimized, the result will be cached the first time it
is retrieved. If caching is not optimistic, the providers from the cache
will be asked again if they still provide for the operation.
-
-
-
Parameters:
-
strategy - The strategy used by the service. -
priority - The priority of providers to be retrieved. -
operation - The operation that the provides must provide.
-
Returns:
- A list of providers that provide for the operation (from the
cache, if appropriate).
getAllProviders
protected final java.util.List getAllProviders()
- Retrieves a list of all providers of all priorities for this service.
-
-
-
Returns:
- A list of all providers of all priorities.
addProvider
protected final void addProvider(
ProviderPriority priority,
Service.ProviderDescriptor provider)
- Registers the
provider as a provider for this service,
with the specified priority.
-
-
-
Parameters:
-
priority - The priority at which to add the provider. -
provider - The provider to be added.
removeProvider
protected final void removeProvider(
Service.ProviderDescriptor provider)
- Removes the
provider as a provider for this service.
-
-
-
Parameters:
-
provider - The provider to be removed.
execute
protected final java.util.List execute(
ExecutionStrategy strategy,
IOperation operation)
- Executes the
operation based on the specified execution
strategy.
-
-
-
Parameters:
-
strategy - The execution strategy to use. -
operation - The operation to be executed.
-
Returns:
- The list of results.
executeUnique
protected final java.lang.Object executeUnique(
ExecutionStrategy strategy,
IOperation operation)
- Executes the
operation based on the specified execution
strategy. If the result is a single object, return it.
Otherwise return null.
-
-
-
Parameters:
-
strategy - The execution strategy to use. -
operation - The operation to be executed.
-
Returns:
- The unique result.
provides
public final boolean provides(
IOperation operation)
- Indicates whether or not this service can provide the functionality
described by the specified
operation.
This method does not consider the optimized state of the service. All of
the providers registered with the service are consulted to determine if
they provide for the operation.
-
-
Specified by:
-
provides
in interface
IProvider
-
-
Parameters:
-
operation - The operation that describes the requested functionality.
-
Returns:
-
true if any of this service's providers provide
the operation; false otherwise.
provides
protected final boolean provides(
ExecutionStrategy strategy,
IOperation operation)
- Indicates whether or not this service can provide the functionality
described by the specified
operation using the given
execution strategy.
This method considers the optimized state of the service. If the service
is optimized, it will consult only those providers that have been cached.
-
-
-
Parameters:
-
operation - The operation in question. -
strategy - The strategy to be used.
-
Returns:
-
true if any of this service's providers provide
the operation; false otherwise.
providerChanged
public final void providerChanged(
ProviderChangeEvent event)
- Handles an event indicating that a provider has changed.
-
-
Specified by:
-
providerChanged
in interface
IProviderChangeListener
-
-
Parameters:
-
event - The provider change event to be handled.
configureProviders
public final void configureProviders(java.lang.String namespace,
java.lang.String extensionPointName)
- Registers the service providers described by the extensions of the
specified namespace and extension point name with this service.
-
-
-
Parameters:
-
namespace - the namespace for the given extension point
(e.g. "org.eclipse.gmf.runtime.common.core") -
extensionPointName - the simple identifier of the
extension point (e.g. "parserProviders")
configureProviders
public final void configureProviders(
IConfigurationElement[] elements)
- Registers the service providers described by the specified configuration
elements with this service.
-
-
-
Parameters:
-
elements - The configuration elements describing the providers.
getPriority
public java.lang.String getPriority(
IConfigurationElement element)
- Get the priority of the Provider's configuration element
-
-
-
Parameters:
-
element - The configuration elements describing the provider.
-
Returns:
- the priority of the specified configuration element
newProviderDescriptor
protected
Service.ProviderDescriptor newProviderDescriptor(
IConfigurationElement element)
- Creates a new provider descriptor for the specified configuration
element.
-
-
-
Parameters:
-
element - The configuration element from which to create the descriptor.
-
Returns:
- A new provider descriptor.
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.
