org.picocontainer
Class DefaultPicoContainer

java.lang.Object
  extended by org.picocontainer.DefaultPicoContainer
All Implemented Interfaces:
Serializable, ComponentMonitorStrategy, Converting, Disposable, MutablePicoContainer, PicoContainer, Startable
Direct Known Subclasses:
TieringPicoContainer, TransientPicoContainer

public class DefaultPicoContainer
extends Object
implements MutablePicoContainer, Converting, ComponentMonitorStrategy, Serializable

The Standard PicoContainer/MutablePicoContainer implementation. Constructing a container c with a parent p container will cause c to look up components in p if they cannot be found inside c itself.

Using Class objects as keys to the various registerXXX() methods makes a subtle semantic difference:

If there are more than one registered components of the same type and one of them are registered with a Class key of the corresponding type, this addComponent will take precedence over other components during type resolution.

Another place where keys that are classes make a subtle difference is in HiddenImplementation.

This implementation of MutablePicoContainer also supports ComponentMonitorStrategy.

Author:
Paul Hammant, Aslak Hellesøy, Jon Tirsén, Thomas Heller, Mauro Talevi
See Also:
Serialized Form

Nested Class Summary
static class DefaultPicoContainer.KnowsContainerAdapter<T>
           
static class DefaultPicoContainer.LateInstance
           
 
Field Summary
protected  ComponentFactory componentFactory
          Component factory instance.
protected  ComponentMonitor componentMonitor
          Component monitor instance.
protected  LifecycleStrategy lifecycleStrategy
          Lifecycle strategy instance.
protected  List<ComponentAdapter<?>> orderedComponentAdapters
           
 
Constructor Summary
DefaultPicoContainer()
          Creates a new container with a AdaptingBehavior and no parent container.
DefaultPicoContainer(ComponentFactory componentFactory)
          Creates a new container with a custom ComponentFactory and no parent container.
DefaultPicoContainer(ComponentFactory componentFactory, LifecycleStrategy lifecycleStrategy, PicoContainer parent)
          Creates a new container with a custom ComponentFactory, LifecycleStrategy for instance registration, and a parent container.
DefaultPicoContainer(ComponentFactory componentFactory, LifecycleStrategy lifecycleStrategy, PicoContainer parent, ComponentMonitor componentMonitor)
           
DefaultPicoContainer(ComponentFactory componentFactory, PicoContainer parent)
          Creates a new container with a custom ComponentFactory and a parent container.
DefaultPicoContainer(ComponentMonitor monitor)
          Creates a new container with the AdaptingInjection using a custom ComponentMonitor
DefaultPicoContainer(ComponentMonitor monitor, LifecycleStrategy lifecycleStrategy, PicoContainer parent)
          Creates a new container with the AdaptingInjection using a custom ComponentMonitor and lifecycle strategy
DefaultPicoContainer(ComponentMonitor monitor, PicoContainer parent)
          Creates a new container with the AdaptingInjection using a custom ComponentMonitor
DefaultPicoContainer(LifecycleStrategy lifecycleStrategy, PicoContainer parent)
          Creates a new container with the AdaptingInjection using a custom lifecycle strategy
DefaultPicoContainer(PicoContainer parent)
          Creates a new container with a (caching) AdaptingInjection and a parent container.
 
Method Summary
 void accept(PicoVisitor visitor)
          Accepts a visitor that should visit the child containers, component adapters and component instances.
 MutablePicoContainer addAdapter(ComponentAdapter<?> componentAdapter)
          Register a component via a ComponentAdapter.
 MutablePicoContainer addAdapter(ComponentAdapter<?> componentAdapter, Properties properties)
          
protected  MutablePicoContainer addAdapterInternal(ComponentAdapter<?> componentAdapter)
           
 MutablePicoContainer addChildContainer(PicoContainer child)
          Add a child container.
 MutablePicoContainer addComponent(Object implOrInstance)
          Register an arbitrary object.
 MutablePicoContainer addComponent(Object componentKey, Object componentImplementationOrInstance, Parameter... parameters)
          Register a component and creates specific instructions on which constructor to use, along with which components and/or constants to provide as constructor arguments.
 MutablePicoContainer addConfig(String name, Object val)
          Register a config item.
 MutablePicoContainer as(Properties... properties)
          You can set for the following operation only the characteristic of registration of a component on the fly.
 MutablePicoContainer change(Properties... properties)
          You can change the characteristic of registration of all subsequent components in this container.
 void changeMonitor(ComponentMonitor monitor)
          Changes monitor in the ComponentFactory, the component adapters and the child containers, if these support a ComponentMonitorStrategy.
 ComponentMonitor currentMonitor()
          Returns the first current monitor found in the ComponentFactory, the component adapters and the child containers, if these support a ComponentMonitorStrategy.
protected  Object decorateComponent(Object component, ComponentAdapter<?> componentAdapter)
          This is invoked when getComponent(..) is called.
 void dispose()
          Dispose the components of this PicoContainer and all its logical child containers.
<T> T
getComponent(Class<T> componentType)
          Retrieve a component keyed by the component type.
<T> T
getComponent(Class<T> componentType, Class<? extends Annotation> binding)
          Retrieve a component keyed by the component type and binding type.
 Object getComponent(Object componentKeyOrType)
          Retrieve a component instance registered with a specific key or type.
 Object getComponent(Object componentKeyOrType, Class<? extends Annotation> annotation)
           
 Object getComponent(Object componentKeyOrType, Type into)
           
<T> ComponentAdapter<T>
getComponentAdapter(Class<T> componentType, Class<? extends Annotation> binding)
          Find a component adapter associated with the specified type and binding type.
<T> ComponentAdapter<T>
getComponentAdapter(Class<T> componentType, NameBinding componentNameBinding)
          Find a component adapter associated with the specified type and binding name.
 ComponentAdapter<?> getComponentAdapter(Object componentKey)
          Find a component adapter associated with the specified key.
 Collection<ComponentAdapter<?>> getComponentAdapters()
          Retrieve all the component adapters inside this container.
<T> List<ComponentAdapter<T>>
getComponentAdapters(Class<T> componentType)
          Retrieve all component adapters inside this container that are associated with the specified type.
<T> List<ComponentAdapter<T>>
getComponentAdapters(Class<T> componentType, Class<? extends Annotation> binding)
          Retrieve all component adapters inside this container that are associated with the specified type and binding type.
protected  Map<Object,ComponentAdapter<?>> getComponentKeyToAdapterCache()
           
 List<Object> getComponents()
          Retrieve all the registered component instances in the container, (not including those in the parent container).
<T> List<T>
getComponents(Class<T> componentType)
          Returns a List of components of a certain componentType.
 Converters getConverters()
          If this container has a set of converters, then return it.
protected  List<ComponentAdapter<?>> getModifiableComponentAdapterList()
           
protected  List<ComponentAdapter<?>> getOrderedComponentAdapters()
           
 PicoContainer getParent()
          Retrieve the parent container of this container.
protected  void instantiateComponentAsIsStartable(ComponentAdapter<?> adapter)
           
 MutablePicoContainer makeChildContainer()
          Make a child container, using the same implementation of MutablePicoContainer as the parent.
protected  void potentiallyStartAdapter(ComponentAdapter<?> adapter)
           
 boolean removeChildContainer(PicoContainer child)
          Remove a child container from this container.
<T> ComponentAdapter<T>
removeComponent(Object componentKey)
          Unregister a component by key.
<T> ComponentAdapter<T>
removeComponentByInstance(T componentInstance)
          Unregister a component by instance.
 void setLifecycleState(LifecycleState lifecycleState)
          To assist ThreadLocal usage, LifecycleState can be set.
 void setName(String name)
          Name the container instance, to assit debugging.
 void start()
          Start the components of this PicoContainer and all its logical child containers.
 void stop()
          Stop the components of this PicoContainer and all its logical child containers.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

componentFactory

protected final ComponentFactory componentFactory
Component factory instance.


lifecycleStrategy

protected final LifecycleStrategy lifecycleStrategy
Lifecycle strategy instance.


componentMonitor

protected ComponentMonitor componentMonitor
Component monitor instance. Receives event callbacks.


orderedComponentAdapters

protected final List<ComponentAdapter<?>> orderedComponentAdapters
Constructor Detail

DefaultPicoContainer

public DefaultPicoContainer(ComponentFactory componentFactory,
                            PicoContainer parent)
Creates a new container with a custom ComponentFactory and a parent container.

Important note about caching: If you intend the components to be cached, you should pass in a factory that creates Cached instances, such as for example Caching. Caching can delegate to other ComponentAdapterFactories.

Parameters:
componentFactory - the factory to use for creation of ComponentAdapters.
parent - the parent container (used for component dependency lookups).

DefaultPicoContainer

public DefaultPicoContainer(ComponentFactory componentFactory,
                            LifecycleStrategy lifecycleStrategy,
                            PicoContainer parent)
Creates a new container with a custom ComponentFactory, LifecycleStrategy for instance registration, and a parent container.

Important note about caching: If you intend the components to be cached, you should pass in a factory that creates Cached instances, such as for example Caching. Caching can delegate to other ComponentAdapterFactories.

Parameters:
componentFactory - the factory to use for creation of ComponentAdapters.
lifecycleStrategy - the lifecycle strategy chosen for registered instance (not implementations!)
parent - the parent container (used for component dependency lookups).

DefaultPicoContainer

public DefaultPicoContainer(ComponentFactory componentFactory,
                            LifecycleStrategy lifecycleStrategy,
                            PicoContainer parent,
                            ComponentMonitor componentMonitor)

DefaultPicoContainer

public DefaultPicoContainer(ComponentMonitor monitor,
                            PicoContainer parent)
Creates a new container with the AdaptingInjection using a custom ComponentMonitor

Parameters:
monitor - the ComponentMonitor to use
parent - the parent container (used for component dependency lookups).

DefaultPicoContainer

public DefaultPicoContainer(ComponentMonitor monitor,
                            LifecycleStrategy lifecycleStrategy,
                            PicoContainer parent)
Creates a new container with the AdaptingInjection using a custom ComponentMonitor and lifecycle strategy

Parameters:
monitor - the ComponentMonitor to use
lifecycleStrategy - the lifecycle strategy to use.
parent - the parent container (used for component dependency lookups).

DefaultPicoContainer

public DefaultPicoContainer(LifecycleStrategy lifecycleStrategy,
                            PicoContainer parent)
Creates a new container with the AdaptingInjection using a custom lifecycle strategy

Parameters:
lifecycleStrategy - the lifecycle strategy to use.
parent - the parent container (used for component dependency lookups).

DefaultPicoContainer

public DefaultPicoContainer(ComponentFactory componentFactory)
Creates a new container with a custom ComponentFactory and no parent container.

Parameters:
componentFactory - the ComponentFactory to use.

DefaultPicoContainer

public DefaultPicoContainer(ComponentMonitor monitor)
Creates a new container with the AdaptingInjection using a custom ComponentMonitor

Parameters:
monitor - the ComponentMonitor to use

DefaultPicoContainer

public DefaultPicoContainer(PicoContainer parent)
Creates a new container with a (caching) AdaptingInjection and a parent container.

Parameters:
parent - the parent container (used for component dependency lookups).

DefaultPicoContainer

public DefaultPicoContainer()
Creates a new container with a AdaptingBehavior and no parent container.

Method Detail

getComponentAdapters

public Collection<ComponentAdapter<?>> getComponentAdapters()
Retrieve all the component adapters inside this container. The component adapters from the parent container are not returned.

Specified by:
getComponentAdapters in interface PicoContainer
Returns:
a collection containing all the ComponentAdapters inside this container. The collection will not be modifiable.
See Also:
a variant of this method which returns the component adapters inside this container that are associated with the specified type.

getComponentAdapter

public final ComponentAdapter<?> getComponentAdapter(Object componentKey)
Find a component adapter associated with the specified key. If a component adapter cannot be found in this container, the parent container (if one exists) will be searched.

Specified by:
getComponentAdapter in interface PicoContainer
Parameters:
componentKey - the key that the component was registered with.
Returns:
the component adapter associated with this key, or null if no component has been registered for the specified key.

getComponentAdapter

public <T> ComponentAdapter<T> getComponentAdapter(Class<T> componentType,
                                                   NameBinding componentNameBinding)
Find a component adapter associated with the specified type and binding name. If a component adapter cannot be found in this container, the parent container (if one exists) will be searched.

Specified by:
getComponentAdapter in interface PicoContainer
Parameters:
componentType - the type of the component.
componentNameBinding - the name binding to use
Returns:
the component adapter associated with this class, or null if no component has been registered for the specified key.

getComponentAdapter

public <T> ComponentAdapter<T> getComponentAdapter(Class<T> componentType,
                                                   Class<? extends Annotation> binding)
Find a component adapter associated with the specified type and binding type. If a component adapter cannot be found in this container, the parent container (if one exists) will be searched.

Specified by:
getComponentAdapter in interface PicoContainer
Parameters:
componentType - the type of the component.
binding - the typed binding to use
Returns:
the component adapter associated with this class, or null if no component has been registered for the specified key.

getComponentAdapters

public <T> List<ComponentAdapter<T>> getComponentAdapters(Class<T> componentType)
Retrieve all component adapters inside this container that are associated with the specified type. The addComponent adapters from the parent container are not returned.

Specified by:
getComponentAdapters in interface PicoContainer
Parameters:
componentType - the type of the components.
Returns:
a collection containing all the ComponentAdapters inside this container that are associated with the specified type. Changes to this collection will not be reflected in the container itself.

getComponentAdapters

public <T> List<ComponentAdapter<T>> getComponentAdapters(Class<T> componentType,
                                                          Class<? extends Annotation> binding)
Retrieve all component adapters inside this container that are associated with the specified type and binding type. The addComponent adapters from the parent container are not returned.

Specified by:
getComponentAdapters in interface PicoContainer
Parameters:
componentType - the type of the components.
binding - the typed binding to use
Returns:
a collection containing all the ComponentAdapters inside this container that are associated with the specified type. Changes to this collection will not be reflected in the container itself.

addAdapterInternal

protected MutablePicoContainer addAdapterInternal(ComponentAdapter<?> componentAdapter)

addAdapter

public MutablePicoContainer addAdapter(ComponentAdapter<?> componentAdapter)
Register a component via a ComponentAdapter. Use this if you need fine grained control over what ComponentAdapter to use for a specific component. The adapter will be wrapped in whatever behaviors that the the container has been set up with. If you want to bypass that behavior for the adapter you are adding, you should use Characteristics.NONE like so pico.as(Characteristics.NONE).addAdapter(...) This method can be used to override the ComponentAdapter created by the ComponentFactory passed to the constructor of this container.

Specified by:
addAdapter in interface MutablePicoContainer
Parameters:
componentAdapter - the adapter
Returns:
the same instance of MutablePicoContainer

addAdapter

public MutablePicoContainer addAdapter(ComponentAdapter<?> componentAdapter,
                                       Properties properties)


removeComponent

public <T> ComponentAdapter<T> removeComponent(Object componentKey)
Unregister a component by key.

Specified by:
removeComponent in interface MutablePicoContainer
Parameters:
componentKey - key of the component to unregister.
Returns:
the ComponentAdapter that was associated with this component.

addComponent

public MutablePicoContainer addComponent(Object implOrInstance)
Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to calling addComponent(componentImplementation, componentImplementation). The returned ComponentAdapter will be an InstanceAdapter.

Specified by:
addComponent in interface MutablePicoContainer
Parameters:
implOrInstance - Component implementation or instance
Returns:
the same instance of MutablePicoContainer

addConfig

public MutablePicoContainer addConfig(String name,
                                      Object val)
Description copied from interface: MutablePicoContainer
Register a config item.

Specified by:
addConfig in interface MutablePicoContainer
Parameters:
name - the name of the config item
val - the value of the config item
Returns:
the same instance of MutablePicoContainer

addComponent

public MutablePicoContainer addComponent(Object componentKey,
                                         Object componentImplementationOrInstance,
                                         Parameter... parameters)
Register a component and creates specific instructions on which constructor to use, along with which components and/or constants to provide as constructor arguments. These "directives" are provided through an array of Parameter objects. Parameter[0] correspondes to the first constructor argument, Parameter[N] corresponds to the N+1th constructor argument.

Tips for Parameter usage


getComponents

public List<Object> getComponents()
                           throws PicoException
Description copied from interface: PicoContainer
Retrieve all the registered component instances in the container, (not including those in the parent container). The components are returned in their order of instantiation, which depends on the dependency order between them.

Specified by:
getComponents in interface PicoContainer
Returns:
all the components.
Throws:
PicoException - if the instantiation of the component fails

getComponents

public <T> List<T> getComponents(Class<T> componentType)
Description copied from interface: PicoContainer
Returns a List of components of a certain componentType. The list is ordered by instantiation order, starting with the components instantiated first at the beginning.

Specified by:
getComponents in interface PicoContainer
Parameters:
componentType - the searched type.
Returns:
a List of components.

getComponent

public Object getComponent(Object componentKeyOrType)
Description copied from interface: PicoContainer
Retrieve a component instance registered with a specific key or type. If a component cannot be found in this container, the parent container (if one exists) will be searched.

Specified by:
getComponent in interface PicoContainer
Parameters:
componentKeyOrType - the key or Type that the component was registered with.
Returns:
an instantiated component, or null if no component has been registered for the specified key.

getComponent

public Object getComponent(Object componentKeyOrType,
                           Type into)
Specified by:
getComponent in interface PicoContainer

getComponent

public Object getComponent(Object componentKeyOrType,
                           Class<? extends Annotation> annotation)

decorateComponent

protected Object decorateComponent(Object component,
                                   ComponentAdapter<?> componentAdapter)
This is invoked when getComponent(..) is called. It allows extendees to decorate a component before it is returned to the caller.

Parameters:
component - the component that will be returned for getComponent(..)
componentAdapter - the component adapter that made that component
Returns:
the component (the same as that passed in by default)

getComponent

public <T> T getComponent(Class<T> componentType)
Description copied from interface: PicoContainer
Retrieve a component keyed by the component type.

Specified by:
getComponent in interface PicoContainer
Parameters:
componentType - the type of the component
Returns:
the typed resulting object instance or null if the object does not exist.

getComponent

public <T> T getComponent(Class<T> componentType,
                          Class<? extends Annotation> binding)
Description copied from interface: PicoContainer
Retrieve a component keyed by the component type and binding type.

Specified by:
getComponent in interface PicoContainer
Parameters:
componentType - the type of the component
binding - the binding type of the component
Returns:
the typed resulting object instance or null if the object does not exist.

getParent

public PicoContainer getParent()
Retrieve the parent container of this container.

Specified by:
getParent in interface PicoContainer
Returns:
a PicoContainer instance, or null if this container does not have a parent.

removeComponentByInstance

public <T> ComponentAdapter<T> removeComponentByInstance(T componentInstance)
Unregister a component by instance.

Specified by:
removeComponentByInstance in interface MutablePicoContainer
Parameters:
componentInstance - the component instance to unregister.
Returns:
the same instance of MutablePicoContainer

start

public void start()
Start the components of this PicoContainer and all its logical child containers. The starting of the child container is only attempted if the parent container start successfully. The child container for which start is attempted is tracked so that upon stop, only those need to be stopped. The lifecycle operation is delegated to the component adapter, if it is an instance of lifecycle manager. The actual lifecycle strategy supported depends on the concrete implementation of the adapter.

Specified by:
start in interface Startable
See Also:
Behavior, LifecycleStrategy, makeChildContainer(), addChildContainer(PicoContainer), removeChildContainer(PicoContainer)

stop

public void stop()
Stop the components of this PicoContainer and all its logical child containers. The stopping of the child containers is only attempted for those that have been started, possibly not successfully. The lifecycle operation is delegated to the component adapter, if it is an instance of lifecycle manager. The actual lifecycle strategy supported depends on the concrete implementation of the adapter.

Specified by:
stop in interface Startable
See Also:
Behavior, LifecycleStrategy, makeChildContainer(), addChildContainer(PicoContainer), removeChildContainer(PicoContainer)

dispose

public void dispose()
Dispose the components of this PicoContainer and all its logical child containers. The lifecycle operation is delegated to the component adapter, if it is an instance of lifecycle manager. The actual lifecycle strategy supported depends on the concrete implementation of the adapter.

Specified by:
dispose in interface Disposable
See Also:
Behavior, LifecycleStrategy, makeChildContainer(), addChildContainer(PicoContainer), removeChildContainer(PicoContainer)

setLifecycleState

public void setLifecycleState(LifecycleState lifecycleState)
Description copied from interface: MutablePicoContainer
To assist ThreadLocal usage, LifecycleState can be set. No need to use this for normal usages.

Specified by:
setLifecycleState in interface MutablePicoContainer
Parameters:
lifecycleState - the lifecyle state to use.

makeChildContainer

public MutablePicoContainer makeChildContainer()
Description copied from interface: MutablePicoContainer
Make a child container, using the same implementation of MutablePicoContainer as the parent. It will have a reference to this as parent. This will list the resulting MPC as a child. Lifecycle events will be cascaded from parent to child as a consequence of this.

Specified by:
makeChildContainer in interface MutablePicoContainer
Returns:
the new child container.

addChildContainer

public MutablePicoContainer addChildContainer(PicoContainer child)
Description copied from interface: MutablePicoContainer
Add a child container. This action will list the the 'child' as exactly that in the parents scope. It will not change the child's view of a parent. That is determined by the constructor arguments of the child itself. Lifecycle events will be cascaded from parent to child as a consequence of calling this method.

Specified by:
addChildContainer in interface MutablePicoContainer
Parameters:
child - the child container
Returns:
the same instance of MutablePicoContainer

removeChildContainer

public boolean removeChildContainer(PicoContainer child)
Description copied from interface: MutablePicoContainer
Remove a child container from this container. It will not change the child's view of a parent. Lifecycle event will no longer be cascaded from the parent to the child.

Specified by:
removeChildContainer in interface MutablePicoContainer
Parameters:
child - the child container
Returns:
true if the child container has been removed.

change

public MutablePicoContainer change(Properties... properties)
Description copied from interface: MutablePicoContainer
You can change the characteristic of registration of all subsequent components in this container.

Specified by:
change in interface MutablePicoContainer
Returns:
the same Pico instance with changed properties

as

public MutablePicoContainer as(Properties... properties)
Description copied from interface: MutablePicoContainer
You can set for the following operation only the characteristic of registration of a component on the fly.

Specified by:
as in interface MutablePicoContainer
Returns:
the same Pico instance with temporary properties

accept

public void accept(PicoVisitor visitor)
Description copied from interface: PicoContainer
Accepts a visitor that should visit the child containers, component adapters and component instances.

Specified by:
accept in interface PicoContainer
Parameters:
visitor - the visitor

changeMonitor

public void changeMonitor(ComponentMonitor monitor)
Changes monitor in the ComponentFactory, the component adapters and the child containers, if these support a ComponentMonitorStrategy. Changes the component monitor used

Specified by:
changeMonitor in interface ComponentMonitorStrategy
Parameters:
monitor - the new ComponentMonitor to use

currentMonitor

public ComponentMonitor currentMonitor()
Returns the first current monitor found in the ComponentFactory, the component adapters and the child containers, if these support a ComponentMonitorStrategy. Returns the monitor currently used

Specified by:
currentMonitor in interface ComponentMonitorStrategy
Returns:
The ComponentMonitor currently used
Throws:
PicoCompositionException - if no component monitor is found in container or its children

potentiallyStartAdapter

protected void potentiallyStartAdapter(ComponentAdapter<?> adapter)

instantiateComponentAsIsStartable

protected void instantiateComponentAsIsStartable(ComponentAdapter<?> adapter)

getOrderedComponentAdapters

protected List<ComponentAdapter<?>> getOrderedComponentAdapters()
Returns:
the orderedComponentAdapters

getComponentKeyToAdapterCache

protected Map<Object,ComponentAdapter<?>> getComponentKeyToAdapterCache()
Returns:
the componentKeyToAdapterCache

getModifiableComponentAdapterList

protected List<ComponentAdapter<?>> getModifiableComponentAdapterList()
Returns:
the componentAdapters

setName

public void setName(String name)
Description copied from interface: MutablePicoContainer
Name the container instance, to assit debugging.

Specified by:
setName in interface MutablePicoContainer
Parameters:
name - the name to call it.

toString

public String toString()
Overrides:
toString in class Object

getConverters

public Converters getConverters()
If this container has a set of converters, then return it. If it does not, and the parent (or their parent ..) does, use that If they do not, return a NullObject implementation (ConversNothing)

Specified by:
getConverters in interface Converting
Returns:
the converters


Copyright © 2003-2010 Codehaus. All Rights Reserved.