org.picocontainer

Interface MutablePicoContainer

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

See Also: See package description for basic overview how to use PicoContainer.

Method Summary
booleanaddChildContainer(PicoContainer child)
Add a child container.
MutablePicoContainermakeChildContainer()
Make a child container, using the same implementation of MutablePicoContainer as the parent.
ComponentAdapterregisterComponent(ComponentAdapter componentAdapter)
Register a component via a ComponentAdapter.
ComponentAdapterregisterComponentImplementation(Object componentKey, Class componentImplementation)
Register a component.
ComponentAdapterregisterComponentImplementation(Object componentKey, 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.
ComponentAdapterregisterComponentImplementation(Class componentImplementation)
Register a component using the componentImplementation as key.
ComponentAdapterregisterComponentInstance(Object componentInstance)
Register an arbitrary object.
ComponentAdapterregisterComponentInstance(Object componentKey, Object componentInstance)
Register an arbitrary object as a component in the container.
booleanremoveChildContainer(PicoContainer child)
Remove a child container from this container.
ComponentAdapterunregisterComponent(Object componentKey)
Unregister a component by key.
ComponentAdapterunregisterComponentByInstance(Object componentInstance)
Unregister a component by instance.

Method Detail

addChildContainer

public 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

makeChildContainer

public 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

registerComponent

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

registerComponentImplementation

public ComponentAdapter registerComponentImplementation(Object componentKey, 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: (Object,Class,Parameter[]) 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)
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

public ComponentAdapter registerComponentImplementation(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

public ComponentAdapter registerComponentInstance(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

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

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.

removeChildContainer

public 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

unregisterComponent

public ComponentAdapter unregisterComponent(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

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

Parameters: componentInstance the component instance to unregister.

Returns: the ComponentAdapter that was associated with this component.