org.picocontainer.defaults
Class DefaultPicoContainer

java.lang.Object
  extended byorg.picocontainer.defaults.DefaultPicoContainer
All Implemented Interfaces:
Disposable, MutablePicoContainer, PicoContainer, Serializable, Startable

public class DefaultPicoContainer
extends Object
implements MutablePicoContainer, 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 component will take precedence over other components during type resolution.

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

Version:
$Revision: 1.8 $
Author:
Paul Hammant, Aslak Hellesøy, Jon Tirsén, Thomas Heller
See Also:
Serialized Form

Field Summary
static PicoContainer EMPTY_IMMUTABLE_INSTANCE
          Empty immutable container.
 
Constructor Summary
DefaultPicoContainer()
          Creates a new container with a (caching) DefaultComponentAdapterFactory and no parent container.
DefaultPicoContainer(ComponentAdapterFactory componentAdapterFactory)
          Creates a new container with a custom ComponentAdapterFactory and no parent container.
DefaultPicoContainer(ComponentAdapterFactory componentAdapterFactory, PicoContainer parent)
          Creates a new container with a custom ComponentAdapterFactory and a parent container.
DefaultPicoContainer(PicoContainer parent)
          Creates a new container with a (caching) DefaultComponentAdapterFactory and a parent container.
 
Method Summary
 void addOrderedComponentAdapter(ComponentAdapter componentAdapter)
          Callback method from the implementation to keep track of the instantiation order.
 void dispose()
          Dispose this component.
 ComponentAdapter getComponentAdapter(Object componentKey)
          Find a component adapter associated with the specified key.
 ComponentAdapter getComponentAdapterOfType(Class componentType)
          Find a component adapter associated with the specified type.
 Collection getComponentAdapters()
          Retrieve all the component adapters inside this container.
 List getComponentAdaptersOfType(Class componentType)
          Retrieve all component adapters inside this container that are associated with the specified type.
 Object getComponentInstance(Object componentKey)
          Retrieve a component instance registered with a specific key.
 Object getComponentInstanceOfType(Class componentType)
          Find a component instance matching the specified type.
 List getComponentInstances()
          Retrieve all the registered component instances in the container, (not including those in the parent container).
 List getComponentInstancesOfType(Class type)
           
 PicoContainer getParent()
          Retrieve the parent container of this container.
 ComponentAdapter registerComponent(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. This method can be used to override the ComponentAdapter created by the ComponentAdapterFactory passed to the constructor of this container.
 ComponentAdapter registerComponentImplementation(Class componentImplementation)
          Register a component using the componentImplementation as key. Calling this method is equivalent to calling registerComponentImplementation(componentImplementation, componentImplementation). The returned ComponentAdapter will be instantiated by the ComponentAdapterFactory passed to the container's constructor.
 ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation)
          Register a component. The returned ComponentAdapter will be instantiated by the ComponentAdapterFactory passed to the container's constructor.
 ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation, List parameters)
           
 ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation, Parameter[] parameters)
          Register a component. The returned ComponentAdapter will be instantiated by the ComponentAdapterFactory passed to the container's constructor.
 ComponentAdapter registerComponentInstance(Object component)
          Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to calling * registerComponentImplementation(componentImplementation, componentImplementation). The returned ComponentAdapter will be an InstanceComponentAdapter.
 ComponentAdapter registerComponentInstance(Object componentKey, Object componentInstance)
          Register an arbitrary object as a component in the container. This is handy when other components in the same container have dependencies on this kind of object, but where letting the container manage and instantiate it is impossible.

Beware that too much use of this method is an antipattern. The returned ComponentAdapter will be an InstanceComponentAdapter.

 void setParent(PicoContainer parent)
          Set the Parent container.
 void start()
          Start this component.
 void stop()
          Stop this component.
 ComponentAdapter unregisterComponent(Object componentKey)
          Unregister a component by key.
 ComponentAdapter unregisterComponentByInstance(Object componentInstance)
          Unregister a component by instance.
 void verify()
          Verify that the dependencies for all the registered components can be satisfied.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_IMMUTABLE_INSTANCE

public static final PicoContainer EMPTY_IMMUTABLE_INSTANCE
Empty immutable container. The lifecycle methods can be invoked several times without throwing exceptions.

Constructor Detail

DefaultPicoContainer

public DefaultPicoContainer(ComponentAdapterFactory componentAdapterFactory,
                            PicoContainer parent)
Creates a new container with a custom ComponentAdapterFactory and a parent container.

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

Parameters:
componentAdapterFactory - the factory to use for creation of ComponentAdapters.
parent - the parent container.

DefaultPicoContainer

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


DefaultPicoContainer

public DefaultPicoContainer(ComponentAdapterFactory componentAdapterFactory)
Creates a new container with a custom ComponentAdapterFactory and no parent container.


DefaultPicoContainer

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

Method Detail

getComponentAdapters

public Collection getComponentAdapters()
Description copied from interface: PicoContainer
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)
                                           throws AmbiguousComponentResolutionException
Description copied from interface: PicoContainer
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.
Throws:
AmbiguousComponentResolutionException

getComponentAdapterOfType

public ComponentAdapter getComponentAdapterOfType(Class componentType)
Description copied from interface: PicoContainer
Find a component adapter associated with the specified type. If a component adapter cannot be found in this container, the parent container (if one exists) will be searched.

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

getComponentAdaptersOfType

public List getComponentAdaptersOfType(Class componentType)
Description copied from interface: PicoContainer
Retrieve all component adapters inside this container that are associated with the specified type. The component adapters from the parent container are not returned.

Specified by:
getComponentAdaptersOfType 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.

registerComponent

public ComponentAdapter registerComponent(ComponentAdapter componentAdapter)
                                   throws DuplicateComponentKeyRegistrationException
Register a component via a ComponentAdapter. Use this if you need fine grained control over what ComponentAdapter to use for a specific component. This method can be used to override the ComponentAdapter created by the ComponentAdapterFactory passed to the constructor of this container.

Specified by:
registerComponent in interface MutablePicoContainer
Parameters:
componentAdapter - the adapter
Returns:
the same adapter that was passed as an argument.
Throws:
DuplicateComponentKeyRegistrationException

unregisterComponent

public ComponentAdapter unregisterComponent(Object componentKey)
Description copied from interface: MutablePicoContainer
Unregister a component by key.

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

registerComponentInstance

public ComponentAdapter registerComponentInstance(Object component)
                                           throws PicoRegistrationException
Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to calling * registerComponentImplementation(componentImplementation, componentImplementation). The returned ComponentAdapter will be an InstanceComponentAdapter.

Specified by:
registerComponentInstance in interface MutablePicoContainer
Parameters:
component -
Returns:
the ComponentAdapter that has been associated with this component. In the majority of cases, this return value can be safely ignored, as one of the getXXX() methods of the PicoContainer interface can be used to retrieve a reference to the component later on.
Throws:
PicoRegistrationException - if registration fails.

registerComponentInstance

public ComponentAdapter registerComponentInstance(Object componentKey,
                                                  Object componentInstance)
                                           throws PicoRegistrationException
Register an arbitrary object as a component in the container. This is handy when other components in the same container have dependencies on this kind of object, but where letting the container manage and instantiate it is impossible.

Beware that too much use of this method is an antipattern. The returned ComponentAdapter will be an InstanceComponentAdapter.

Specified by:
registerComponentInstance in interface MutablePicoContainer
Parameters:
componentKey - a key that identifies the component. Must be unique within the conainer. The type of the key object has no semantic significance unless explicitly specified in the implementing container.
componentInstance - an arbitrary object.
Returns:
the ComponentAdapter that has been associated with this component. In the majority of cases, this return value can be safely ignored, as one of the getXXX() methods of the PicoContainer interface can be used to retrieve a reference to the component later on.
Throws:
PicoRegistrationException - if registration fails.

registerComponentImplementation

public ComponentAdapter registerComponentImplementation(Class componentImplementation)
                                                 throws PicoRegistrationException
Register a component using the componentImplementation as key. Calling this method is equivalent to calling registerComponentImplementation(componentImplementation, componentImplementation). The returned ComponentAdapter will be instantiated by the ComponentAdapterFactory passed to the container's constructor.

Specified by:
registerComponentImplementation in interface MutablePicoContainer
Parameters:
componentImplementation - the concrete component class.
Returns:
the ComponentAdapter that has been associated with this component. In the majority of cases, this return value can be safely ignored, as one of the getXXX() methods of the PicoContainer interface can be used to retrieve a reference to the component later on.
Throws:
PicoRegistrationException - if registration fails.

registerComponentImplementation

public ComponentAdapter registerComponentImplementation(Object componentKey,
                                                        Class componentImplementation)
                                                 throws PicoRegistrationException
Register a component. The returned ComponentAdapter will be instantiated by the ComponentAdapterFactory passed to the container's constructor.

Specified by:
registerComponentImplementation in interface MutablePicoContainer
Parameters:
componentKey - a key that identifies the component. Must be unique within the container. The type of the key object has no semantic significance unless explicitly specified in the documentation of the implementing container.
componentImplementation - the component's implementation class. This must be a concrete class (ie, a class that can be instantiated).
Returns:
the ComponentAdapter that has been associated with this component. In the majority of cases, this return value can be safely ignored, as one of the getXXX() methods of the PicoContainer interface can be used to retrieve a reference to the component later on.
Throws:
PicoRegistrationException - if registration of the component fails.
See Also:
a variant of this method that allows more control over the parameters passed into the componentImplementation constructor when constructing an instance.

registerComponentImplementation

public ComponentAdapter registerComponentImplementation(Object componentKey,
                                                        Class componentImplementation,
                                                        Parameter[] parameters)
                                                 throws PicoRegistrationException
Register a component. The returned ComponentAdapter will be instantiated by the ComponentAdapterFactory passed to the container's constructor.

Specified by:
registerComponentImplementation in interface MutablePicoContainer
Parameters:
componentKey - a key that identifies the component. Must be unique within the container. The type of the key object has no semantic significance unless explicitly specified in the documentation of the implementing container.
componentImplementation - the component's implementation class. This must be a concrete class (ie, a class that can be instantiated).
parameters - an array of parameters that gives the container hints about what arguments to pass to the constructor when it is instantiated. Container implementations may ignore one or more of these hints.
Returns:
the ComponentAdapter that has been associated with this component. In the majority of cases, this return value can be safely ignored, as one of the getXXX() methods of the PicoContainer interface can be used to retrieve a reference to the component later on.
Throws:
PicoRegistrationException - if registration of the component fails.

registerComponentImplementation

public ComponentAdapter registerComponentImplementation(Object componentKey,
                                                        Class componentImplementation,
                                                        List parameters)
                                                 throws PicoRegistrationException
Throws:
PicoRegistrationException

addOrderedComponentAdapter

public void addOrderedComponentAdapter(ComponentAdapter componentAdapter)
Description copied from interface: PicoContainer
Callback method from the implementation to keep track of the instantiation order. This method is not intended to be called explicitly by clients of the API!

Specified by:
addOrderedComponentAdapter in interface PicoContainer
Parameters:
componentAdapter - the freshly added ComponentAdapter

getComponentInstances

public List getComponentInstances()
                           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:
getComponentInstances in interface PicoContainer
Returns:
all the components.
Throws:
PicoException

getComponentInstancesOfType

public List getComponentInstancesOfType(Class type)
                                 throws PicoException
Throws:
PicoException

getComponentInstance

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

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

getComponentInstanceOfType

public Object getComponentInstanceOfType(Class componentType)
Description copied from interface: PicoContainer
Find a component instance matching the specified type.

Specified by:
getComponentInstanceOfType in interface PicoContainer
Parameters:
componentType - the type of the component.
Returns:
the adapter matching the class.

getParent

public PicoContainer getParent()
Description copied from interface: PicoContainer
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.

setParent

public void setParent(PicoContainer parent)
Description copied from interface: MutablePicoContainer
Set the Parent container.

Specified by:
setParent in interface MutablePicoContainer
Parameters:
parent - parent container.

unregisterComponentByInstance

public ComponentAdapter unregisterComponentByInstance(Object componentInstance)
Description copied from interface: MutablePicoContainer
Unregister a component by instance.

Specified by:
unregisterComponentByInstance in interface MutablePicoContainer
Parameters:
componentInstance - the component instance to unregister.
Returns:
the ComponentAdapter that was associated with this component.

verify

public void verify()
            throws PicoVerificationException
Description copied from interface: PicoContainer
Verify that the dependencies for all the registered components can be satisfied. No components are instantiated during the verification process.

Specified by:
verify in interface PicoContainer
Throws:
PicoVerificationException - if there are unsatisifiable dependencies.

start

public void start()
Description copied from interface: Startable
Start this component. Called initially at the begin of the lifecycle. It can be called again after a stop.

Specified by:
start in interface Startable

stop

public void stop()
Description copied from interface: Startable
Stop this component. Called near the end the lifecycle. It can be called again after a further start. Implement Disposable if you need a single call at the definite end of the lifecycle.

Specified by:
stop in interface Startable

dispose

public void dispose()
Description copied from interface: Disposable
Dispose this component. The component should deallocate all resources. The contract for this method defines a single call at the end of this component's life.

Specified by:
dispose in interface Disposable


Copyright © 2003-2004 Codehaus. All Rights Reserved.