Eclipse Platform v3.1

org.eclipse.ui.internal.components.framework
Class FactoryMap

java.lang.Object
  extended by org.eclipse.ui.internal.components.framework.ServiceFactory
      extended by org.eclipse.ui.internal.components.framework.FactoryMap

public final class FactoryMap
extends ServiceFactory

Default implementation of ServiceFactory that is useful for expressing hardcoded dependency rules. A FactoryMap contains a map of component factories and an ordered list of other service factories to delegate to. It resolves dependencies like this:

  1. Check if the type is being explicitly excluded.
  2. Check if it there is a specific mapping for the dependency.
  3. Run through the list of other service factories to delegate to. The first factory that can handle the dependency will be used. When delegating, all possible types are delegated to the target object.
  4. Return null

Note that this is only a convenience class. Any methods that take a service factory as input argument should generally take an AbstractServiceFactory rather than depending on this concrete class.

Class keys must match exactly. When a service is looked up by class, the factory will not look for mappings to other compatible types if an exact match is not found.

As a convenience, all of the setters on this object return this, allowing them to be chained Smalltalk-style. For example:

// Chained initialization Container myContainer = new Container(new FactoryMap() .mapInstance(Dog.class, myDog) .mapInstance(Cat.class, myCat)); // Equivalent non-chained initialization FactoryMap context = new FactoryMap(); context.mapInstance(Dog.class, myDog); context.mapInstance(Cat.class, myCat); Container myContainer = new Container(context);

Not intended to be subclassed by clients.

EXPERIMENTAL: The components framework is currently under active development. All aspects of this class including its existence, name, and public interface are likely to change during the development of Eclipse 3.1

Since:
3.1

Constructor Summary
FactoryMap()
          Create an empty ContainerContext that does not recognize any types.
 
Method Summary
 FactoryMap add(IServiceProvider toAdd)
           
 FactoryMap add(ServiceFactory context)
          Causes the receiver to delegate to the given context whenever it can't find a dependency.
 FactoryMap addInstance(Object instance)
           
 ComponentHandle createHandle(Object key, IServiceProvider availableDependencies)
          Returns a component handle for the given key or null if this context does not recognize the given key.
 Collection getMissingDependencies()
          Returns the set of missing dependencies for this factory.
 boolean hasService(Object componentKey)
          Returns true iff the receiver knows how to create handles for the given service key.
 FactoryMap map(Object interface_, ComponentFactory adapter)
          Maps the given interface to the given factory.
 FactoryMap map(Object interfaceType, ServiceFactory context)
          Maps the given interface to the given context.
 FactoryMap mapExclusion(Object interface_)
          Blocks the given type from being returned by this context.
 FactoryMap mapInstance(Object interfaceType, Object component)
          Maps the given interface type to the given object instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FactoryMap

public FactoryMap()
Create an empty ContainerContext that does not recognize any types.

Method Detail

mapExclusion

public FactoryMap mapExclusion(Object interface_)
Blocks the given type from being returned by this context. Subsequent calls to getComponentInfo will return null when asked for this interface, even if there is an instance or parent context that can provide the component. This is not the same as unmapping the type, which simply undoes the effects of a previous mapping and may still fall through to an object registered through add*. This overrides any previous mapping for this interface, and does not affect its subtypes or supertypes.

Parameters:
interface_ - interface to exclude
Returns:
this

map

public FactoryMap map(Object interface_,
                      ComponentFactory adapter)
Maps the given interface to the given factory. The factory must be able to create objects that are assignable to the interface. This will override the effects of any previous mapping for this interface, but does not affect its subtypes or supertypes.

Parameters:
interface_ - interface to implement
adapter - a factory that can create objects of the given type
Returns:
this

map

public FactoryMap map(Object interfaceType,
                      ServiceFactory context)
Maps the given interface to the given context. Whenever this context is asked for a dependency of the given type, it will delegate to the given context. This will override the effects of any previous mapping for this interface, but does not affect its subtypes or supertypes.

Parameters:
interfaceType - interface to map
context - context to delegate to
Returns:
this

mapInstance

public FactoryMap mapInstance(Object interfaceType,
                              Object component)
Maps the given interface type to the given object instance. Whenever the context is asked for a dependency of the given type, it will return the given object. This will override the effects of any previous mapping for this interface but does not affect its subtypes or supertypes.

Parameters:
interfaceType - interface type to map
component - component instance that either implements the interface or supplies an adapter to the interface
Returns:
this

addInstance

public FactoryMap addInstance(Object instance)

add

public FactoryMap add(ServiceFactory context)
Causes the receiver to delegate to the given context whenever it can't find a dependency.

Dependencies registered through add* are processed after specific mappings registered through map*. If two add* calls can satisfy the same dependency, the one that was added first takes precidence.

Parameters:
context - newly added context
Returns:
this

add

public FactoryMap add(IServiceProvider toAdd)

createHandle

public ComponentHandle createHandle(Object key,
                                    IServiceProvider availableDependencies)
                             throws ComponentException
Description copied from class: ServiceFactory
Returns a component handle for the given key or null if this context does not recognize the given key. The handle will point to a component that is fully initialized and has all of its dependencies satisfied.

By convention, if the key is a Class instance then the resulting component must be an instance of that class.

Specified by:
createHandle in class ServiceFactory
Parameters:
key - identifier for the service to create. This is typically a Class object for a class listed as a component interface in the org.eclipse.core.components.services extension point
availableDependencies - available dependencies for the service
Returns:
a newly created component handle or null if the key is not known to this factory
Throws:
ComponentException - if unable to create the service

getMissingDependencies

public Collection getMissingDependencies()
Description copied from class: ServiceFactory
Returns the set of missing dependencies for this factory. Missing dependencies are keys that may be requested by services in this factory but which this factory cannot construct directly. Any service provider that is passed to createHandle should be able to satisfy all of the keys in this set.

Specified by:
getMissingDependencies in class ServiceFactory
Returns:
a set of service keys that are required by this factory

hasService

public boolean hasService(Object componentKey)
Description copied from class: ServiceFactory
Returns true iff the receiver knows how to create handles for the given service key. If this method returns true, createHandle should not return null for the given key in normal circumstances.

Specified by:
hasService in class ServiceFactory
Parameters:
componentKey - key to check
Returns:
true iff this factory knows about the given key

Eclipse Platform v3.1