org.codehaus.plexus

Interface PlexusContainer

public interface PlexusContainer

The core component of Plexus. This is the entry-point for loading and accessing other components, as well as an element in a hierarchy of containers. A Plexus Container can also itself be a component, however, the hierarchy must be bootstrapped by a PlexusContainer implementation.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ROLE

Method Summary

Modifier and Type	Method and Description
void	addComponentDescriptor(ComponentDescriptor componentDescriptor) Adds a component descriptor to this container.
void	addContextValue(Object key, Object value) Add a key/value pair to this container's Context.
void	addJarRepository(File repository) Adds a directory of jar resources.
void	addJarResource(File resource) Adds a jar to this container's ClassRealm - whose components are then discovered (via the various registered ComponentDiscoverer's).
Object	autowire(Object component) Assembles a component and returns it.
Object	createAndAutowire(String clazz) Creates a corrosponding component instance found in this container's classrealm, then autowires it.
PlexusContainer	createChildContainer(String name, List classpathJars, Map context)
PlexusContainer	createChildContainer(String name, List classpathJars, Map context, List discoveryListeners)
org.codehaus.plexus.classworlds.realm.ClassRealm	createComponentRealm(String id, List jars) Creates and returns a new class realm under this container's realm for the given list of jars.
void	dispose() Disposes of this container, which in turn disposes all of it's components.
PlexusContainer	getChildContainer(String name) Returns a child container with the unique name.
ComponentDescriptor	getComponentDescriptor(String role) Returns the ComponentDescriptor with the given component role and the default role hint.
ComponentDescriptor	getComponentDescriptor(String role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) 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.
ComponentDescriptor	getComponentDescriptor(String role, String roleHint, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Returns the ComponentDescriptor with the given component role and hint.
List	getComponentDescriptorList(String role) Returns a List of ComponentDescriptors with the given role.
List	getComponentDescriptorList(String role, org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm) Returns a List of ComponentDescriptors with the given role.
Map	getComponentDescriptorMap(String role) Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
Map	getComponentDescriptorMap(String role, org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm) Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
org.codehaus.plexus.classworlds.realm.ClassRealm	getComponentRealm(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.
Date	getCreationDate() Returns the date this container was created.
Logger	getLogger() Deprecated.
LoggerManager	getLoggerManager()
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 MutablePlexusContainer#setLookupRealm(ClassRealm).
org.codehaus.plexus.classworlds.realm.ClassRealm	getLookupRealm(Object component) XXX ideally i'd like to place this in a plexus container specific utility class.
String	getName() Returns the unique name of this container in the container hierarchy.
boolean	hasChildContainer(String name) Returns true if this container has a child with the given name.
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.
boolean	isReloadingEnabled() Returns true if a component's metadata may be reloaded, otherwise, it may be loaded only once.
Object	lookup(Class componentClass) Looks up and returns a component object with the given unique key or role.
Object	lookup(Class componentClass, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a component object with the given unique key or role.
Object	lookup(Class role, String roleHint) Looks up and returns a component object with the given unique role/role-hint combination.
Object	lookup(Class role, String roleHint, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a component object with the given unique role/role-hint combination.
Object	lookup(String componentKey) Looks up and returns a component object with the given unique key or role.
Object	lookup(String componentKey, org.codehaus.plexus.classworlds.realm.ClassRealm realm) 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.
Object	lookup(String role, String roleHint, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a component object with the given unique role/role-hint combination.
List	lookupList(Class role) Looks up and returns a List of component objects with the given role.
List	lookupList(Class role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a List of component objects with the given role.
List	lookupList(String role) Looks up and returns a List of component objects with the given role.
List	lookupList(String role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a List of component objects with the given role.
Map	lookupMap(Class role) Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
Map	lookupMap(Class role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
Map	lookupMap(String role) Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
Map	lookupMap(String role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) 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 components) Releases all Mapped component values from the container.
void	removeChildContainer(String name) Removes the keyed child from this container.
void	removeComponentDiscoveryListener(ComponentDiscoveryListener listener) Removes the listener from this container.
void	resume(Object component) Attempts to resume execution of the component.
void	setLoggerManager(LoggerManager loggerManager)
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.
void	setName(String name)
void	setParentPlexusContainer(PlexusContainer container) Sets the parent of this container.
void	setReloadingEnabled(boolean reloadingEnabled) Sets the ability to reload a component's metadata multiple times.
void	suspend(Object component) Attempts to suspend execution of the component.

Field Detail

ROLE

static final String ROLE

Method Detail

getName

String getName()

Returns the unique name of this container in the container hierarchy.

Returns:

the unique name of this container in the container hierarchy

getCreationDate

Date getCreationDate()

Returns the date this container was created.

Returns:

the date this container was created

hasChildContainer

boolean hasChildContainer(String name)

Returns true if this container has a child with the given name.

Parameters:

name - a key unique amongst this container's children

Returns:

true if this container has a child with the given name

removeChildContainer

void removeChildContainer(String name)

Removes the keyed child from this container. Does not necessarily dispose the children.

Parameters:

name - a key unique amongst this container's children

getChildContainer

PlexusContainer getChildContainer(String name)

Returns a child container with the unique name.

Parameters:

name - a key unique amongst this container's children

Returns:

the keyed child container

lookup

Object lookup(String componentKey)
       throws ComponentLookupException

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

Parameters:

componentKey - a unique key for the desired component

Returns:

a Plexus component object

Throws:

ComponentLookupException

lookup

Object lookup(String componentKey,
              org.codehaus.plexus.classworlds.realm.ClassRealm realm)
       throws ComponentLookupException

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

Parameters:

componentKey - 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

Object lookup(String role,
              String roleHint,
              org.codehaus.plexus.classworlds.realm.ClassRealm realm)
       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

Object lookup(Class componentClass)
       throws ComponentLookupException

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

Parameters:

componentClass - a unique key for the desired component

Returns:

a Plexus component object

Throws:

ComponentLookupException

lookup

Object lookup(Class componentClass,
              org.codehaus.plexus.classworlds.realm.ClassRealm realm)
       throws ComponentLookupException

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

Parameters:

componentClass - a unique key for the desired component

Returns:

a Plexus component object

Throws:

ComponentLookupException

lookup

Object lookup(Class 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 class key for the desired component

roleHint - a hint for the desired component implementation

Returns:

a Plexus component object

Throws:

ComponentLookupException

lookup

Object lookup(Class role,
              String roleHint,
              org.codehaus.plexus.classworlds.realm.ClassRealm realm)
       throws ComponentLookupException

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

Parameters:

role - a non-unique class key for the desired component

roleHint - a hint for the desired component implementation

Returns:

a Plexus component object

Throws:

ComponentLookupException

lookupList

List 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 lookupList(String role,
                org.codehaus.plexus.classworlds.realm.ClassRealm realm)
         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 lookupList(Class role)
         throws ComponentLookupException

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

Parameters:

role - a non-unique class key for the desired components

Returns:

a List of component objects

Throws:

ComponentLookupException

lookupList

List lookupList(Class role,
                org.codehaus.plexus.classworlds.realm.ClassRealm realm)
         throws ComponentLookupException

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

Parameters:

role - a non-unique class key for the desired components

Returns:

a List of component objects

Throws:

ComponentLookupException

lookupMap

Map 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 lookupMap(String role,
              org.codehaus.plexus.classworlds.realm.ClassRealm realm)
       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 lookupMap(Class 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 class key for the desired components

Returns:

a Map of component objects

Throws:

ComponentLookupException

lookupMap

Map lookupMap(Class role,
              org.codehaus.plexus.classworlds.realm.ClassRealm realm)
       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 class key for the desired 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

ComponentDescriptor getComponentDescriptor(String role,
                                           org.codehaus.plexus.classworlds.realm.ClassRealm realm)

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

realm - The class realm to search

Returns:

the ComponentDescriptor with the given component role

getComponentDescriptor

ComponentDescriptor getComponentDescriptor(String role,
                                           String roleHint,
                                           org.codehaus.plexus.classworlds.realm.ClassRealm realm)

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

realm - The class realm to search

Returns:

the ComponentDescriptor with the given component role

getComponentDescriptorMap

Map 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

Map getComponentDescriptorMap(String role,
                              org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm)

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

getComponentDescriptorList

List 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

List getComponentDescriptorList(String role,
                                org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm)

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

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(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(Map 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 -

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 -

roleHint -

Returns:

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

suspend

void suspend(Object component)
      throws ComponentLifecycleException

Attempts to suspend execution of the component.

Parameters:

component - a plexus component

Throws:

ComponentLifecycleException

resume

void resume(Object component)
     throws ComponentLifecycleException

Attempts to resume execution of the component.

Parameters:

component - a plexus component

Throws:

ComponentLifecycleException

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

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

addJarRepository

void addJarRepository(File repository)

Adds a directory of jar resources.

Parameters:

repository - a directory containing JAR files

See Also:

addJarResource(File)

addJarResource

void addJarResource(File resource)
             throws PlexusContainerException

Adds a jar to this container's ClassRealm - whose components are then discovered (via the various registered ComponentDiscoverer's).

Parameters:

resource - a JAR file

Throws:

PlexusContainerException

autowire

Object autowire(Object component)
         throws CompositionException

Assembles a component and returns it. May bypass the normal component assembly hooks (such as creation of a ComponentDescriptor).

Parameters:

component - a valid Plexus component

Returns:

a componsed (dependency-injected) component

Throws:

CompositionException

createAndAutowire

Object createAndAutowire(String clazz)
                  throws CompositionException,
                         ClassNotFoundException,
                         InstantiationException,
                         IllegalAccessException

Creates a corrosponding component instance found in this container's classrealm, then autowires it.

Parameters:

clazz - A class available in this container's ClassRealm

Returns:

A newly created and autowired component

Throws:

CompositionException

ClassNotFoundException

InstantiationException

IllegalAccessException

See Also:

autowire(Object)

setReloadingEnabled

void setReloadingEnabled(boolean reloadingEnabled)

Sets the ability to reload a component's metadata multiple times.

Parameters:

reloadingEnabled - true is a component may be reloaded

isReloadingEnabled

boolean isReloadingEnabled()

Returns true if a component's metadata may be reloaded, otherwise, it may be loaded only once.

Returns:

true if a component's metadata may be reloaded

setLoggerManager

void setLoggerManager(LoggerManager loggerManager)

getLoggerManager

LoggerManager getLoggerManager()

getLogger

Logger getLogger()

Deprecated.

setName

void setName(String name)

setParentPlexusContainer

void setParentPlexusContainer(PlexusContainer container)

Sets the parent of this container.

Parameters:

container - the parent of this container, null if none

createChildContainer

PlexusContainer createChildContainer(String name,
                                     List classpathJars,
                                     Map context)
                              throws PlexusContainerException

Throws:

PlexusContainerException

createChildContainer

PlexusContainer createChildContainer(String name,
                                     List classpathJars,
                                     Map context,
                                     List discoveryListeners)
                              throws PlexusContainerException

Throws:

PlexusContainerException

createComponentRealm

org.codehaus.plexus.classworlds.realm.ClassRealm createComponentRealm(String id,
                                                                      List jars)
                                                               throws PlexusContainerException

Creates and returns a new class realm under this container's realm for the given list of jars. If the realm already exists, return the realm with the given ID?

Parameters:

id - unique key for the ClassRealm

jars - list of JARs to place in the realm.

Throws:

PlexusContainerException

See Also:

addJarResource(File)

getComponentRealm

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

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 MutablePlexusContainer#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(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: