Runtime

## 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, DragDropListenerService, EditorService, EditPartService, ElementSelectionService, GlobalActionHandlerService, IconService, LayoutService, MarkerNavigationService, ModelingAssistantService, PaletteService, ParserService, PropertiesService, 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`

Nested Class Summary
`static class` `Service.ProviderDescriptor` A descriptor for providers defined by a configuration element.

Field Summary
`protected static java.lang.String` `INVALID_ELEMENT_MESSAGE_PATTERN` A pattern for error messages indicating an invalid XML element.

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.

Method Summary
`protected void` `addProvider(ProviderPriority priority, Service.ProviderDescriptor provider)` Registers the `provider` as a provider for this service, with the specified `priority`.
`protected void` `clearCache()` Clears the service provider cache (if this service is optimized).
`void` `configureProviders(IConfigurationElement[] elements)` Registers the service providers described by the specified configuration `elements` with this service.
`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.
`protected java.util.Map` `createPriorityCache()` Creates a map for caching service providers keyed by the values returned in `Service.getCachingKey(IOperation)`.
`protected java.util.List` `execute(ExecutionStrategy strategy, IOperation operation)` Executes the `operation` based on the specified execution `strategy`.
`protected java.lang.Object` `executeUnique(ExecutionStrategy strategy, IOperation operation)` Executes the `operation` based on the specified execution `strategy`.
`protected java.util.List` `getAllProviders()` Retrieves a list of all providers of all priorities for this service.
`protected java.lang.Object` `getCachingKey(IOperation operation)` Gets the key used to cache service providers that provide for `operation` in the map created by `Service.createPriorityCache()`.
`java.lang.String` `getPriority(IConfigurationElement element)` Get the priority of the Provider's configuration element
`protected 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`.
`protected boolean` `isOptimistic()` Answers whether or not this service uses optimistic caching.
`protected boolean` `isOptimized()` Answers whether or not this service is optimized by caching its service providers.
`protected Service.ProviderDescriptor` `newProviderDescriptor(IConfigurationElement element)` Creates a new provider descriptor for the specified configuration `element`.
`void` `providerChanged(ProviderChangeEvent event)` Handles an event indicating that a provider has changed.
`protected 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`.
`boolean` `provides(IOperation operation)` Indicates whether or not this service can provide the functionality described by the specified `operation`.
`protected void` `removeProvider(Service.ProviderDescriptor provider)` Removes the `provider` as a provider for this service.

Methods inherited from class org.eclipse.gmf.runtime.common.core.service.AbstractProvider
`addProviderChangeListener, fireProviderChange, removeProviderChangeListener`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.eclipse.gmf.runtime.common.core.service.IProvider
`addProviderChangeListener, removeProviderChangeListener`

Field Detail

### 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

Constructor Detail

### 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.

Method Detail

### createPriorityCache

    protected java.util.Map createPriorityCache()

  Creates a map for caching service providers keyed by the values returned in `Service.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 `Service.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 `Service.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.

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.