org.codehaus.plexus

Interface PlexusContainer

public interface PlexusContainer

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

Field Summary

Fields

Modifier and Type	Field and Description
static String	ROLE

Method Summary

Modifier and Type	Method and Description
void	addComponent(Object component, String role)
<T> void	addComponent(T component, Class<?> role, String roleHint) Adds live component instance to this container.
void	addComponentDescriptor(ComponentDescriptor<?> componentDescriptor) Adds a component descriptor to this container.
void	addComponentModel(Object componentModel) Adds a component model to this container.
void	addContextValue(Object key, Object value) Add a key/value pair to this container's Context.
ClassRealm	createChildRealm(String id)
List<ComponentDescriptor<?>>	discoverComponents(ClassRealm childRealm) Discovers components in the given realm.
List<ComponentDescriptor<?>>	discoverComponents(ClassRealm realm, Object data)
void	dispose() Disposes of this container, which in turn disposes all of it's components.
<T> ComponentDescriptor<T>	getComponentDescriptor(Class<T> type, String role, String roleHint) Returns the ComponentDescriptor with the given component role and hint.
ComponentDescriptor<?>	getComponentDescriptor(String role) Returns the ComponentDescriptor with the given component role and the default role hint.
ComponentDescriptor<?>	getComponentDescriptor(String role, String roleHint) Returns the ComponentDescriptor with the given component role and hint.
<T> List<ComponentDescriptor<T>>	getComponentDescriptorList(Class<T> type, String role) Returns a List of ComponentDescriptors with the given role.
List<ComponentDescriptor<?>>	getComponentDescriptorList(String role) Returns a List of ComponentDescriptors with the given role.
<T> Map<String,ComponentDescriptor<T>>	getComponentDescriptorMap(Class<T> type, String role) Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
Map<String,ComponentDescriptor<?>>	getComponentDescriptorMap(String role) Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
ClassRealm	getComponentRealm(String realmId)
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.
ClassRealm	getLookupRealm() Returns the lookup realm for this container, which is either the container realm or the realm set by MutablePlexusContainer#setLookupRealm(ClassRealm).
ClassRealm	getLookupRealm(Object component) XXX ideally i'd like to place this in a plexus container specific utility class.
boolean	hasComponent(Class<?> type) Returns true if this container has a component with the given role/role-hint.
boolean	hasComponent(Class<?> type, String roleHint) Returns true if this container has a component with the given role/role-hint.
boolean	hasComponent(Class<?> type, String role, String roleHint) Returns true if this container has a component with the given role/role-hint.
boolean	hasComponent(String role) Returns true if this container has the keyed component.
boolean	hasComponent(String role, String roleHint) Returns true if this container has a component with the given role/role-hint.
<T> T	lookup(Class<T> type) Looks up and returns a component object with the given unique key or role.
<T> T	lookup(Class<T> type, String roleHint) Looks up and returns a component object with the given unique role/role-hint combination.
<T> T	lookup(Class<T> type, String role, String roleHint) Looks up and returns a component object with the given unique role/role-hint combination.
<T> T	lookup(ComponentDescriptor<T> componentDescriptor) Looks up and returns a component object matching the given component descriptor.
Object	lookup(String role) Looks up and returns a component object with the given unique key or role.
Object	lookup(String role, String roleHint) Looks up and returns a component object with the given unique role/role-hint combination.
<T> List<T>	lookupList(Class<T> type) Looks up and returns a List of component objects with the given role.
<T> List<T>	lookupList(Class<T> type, List<String> roleHints) Looks up and returns a List of component objects with the given role.
List<Object>	lookupList(String role) Looks up and returns a List of component objects with the given role.
List<Object>	lookupList(String role, List<String> roleHints) Looks up and returns a List of component objects with the given role.
<T> Map<String,T>	lookupMap(Class<T> type) Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
<T> Map<String,T>	lookupMap(Class<T> type, List<String> roleHints) Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
Map<String,Object>	lookupMap(String role) Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
Map<String,Object>	lookupMap(String role, List<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(Object component) Releases the component from the container.
void	releaseAll(List<?> components) Releases all Listed components from the container.
void	releaseAll(Map<String,?> components) Releases all Mapped component values from the container.
void	removeComponentDiscoveryListener(ComponentDiscoveryListener listener) Removes the listener from this container.
void	removeComponentRealm(ClassRealm componentRealm) Dissociate the realm with the specified id from the container.
ClassRealm	setLookupRealm(ClassRealm realm) Sets the lookup realm to use for lookup calls that don't have a ClassRealm parameter.

Field Detail

ROLE

static final String ROLE

Method Detail

lookup

Object lookup(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

Object lookup(String role,
              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(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(Class<T> type,
             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(Class<T> type,
             String role,
             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

lookup

<T> T lookup(ComponentDescriptor<T> componentDescriptor)
      throws ComponentLookupException

Looks up and returns a component object matching the given component descriptor.

Parameters:

componentDescriptor - the descriptor of the component

Returns:

a Plexus component object

Throws:

ComponentLookupException

lookupList

List<Object> lookupList(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

List<Object> lookupList(String role,
                        List<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> List<T> lookupList(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> List<T> lookupList(Class<T> type,
                       List<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

Map<String,Object> lookupMap(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

Map<String,Object> lookupMap(String role,
                             List<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> Map<String,T> lookupMap(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> Map<String,T> lookupMap(Class<T> type,
                            List<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(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(String role,
                                              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(Class<T> type,
                                                  String role,
                                                  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

Map<String,ComponentDescriptor<?>> getComponentDescriptorMap(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> Map<String,ComponentDescriptor<T>> getComponentDescriptorMap(Class<T> type,
                                                                 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

List<ComponentDescriptor<?>> getComponentDescriptorList(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> List<ComponentDescriptor<T>> getComponentDescriptorList(Class<T> type,
                                                            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 CycleDetectedInComponentGraphException

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

Parameters:

componentDescriptor -

Throws:

ComponentRepositoryException

CycleDetectedInComponentGraphException

addComponentModel

void addComponentModel(Object componentModel)
                throws CycleDetectedInComponentGraphException

Adds a component model to this container.

Parameters:

componentModel -

Throws:

ComponentRepositoryException

CycleDetectedInComponentGraphException

release

void release(Object component)
      throws ComponentLifecycleException

Releases the component from the container. This is dependent 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(Map<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(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(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(String role,
                     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(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(Class<?> type,
                     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(Class<?> type,
                     String role,
                     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(Object key,
                     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

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 different ComponentDiscoveryEvents

removeComponentDiscoveryListener

void removeComponentDiscoveryListener(ComponentDiscoveryListener listener)

Removes the listener from this container.

Parameters:

listener - A listener to remove

discoverComponents

List<ComponentDescriptor<?>> discoverComponents(ClassRealm childRealm)
                                         throws PlexusConfigurationException,
                                                CycleDetectedInComponentGraphException

Discovers components in the given realm.

Parameters:

childRealm -

override - whether to override/merge any conflicting components, where the new component takes precedence.

Returns:

Throws:

PlexusConfigurationException

ComponentRepositoryException

CycleDetectedInComponentGraphException

discoverComponents

List<ComponentDescriptor<?>> discoverComponents(ClassRealm realm,
                                                Object data)
                                         throws PlexusConfigurationException,
                                                CycleDetectedInComponentGraphException

Throws:

PlexusConfigurationException

CycleDetectedInComponentGraphException

createChildRealm

ClassRealm createChildRealm(String id)

getComponentRealm

ClassRealm getComponentRealm(String realmId)

removeComponentRealm

void removeComponentRealm(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

ClassRealm getLookupRealm()

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

setLookupRealm

ClassRealm setLookupRealm(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 advised to set it back once the old-style lookups have completed.

getLookupRealm

ClassRealm getLookupRealm(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(Object component,
                  String role)
           throws CycleDetectedInComponentGraphException

Throws:

CycleDetectedInComponentGraphException

addComponent

<T> void addComponent(T component,
                      Class<?> role,
                      String roleHint)

Adds live component instance to this container. Component instance is not associated with any class realm and will be ignored during lookup is lookup realm is provided using thread context classloader.