org.picocontainer
Interface MutablePicoContainer

All Superinterfaces:
Disposable, PicoContainer, Startable
All Known Implementing Classes:
AbstractDelegatingMutablePicoContainer, CachingPicoContainer, DefaultPicoContainer, ImplementationHidingCachingPicoContainer, ImplementationHidingPicoContainer

public interface MutablePicoContainer
extends PicoContainer

This is the core interface used for registration of components with a container. It is possible to register an implementation class, an instance or a ComponentAdapter.

Since:
1.0
Version:
$Revision: 3233 $
Author:
Paul Hammant, Aslak Hellesøy, Jon Tirsén
See Also:
See package description for basic overview how to use PicoContainer.

Method Summary
 boolean addChildContainer(PicoContainer child)
          Add a child container.
 MutablePicoContainer makeChildContainer()
          Make a child container, using the same implementation of MutablePicoContainer as the parent.
 ComponentAdapter registerComponent(ComponentAdapter componentAdapter)
          Register a component via a ComponentAdapter.
 ComponentAdapter registerComponentImplementation(java.lang.Class componentImplementation)
          Register a component using the componentImplementation as key.
 ComponentAdapter registerComponentImplementation(java.lang.Object componentKey, java.lang.Class componentImplementation)
          Register a component.
 ComponentAdapter registerComponentImplementation(java.lang.Object componentKey, java.lang.Class componentImplementation, 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.
 ComponentAdapter registerComponentInstance(java.lang.Object componentInstance)
          Register an arbitrary object.
 ComponentAdapter registerComponentInstance(java.lang.Object componentKey, java.lang.Object componentInstance)
          Register an arbitrary object as a component in the container.
 boolean removeChildContainer(PicoContainer child)
          Remove a child container from this container.
 ComponentAdapter unregisterComponent(java.lang.Object componentKey)
          Unregister a component by key.
 ComponentAdapter unregisterComponentByInstance(java.lang.Object componentInstance)
          Unregister a component by instance.
 
Methods inherited from interface org.picocontainer.PicoContainer
accept, getComponentAdapter, getComponentAdapterOfType, getComponentAdapters, getComponentAdaptersOfType, getComponentInstance, getComponentInstanceOfType, getComponentInstances, getComponentInstancesOfType, getParent, verify
 
Methods inherited from interface org.picocontainer.Startable
start, stop
 
Methods inherited from interface org.picocontainer.Disposable
dispose
 

Method Detail

registerComponentImplementation

ComponentAdapter registerComponentImplementation(java.lang.Object componentKey,
                                                 java.lang.Class componentImplementation)
Register a component.

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

ComponentAdapter registerComponentImplementation(java.lang.Object componentKey,
                                                 java.lang.Class componentImplementation,
                                                 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


registerComponentImplementation

ComponentAdapter registerComponentImplementation(java.lang.Class componentImplementation)
Register a component using the componentImplementation as key. Calling this method is equivalent to calling registerComponentImplementation(componentImplementation, componentImplementation).

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.

registerComponentInstance

ComponentAdapter registerComponentInstance(java.lang.Object componentInstance)
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).

Parameters:
componentInstance -
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

ComponentAdapter registerComponentInstance(java.lang.Object componentKey,
                                           java.lang.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.

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.

registerComponent

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.

Parameters:
componentAdapter - the adapter
Returns:
the same adapter that was passed as an argument.
Throws:
PicoRegistrationException - if registration fails.

unregisterComponent

ComponentAdapter unregisterComponent(java.lang.Object componentKey)
Unregister a component by key.

Parameters:
componentKey - key of the component to unregister.
Returns:
the ComponentAdapter that was associated with this component.

unregisterComponentByInstance

ComponentAdapter unregisterComponentByInstance(java.lang.Object componentInstance)
Unregister a component by instance.

Parameters:
componentInstance - the component instance to unregister.
Returns:
the ComponentAdapter that was associated with this component.

makeChildContainer

MutablePicoContainer makeChildContainer()
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.

Returns:
the new child container.
Since:
1.1

addChildContainer

boolean addChildContainer(PicoContainer child)
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.

Parameters:
child - the child container
Returns:
true if the child container was not already in.
Since:
1.1

removeChildContainer

boolean removeChildContainer(PicoContainer child)
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.

Parameters:
child - the child container
Returns:
true if the child container has been removed.
Since:
1.1