org.codehaus.plexus

## Interface PlexusContainer

All Known Subinterfaces:
  MutablePlexusContainer

All Known Implementing Classes:
  DefaultPlexusContainer

    public interface PlexusContainer

PlexusContainer is the entry-point for loading and accessing other components.

### Field Summary

Fields
`static java.lang.String` `ROLE`

### Method Summary

Methods
`void` `addComponent(java.lang.Object component, java.lang.String role)`
`void` `addComponentDescriptor(ComponentDescriptor<?> componentDescriptor)` Adds a component descriptor to this container.
`void` `addContextValue(java.lang.Object key, java.lang.Object value)` Add a key/value pair to this container's Context.
`org.codehaus.plexus.classworlds.realm.ClassRealm` `createChildRealm(java.lang.String id)`
`java.util.List<ComponentDescriptor<?>>` `discoverComponents(org.codehaus.plexus.classworlds.realm.ClassRealm childRealm)` Discovers components in the given realm.
`void` `dispose()` Disposes of this container, which in turn disposes all of it's components.
`<T> ComponentDescriptor<T>` `getComponentDescriptor(java.lang.Class<T> type, java.lang.String role, java.lang.String roleHint)` Returns the ComponentDescriptor with the given component role and hint.
`ComponentDescriptor<?>` `getComponentDescriptor(java.lang.String role)` Returns the ComponentDescriptor with the given component role and the default role hint.
`ComponentDescriptor<?>` `getComponentDescriptor(java.lang.String role, java.lang.String roleHint)` Returns the ComponentDescriptor with the given component role and hint.
`<T> java.util.List<ComponentDescriptor<T>>` `getComponentDescriptorList(java.lang.Class<T> type, java.lang.String role)` Returns a List of ComponentDescriptors with the given role.
`java.util.List<ComponentDescriptor<?>>` `getComponentDescriptorList(java.lang.String role)` Returns a List of ComponentDescriptors with the given role.
`<T> java.util.Map<java.lang.String,ComponentDescriptor<T>>` `getComponentDescriptorMap(java.lang.Class<T> type, java.lang.String role)` Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
`java.util.Map<java.lang.String,ComponentDescriptor<?>>` `getComponentDescriptorMap(java.lang.String role)` Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
`org.codehaus.plexus.classworlds.realm.ClassRealm` `getComponentRealm(java.lang.String realmId)`
`org.codehaus.plexus.classworlds.realm.ClassRealm` `getContainerRealm()` Returns the Classworld's ClassRealm of this Container, which acts as the default parent for all contained components.
`Context` `getContext()` Returns this container's context.
`org.codehaus.plexus.classworlds.realm.ClassRealm` `getLookupRealm()` Returns the lookup realm for this container, which is either the container realm or the realm set by `setLookupRealm(ClassRealm)`.
`org.codehaus.plexus.classworlds.realm.ClassRealm` `getLookupRealm(java.lang.Object component)` XXX ideally i'd like to place this in a plexus container specific utility class.
`boolean` `hasComponent(java.lang.Class<?> type)` Returns true if this container has a component with the given role/role-hint.
`boolean` `hasComponent(java.lang.Class<?> type, java.lang.String roleHint)` Returns true if this container has a component with the given role/role-hint.
`boolean` `hasComponent(java.lang.Class<?> type, java.lang.String role, java.lang.String roleHint)` Returns true if this container has a component with the given role/role-hint.
`boolean` `hasComponent(java.lang.String role)` Returns true if this container has the keyed component.
`boolean` `hasComponent(java.lang.String role, java.lang.String roleHint)` Returns true if this container has a component with the given role/role-hint.
`<T> T` `lookup(java.lang.Class<T> type)` Looks up and returns a component object with the given unique key or role.
`<T> T` `lookup(java.lang.Class<T> type, java.lang.String roleHint)` Looks up and returns a component object with the given unique role/role-hint combination.
`<T> T` `lookup(java.lang.Class<T> type, java.lang.String role, java.lang.String roleHint)` Looks up and returns a component object with the given unique role/role-hint combination.
`java.lang.Object` `lookup(java.lang.String role)` Looks up and returns a component object with the given unique key or role.
`java.lang.Object` `lookup(java.lang.String role, java.lang.String roleHint)` Looks up and returns a component object with the given unique role/role-hint combination.
`<T> java.util.List<T>` `lookupList(java.lang.Class<T> type)` Looks up and returns a List of component objects with the given role.
`<T> java.util.List<T>` `lookupList(java.lang.Class<T> type, java.util.List<java.lang.String> roleHints)` Looks up and returns a List of component objects with the given role.
`java.util.List<java.lang.Object>` `lookupList(java.lang.String role)` Looks up and returns a List of component objects with the given role.
`java.util.List<java.lang.Object>` `lookupList(java.lang.String role, java.util.List<java.lang.String> roleHints)` Looks up and returns a List of component objects with the given role.
`<T> java.util.Map<java.lang.String,T>` `lookupMap(java.lang.Class<T> type)` Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
`<T> java.util.Map<java.lang.String,T>` `lookupMap(java.lang.Class<T> type, java.util.List<java.lang.String> roleHints)` Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
`java.util.Map<java.lang.String,java.lang.Object>` `lookupMap(java.lang.String role)` Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
`java.util.Map<java.lang.String,java.lang.Object>` `lookupMap(java.lang.String role, java.util.List<java.lang.String> roleHints)` Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
`void` `registerComponentDiscoveryListener(ComponentDiscoveryListener listener)` Adds the listener to this container.
`void` `release(java.lang.Object component)` Releases the component from the container.
`void` `releaseAll(java.util.List<?> components)` Releases all Listed components from the container.
`void` `releaseAll(java.util.Map<java.lang.String,?> components)` Releases all Mapped component values from the container.
`void` `removeComponentDiscoveryListener(ComponentDiscoveryListener listener)` Removes the listener from this container.
`void` `removeComponentRealm(org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm)` Dissociate the realm with the specified id from the container.
`org.codehaus.plexus.classworlds.realm.ClassRealm` `setLookupRealm(org.codehaus.plexus.classworlds.realm.ClassRealm realm)` Sets the lookup realm to use for lookup calls that don't have a ClassRealm parameter.

### Field Detail

#### ROLE

    static final java.lang.String ROLE

### Method Detail

#### lookup

    java.lang.Object lookup(java.lang.String role)
                            throws ComponentLookupException

Looks up and returns a component object with the given unique key or role.

Parameters:
  `role` - a unique key for the desired component
Returns:
  a Plexus component object
Throws:
  `ComponentLookupException`

#### lookup

    java.lang.Object lookup(java.lang.String role,
                          java.lang.String roleHint)
                            throws ComponentLookupException

Looks up and returns a component object with the given unique role/role-hint combination.

Parameters:
  `role` - a non-unique key for the desired component
  `roleHint` - a hint for the desired component implementation
Returns:
  a Plexus component object
Throws:
  `ComponentLookupException`

#### lookup

    <T> T lookup(java.lang.Class<T> type)
             throws ComponentLookupException

Looks up and returns a component object with the given unique key or role.

Parameters:
  `type` - the unique type of the component within the container
Returns:
  a Plexus component object
Throws:
  `ComponentLookupException`

#### lookup

    <T> T lookup(java.lang.Class<T> type,
               java.lang.String roleHint)
             throws ComponentLookupException

Looks up and returns a component object with the given unique role/role-hint combination.

Parameters:
  `type` - the non-unique type of the component
  `roleHint` - a hint for the desired component implementation
Returns:
  a Plexus component object
Throws:
  `ComponentLookupException`

#### lookup

    <T> T lookup(java.lang.Class<T> type,
               java.lang.String role,
               java.lang.String roleHint)
             throws ComponentLookupException

Looks up and returns a component object with the given unique role/role-hint combination.

Parameters:
  `type` - the non-unique type of the component
  `role` - a non-unique key for the desired component
  `roleHint` - a hint for the desired component implementation
Returns:
  a Plexus component object
Throws:
  `ComponentLookupException`

#### lookupList

    java.util.List<java.lang.Object> lookupList(java.lang.String role)
                                                throws ComponentLookupException

Looks up and returns a List of component objects with the given role.

Parameters:
  `role` - a non-unique key for the desired components
Returns:
  a List of component objects
Throws:
  `ComponentLookupException`

#### lookupList

    java.util.List<java.lang.Object> lookupList(java.lang.String role,
                                              java.util.List<java.lang.String> roleHints)
                                                throws ComponentLookupException

Looks up and returns a List of component objects with the given role.

Parameters:
  `role` - a non-unique key for the desired components
Returns:
  a List of component objects
Throws:
  `ComponentLookupException`

#### lookupList

    <T> java.util.List<T> lookupList(java.lang.Class<T> type)
                                 throws ComponentLookupException

Looks up and returns a List of component objects with the given role.

Parameters:
  `type` - the non-unique type of the components
Returns:
  a List of component objects
Throws:
  `ComponentLookupException`

#### lookupList

    <T> java.util.List<T> lookupList(java.lang.Class<T> type,
                                   java.util.List<java.lang.String> roleHints)
                                 throws ComponentLookupException

Looks up and returns a List of component objects with the given role.

Parameters:
  `type` - the non-unique type of the components
Returns:
  a List of component objects
Throws:
  `ComponentLookupException`

#### lookupMap

    java.util.Map<java.lang.String,java.lang.Object> lookupMap(java.lang.String role)
                                                               throws ComponentLookupException

Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.

Parameters:
  `role` - a non-unique key for the desired components
Returns:
  a Map of component objects
Throws:
  `ComponentLookupException`

#### lookupMap

    java.util.Map<java.lang.String,java.lang.Object> lookupMap(java.lang.String role,
                                                             java.util.List<java.lang.String> roleHints)
                                                               throws ComponentLookupException

Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.

Parameters:
  `role` - a non-unique key for the desired components
Returns:
  a Map of component objects
Throws:
  `ComponentLookupException`

#### lookupMap

    <T> java.util.Map<java.lang.String,T> lookupMap(java.lang.Class<T> type)
                                                throws ComponentLookupException

Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.

Parameters:
  `type` - the non-unique type of the components
Returns:
  a Map of component objects
Throws:
  `ComponentLookupException`

#### lookupMap

    <T> java.util.Map<java.lang.String,T> lookupMap(java.lang.Class<T> type,
                                                  java.util.List<java.lang.String> roleHints)
                                                throws ComponentLookupException

Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.

Parameters:
  `type` - the non-unique type of the components
Returns:
  a Map of component objects
Throws:
  `ComponentLookupException`

#### getComponentDescriptor

    ComponentDescriptor<?> getComponentDescriptor(java.lang.String role)

Returns the ComponentDescriptor with the given component role and the default role hint. Searches up the hierarchy until one is found, null if none is found.

Parameters:
  `role` - a unique role for the desired component's descriptor
Returns:
  the ComponentDescriptor with the given component role

#### getComponentDescriptor

    ComponentDescriptor<?> getComponentDescriptor(java.lang.String role,
                                                java.lang.String roleHint)

Returns the ComponentDescriptor with the given component role and hint. Searches up the hierarchy until one is found, null if none is found.

Parameters:
  `role` - a unique role for the desired component's descriptor
  `roleHint` - a hint showing which implementation should be used
Returns:
  the ComponentDescriptor with the given component role

#### getComponentDescriptor

    <T> ComponentDescriptor<T> getComponentDescriptor(java.lang.Class<T> type,
                                                    java.lang.String role,
                                                    java.lang.String roleHint)

Returns the ComponentDescriptor with the given component role and hint. Searches up the hierarchy until one is found, null if none is found.

Parameters:
  `type` - the Java type of the desired component
  `role` - a unique role for the desired component's descriptor
  `roleHint` - a hint showing which implementation should be used
Returns:
  the ComponentDescriptor with the given component role

#### getComponentDescriptorMap

    java.util.Map<java.lang.String,ComponentDescriptor<?>> getComponentDescriptorMap(java.lang.String role)

Returns a Map of ComponentDescriptors with the given role, keyed by role-hint. Searches up the hierarchy until all are found, an empty Map if none are found.

Parameters:
  `role` - a non-unique key for the desired components
Returns:
  a Map of component descriptors keyed by role-hint

#### getComponentDescriptorMap

    <T> java.util.Map<java.lang.String,ComponentDescriptor<T>> getComponentDescriptorMap(java.lang.Class<T> type,
                                                                                       java.lang.String role)

Returns a Map of ComponentDescriptors with the given role, keyed by role-hint. Searches up the hierarchy until all are found, an empty Map if none are found.

Parameters:
  `type` - the Java type of the desired components
  `role` - a non-unique key for the desired components
Returns:
  a Map of component descriptors keyed by role-hint

#### getComponentDescriptorList

    java.util.List<ComponentDescriptor<?>> getComponentDescriptorList(java.lang.String role)

Returns a List of ComponentDescriptors with the given role. Searches up the hierarchy until all are found, an empty List if none are found.

Parameters:
  `role` - a non-unique key for the desired components
Returns:
  a List of component descriptors

#### getComponentDescriptorList

    <T> java.util.List<ComponentDescriptor<T>> getComponentDescriptorList(java.lang.Class<T> type,
                                                                        java.lang.String role)

Returns a List of ComponentDescriptors with the given role. Searches up the hierarchy until all are found, an empty List if none are found.

Parameters:
  `type` - the Java type of the desired components
  `role` - a non-unique key for the desired components
Returns:
  a List of component descriptors

#### addComponentDescriptor

    void addComponentDescriptor(ComponentDescriptor<?> componentDescriptor)
                                throws ComponentRepositoryException

Adds a component descriptor to this container. componentDescriptor should have realmId set.

Parameters:
  `componentDescriptor` -
Throws:
  `ComponentRepositoryException`

#### release

    void release(java.lang.Object component)
                 throws ComponentLifecycleException

Releases the component from the container. This is dependant upon how the implementation manages the component, but usually enacts some standard lifecycle shutdown procedure on the component. In every case, the component is no longer accessible from the container (unless another is created).

Parameters:
  `component` - the plexus component object to release
Throws:
  `ComponentLifecycleException`

#### releaseAll

    void releaseAll(java.util.Map<java.lang.String,?> components)
                    throws ComponentLifecycleException

Releases all Mapped component values from the container.

Parameters:
  `components` - Map of plexus component objects to release
Throws:
  `ComponentLifecycleException`
See Also:
  `release( Object component )`

#### releaseAll

    void releaseAll(java.util.List<?> components)
                    throws ComponentLifecycleException

Releases all Listed components from the container.

Parameters:
  `components` - List of plexus component objects to release
Throws:
  `ComponentLifecycleException`
See Also:
  `release( Object component )`

#### hasComponent

    boolean hasComponent(java.lang.String role)

Returns true if this container has the keyed component.

Parameters:
  `role` - a non-unique key for the desired component
Returns:
  true if this container has the keyed component

#### hasComponent

    boolean hasComponent(java.lang.String role,
                       java.lang.String roleHint)

Returns true if this container has a component with the given role/role-hint.

Parameters:
  `role` - a non-unique key for the desired component
  `roleHint` - a hint for the desired component implementation
Returns:
  true if this container has a component with the given role/role-hint

#### hasComponent

    boolean hasComponent(java.lang.Class<?> type)

Returns true if this container has a component with the given role/role-hint.

Parameters:
  `type` - the non-unique type of the component
Returns:
  true if this container has a component with the given role/role-hint

#### hasComponent

    boolean hasComponent(java.lang.Class<?> type,
                       java.lang.String roleHint)

Returns true if this container has a component with the given role/role-hint.

Parameters:
  `type` - the non-unique type of the component
  `roleHint` - a hint for the desired component implementation
Returns:
  true if this container has a component with the given role/role-hint

#### hasComponent

    boolean hasComponent(java.lang.Class<?> type,
                       java.lang.String role,
                       java.lang.String roleHint)

Returns true if this container has a component with the given role/role-hint.

Parameters:
  `type` - the non-unique type of the component
  `role` - a non-unique key for the desired component
  `roleHint` - a hint for the desired component implementation
Returns:
  true if this container has a component with the given role/role-hint

#### dispose

    void dispose()

Disposes of this container, which in turn disposes all of it's components. This container should also remove itself from the container hierarchy.

#### addContextValue

    void addContextValue(java.lang.Object key,
                       java.lang.Object value)

Add a key/value pair to this container's Context.

Parameters:
  `key` - any unique object valid to the Context's implementation
  `value` - any object valid to the Context's implementation

#### getContext

    Context getContext()

Returns this container's context. A Context is a simple data store used to hold values which may alter the execution of the Container.

Returns:
  this container's context.

#### getContainerRealm

    org.codehaus.plexus.classworlds.realm.ClassRealm getContainerRealm()

Returns the Classworld's ClassRealm of this Container, which acts as the default parent for all contained components.

Returns:
  the ClassRealm of this Container

#### registerComponentDiscoveryListener

    void registerComponentDiscoveryListener(ComponentDiscoveryListener listener)

Adds the listener to this container. ComponentDiscoveryListeners have the ability to respond to various ComponentDiscoverer events.

Parameters:
  `listener` - A listener which responds to differnet ComponentDiscoveryEvents

#### removeComponentDiscoveryListener

    void removeComponentDiscoveryListener(ComponentDiscoveryListener listener)

Removes the listener from this container.

Parameters:
  `listener` - A listener to remove

#### discoverComponents

    java.util.List<ComponentDescriptor<?>> discoverComponents(org.codehaus.plexus.classworlds.realm.ClassRealm childRealm)
                                                              throws PlexusConfigurationException,
                                                                     ComponentRepositoryException

Discovers components in the given realm.

Parameters:
  `childRealm` -
  `override` - wheter to override/merge any conflicting components, where the new component takes precedence.
Returns:
Throws:
  `PlexusConfigurationException`
  `ComponentRepositoryException`

#### createChildRealm

    org.codehaus.plexus.classworlds.realm.ClassRealm createChildRealm(java.lang.String id)

#### getComponentRealm

    org.codehaus.plexus.classworlds.realm.ClassRealm getComponentRealm(java.lang.String realmId)

#### removeComponentRealm

    void removeComponentRealm(org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm)
                              throws PlexusContainerException

Dissociate the realm with the specified id from the container. This will remove all components contained in the realm from the component repository.

Parameters:
  `componentRealm` - Realm to remove from the container.
Throws:
  `PlexusContainerException`

#### getLookupRealm

    org.codehaus.plexus.classworlds.realm.ClassRealm getLookupRealm()

Returns the lookup realm for this container, which is either the container realm or the realm set by `setLookupRealm(ClassRealm)`.

#### setLookupRealm

    org.codehaus.plexus.classworlds.realm.ClassRealm setLookupRealm(org.codehaus.plexus.classworlds.realm.ClassRealm realm)

Sets the lookup realm to use for lookup calls that don't have a ClassRealm parameter.

Parameters:
  `realm` - the new realm to use.
Returns:
  The previous lookup realm. It is adviced to set it back once the old-style lookups have completed.

#### getLookupRealm

    org.codehaus.plexus.classworlds.realm.ClassRealm getLookupRealm(java.lang.Object component)

XXX ideally i'd like to place this in a plexus container specific utility class. Utility method to retrieve the lookup realm for a component instance. If the component's classloader is a ClassRealm, that realm is returned, otherwise the result of getLookupRealm is returned.

Parameters:
  `component` -
Returns:

#### addComponent

    void addComponent(java.lang.Object component,
                    java.lang.String role)
                      throws ComponentRepositoryException

Throws:
  `ComponentRepositoryException`