org.picocontainer
Interface PicoContainer

All Known Subinterfaces:
MutablePicoContainer
All Known Implementing Classes:
DefaultLifecyclePicoContainer, DefaultPicoContainer

public interface PicoContainer

This is the core interface for PicoContainer. It only has accessor methods. In order to register components in a PicoContainer, use a MutablePicoContainer, such as DefaultPicoContainer.

Version:
$Revision: 1.19 $
Author:
Paul Hammant, Aslak Hellesøy, Jon Tirsén

Method Summary
 ComponentAdapter findComponentAdapter(Object componentKey)
          Finds a ComponentAdapter matching the key.
 Collection getChildContainers()
          Get the child containers of this container.
 Object getComponentInstance(Object componentKey)
          Gets a component instance.
 List getComponentInstances()
          Gets all the registered component instances in the container.
 Collection getComponentKeys()
          Get all the component keys.
 Object getComponentMulticaster()
          Shorthand for getComponentMulticaster(boolean, boolean)
 Object getComponentMulticaster(boolean callInInstantiationOrder, boolean callUnmanagedComponents)
          Returns an object (in fact, a dynamic proxy) that implements the union of all the interfaces of the currently registered components.
 List getParentContainers()
          Get the parent containers of this container.
 boolean hasComponent(Object componentKey)
          Checks for the presence of a particular component.
 

Method Detail

getComponentInstance

public Object getComponentInstance(Object componentKey)
                            throws PicoException
Gets a component instance.

Parameters:
componentKey - key the component was registered with.
Returns:
an instantiated component.
Throws:
PicoException - if the component could not be instantiated or dependencies could not be properly resolved.

getComponentInstances

public List getComponentInstances()
                           throws PicoException
Gets all the registered component instances in the container. The components are returned in their order of instantiation, which depends on the dependency order between components.

Returns:
all the components.
Throws:
PicoException - if one of the components could not be instantiated or dependencies could not be properly resolved.

hasComponent

public boolean hasComponent(Object componentKey)
Checks for the presence of a particular component.

Parameters:
componentKey - key of the component to look for.
Returns:
true if there is a component for this key.

getComponentMulticaster

public Object getComponentMulticaster(boolean callInInstantiationOrder,
                                      boolean callUnmanagedComponents)
                               throws PicoException
Returns an object (in fact, a dynamic proxy) that implements the union of all the interfaces of the currently registered components.

Casting this object to any of those interfaces and then calling a method on it will result in that call being multicast to all the components implementing that given interface.

This is a simple yet extremely powerful way to handle lifecycle of components. Component writers can invent their own lifecycle interfaces, and then use the multicaster to invoke the method in one go.

Parameters:
callInInstantiationOrder - whether or not to call the method in the order of instantiation, which depends on the components' inter-dependencies.
callUnmanagedComponents - whether or not to multicast to components that are not managed by this container.
Returns:
a multicaster object.
Throws:
PicoException

getComponentMulticaster

public Object getComponentMulticaster()
                               throws PicoException
Shorthand for getComponentMulticaster(boolean, boolean)
(true, false)
, which is the most common usage scenario.

Returns:
a multicaster object.
Throws:
PicoException

getComponentKeys

public Collection getComponentKeys()
Get all the component keys.

Returns:
all the component keys.

getChildContainers

public Collection getChildContainers()
Get the child containers of this container. Any given container instance should not use the child containers to resolve components, but rahter their parents. This method is available merely to be able to traverse trees of containers, and is not used by the container itself.

Returns:
a Collection of PicoContainer.
See Also:
getParentContainers()

getParentContainers

public List getParentContainers()
Get the parent containers of this container. In a purely hierarchical (tree structure) container, there will be 0..1 parents. However, it is possible to have several parents. A container will look in its parents if a component can be found in self.

Returns:
a Collection of PicoContainer.

findComponentAdapter

public ComponentAdapter findComponentAdapter(Object componentKey)
                                      throws PicoIntrospectionException
Finds a ComponentAdapter matching the key. This method is an "expert" method, and should normally not be called by clients of this API. (It is called by the implementation).

Parameters:
componentKey - key of the component.
Throws:
PicoIntrospectionException


Copyright © 2003 Codehaus. All Rights Reserved.