Package org.picocontainer

# Interface MutablePicoContainer

All Superinterfaces:
  `Disposable`, `PicoContainer`, `Startable`

All Known Subinterfaces:
  `ClassLoadingPicoContainer`

All Known Implementing Classes:
  `AbstractDelegatingMutablePicoContainer`, `DefaultClassLoadingPicoContainer`, `DefaultPicoContainer`, `TieringPicoContainer`, `TransientPicoContainer`

public interface MutablePicoContainer extends PicoContainer, Startable, Disposable
This is the core interface used for registration of components with a container. It is possible to register implementations and instances here

Author:
  Paul Hammant, Aslak Hellesøy, Jon Tirsén
See Also:
  - See package description for basic overview how to use PicoContainer.

## Method Summary

Modifier and Type
Method
Description
`MutablePicoContainer`
`addAdapter(ComponentAdapter<?> componentAdapter)`
Register a component via a 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.
`LifecycleState`
`getLifecycleState()`
Allow querying of the current lifecycle state of a MutablePicoContainer.
`String`
`getName()`
Retrieve the name set (if any).
`MutablePicoContainer`
`makeChildContainer()`
Make a child container, using both the same implementation of MutablePicoContainer as the parent and identical behaviors as well.
`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 assist debugging or other indexing.

### Methods inherited from interface org.picocontainer.Disposable

`dispose`

### Methods inherited from interface org.picocontainer.PicoContainer

`accept, getComponent, getComponent, getComponent, getComponent, getComponentAdapter, getComponentAdapter, getComponentAdapter, getComponentAdapters, getComponentAdapters, getComponentAdapters, getComponents, getComponents, getParent`

### Methods inherited from interface org.picocontainer.Startable

`start, stop`

## Method Details

### addComponent

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

- Partial Autowiring: If you have two constructor args to match and you only wish to specify one of the constructors and let PicoContainer wire the other one, you can use as parameters: `new ComponentParameter(), new ComponentParameter("someService")` The default constructor for the component parameter indicates auto-wiring should take place for that parameter.
- Force No-Arg constructor usage: If you wish to force a component to be constructed with the no-arg constructor, use a zero length Parameter array. Ex: `new Parameter[0]`

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.
  `componentImplementationOrInstance` - the component's implementation class. This must be a concrete class (ie, a class that can be instantiated). Or an intance of the compoent.
  `parameters` - the 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 same instance of MutablePicoContainer
Throws:
  `PicoCompositionException` - if registration of the component fails.
See Also:
  - `Parameter`
  - `ConstantParameter`
  - `ComponentParameter`

### addComponent

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)`.

Parameters:
  `implOrInstance` - Component implementation or instance
Returns:
  the same instance of MutablePicoContainer
Throws:
  `PicoCompositionException` - if registration fails.

### addConfig

MutablePicoContainer addConfig(String name, Object val)
Register a config item.

Parameters:
  `name` - the name of the config item
  `val` - the value of the config item
Returns:
  the same instance of MutablePicoContainer
Throws:
  `PicoCompositionException` - if registration fails.

### addAdapter

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

Parameters:
  `componentAdapter` - the adapter
Returns:
  the same instance of MutablePicoContainer
Throws:
  `PicoCompositionException` - if registration fails.

### removeComponent

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

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

### removeComponentByInstance

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

Parameters:
  `componentInstance` - the component instance to unregister.
Returns:
  the same instance of MutablePicoContainer

### makeChildContainer

MutablePicoContainer makeChildContainer()
Make a child container, using both the same implementation of MutablePicoContainer as the parent and identical behaviors as well. 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.

Note that for long-lived parent containers, you need to unregister child containers made with this call before disposing or you will leak memory. (Experience speaking here! )

Incorrect Example:

       MutablePicoContainer parent = new PicoBuilder().withCaching().withLifecycle().build();
       MutablePicoContainer child = parent.makeChildContainer();
       child = null; //Child still retains in memory because parent still holds reference.

Correct Example:

       MutablePicoContainer parent = new PicoBuilder().withCaching().withLifecycle().build();
       MutablePicoContainer child = parent.makeChildContainer();
       parent.removeChildContainer(child); //Remove the bi-directional references.
       child = null;

Returns:
  the new child container.

### addChildContainer

MutablePicoContainer 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:
  the same instance of MutablePicoContainer

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

### change

MutablePicoContainer change(Properties... properties)
You can change the characteristic of registration of all subsequent components in this container.

Parameters:
  `properties` -
Returns:
  the same Pico instance with changed properties

### as

MutablePicoContainer as(Properties... properties)
You can set for the following operation only the characteristic of registration of a component on the fly.

Parameters:
  `properties` -
Returns:
  the same Pico instance with temporary properties

### setName

void setName(String name)
Name the container instance, to assist debugging or other indexing.

Parameters:
  `name` - the name to call it.
Since:
  2.8

### setLifecycleState

void setLifecycleState(LifecycleState lifecycleState)
To assist ThreadLocal usage, LifecycleState can be set. No need to use this for normal usages.

Parameters:
  `lifecycleState` - the lifecyle state to use.
Since:
  2.8

### getName

String getName()
Retrieve the name set (if any).

Returns:
  Retrieve the arbitrary name of the container set by calling `setName`.
Since:
  2.10.2

### getLifecycleState

LifecycleState getLifecycleState()
Allow querying of the current lifecycle state of a MutablePicoContainer.

Returns:
  the current Lifecycle State.
Since:
  2.10.2