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
StringROLE
Method Summary
voidaddComponent(Object component, String role)
voidaddComponentDescriptor(ComponentDescriptor componentDescriptor)
Adds a component descriptor to this container. componentDescriptor should have realmId set.
voidaddContextValue(Object key, Object value)
Add a key/value pair to this container's Context.
voidaddJarRepository(File repository)
Adds a directory of jar resources.
voidaddJarResource(File resource)
Adds a jar to this container's ClassRealm - whose components are then discovered (via the various registered ComponentDiscoverer's).
PlexusContainercreateChildContainer(String name, Set urls)
PlexusContainercreateChildContainer(String name, ClassRealm realm)
ClassRealmcreateComponentRealm(String id, List jars)
Creates and returns a new class realm under this container's realm for the given list of jars.
voiddispose()
Disposes of this container, which in turn disposes all of it's components.
PlexusContainergetChildContainer(String name)
Returns a child container with the unique name.
ComponentDescriptorgetComponentDescriptor(String role)
Returns the ComponentDescriptor with the given component role and the default role hint.
ComponentDescriptorgetComponentDescriptor(String role, String roleHint)
Returns the ComponentDescriptor with the given component role and hint.
ComponentDescriptorgetComponentDescriptor(String role, ClassRealm realm)
Returns the ComponentDescriptor with the given component role and the default role hint.
ComponentDescriptorgetComponentDescriptor(String role, String roleHint, ClassRealm realm)
Returns the ComponentDescriptor with the given component role and hint.
ListgetComponentDescriptorList(String role)
Returns a List of ComponentDescriptors with the given role.
ListgetComponentDescriptorList(String role, ClassRealm componentRealm)
Returns a List of ComponentDescriptors with the given role.
MapgetComponentDescriptorMap(String role)
Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
MapgetComponentDescriptorMap(String role, ClassRealm componentRealm)
Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.
ClassRealmgetComponentRealm(String realmId)
ClassRealmgetContainerRealm()
Returns the Classworld's ClassRealm of this Container, which acts as the default parent for all contained components.
ContextgetContext()
Returns this container's context.
DategetCreationDate()
Returns the date this container was created.
LoggergetLogger()
LoggerManagergetLoggerManager()
ClassRealmgetLookupRealm()
Returns the lookup realm for this container, which is either the container realm or the realm set by {@see MutablePlexusContainer#setLookupRealm(ClassRealm)}.
ClassRealmgetLookupRealm(Object component)
XXX ideally i'd like to place this in a plexus container specific utility class.
StringgetName()
Returns the unique name of this container in the container hierarchy.
booleanhasChildContainer(String name)
Returns true if this container has a child with the given name.
booleanhasComponent(String role)
Returns true if this container has the keyed component.
booleanhasComponent(String role, String roleHint)
Returns true if this container has a component with the given role/role-hint.
booleanisReloadingEnabled()
Returns true if a component's metadata may be reloaded, otherwise, it may be loaded only once.
Objectlookup(String componentKey)
Looks up and returns a component object with the given unique key or role.
Objectlookup(String componentKey, ClassRealm realm)
Looks up and returns a component object with the given unique key or role.
Objectlookup(String role, String roleHint)
Looks up and returns a component object with the given unique role/role-hint combination.
Objectlookup(String role, String roleHint, ClassRealm realm)
Looks up and returns a component object with the given unique role/role-hint combination.
Objectlookup(Class componentClass)
Looks up and returns a component object with the given unique key or role.
Objectlookup(Class componentClass, ClassRealm realm)
Looks up and returns a component object with the given unique key or role.
Objectlookup(Class role, String roleHint)
Looks up and returns a component object with the given unique role/role-hint combination.
Objectlookup(Class role, String roleHint, ClassRealm realm)
Looks up and returns a component object with the given unique role/role-hint combination.
ListlookupList(String role)
Looks up and returns a List of component objects with the given role.
ListlookupList(String role, List roles)
Looks up and returns a List of component objects with the given role.
ListlookupList(String role, ClassRealm realm)
Looks up and returns a List of component objects with the given role.
ListlookupList(String role, List roles, ClassRealm realm)
Looks up and returns a List of component objects with the given role.
ListlookupList(Class role, List roles)
Looks up and returns a List of component objects with the given role.
ListlookupList(Class role)
Looks up and returns a List of component objects with the given role.
ListlookupList(Class role, List roles, ClassRealm realm)
Looks up and returns a List of component objects with the given role.
ListlookupList(Class role, ClassRealm realm)
Looks up and returns a List of component objects with the given role.
MaplookupMap(String role, List roles)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(String role)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(String role, List roles, ClassRealm realm)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(String role, ClassRealm realm)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(Class role, List roles)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(Class role)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(Class role, List roles, ClassRealm realm)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
MaplookupMap(Class role, ClassRealm realm)
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
voidregisterComponentDiscoveryListener(ComponentDiscoveryListener listener)
Adds the listener to this container.
voidrelease(Object component)
Releases the component from the container.
voidreleaseAll(Map components)
Releases all Mapped component values from the container.
voidreleaseAll(List components)
Releases all Listed components from the container.
voidremoveChildContainer(String name)
Removes the keyed child from this container.
voidremoveComponentDiscoveryListener(ComponentDiscoveryListener listener)
Removes the listener from this container.
voidsetLoggerManager(LoggerManager loggerManager)
ClassRealmsetLookupRealm(ClassRealm realm)
Sets the lookup realm to use for lookup calls that don't have a ClassRealm parameter.
voidsetName(String name)
voidsetParentPlexusContainer(PlexusContainer container)
Sets the parent of this container.
voidsetReloadingEnabled(boolean reloadingEnabled)
Sets the ability to reload a component's metadata multiple times.

Field Detail

ROLE

public String ROLE

Method Detail

addComponent

public void addComponent(Object component, String role)

addComponentDescriptor

public void addComponentDescriptor(ComponentDescriptor componentDescriptor)
Adds a component descriptor to this container. componentDescriptor should have realmId set.

Parameters: componentDescriptor

Throws: ComponentRepositoryException

addContextValue

public 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

addJarRepository

public void addJarRepository(File repository)
Adds a directory of jar resources.

Parameters: repository a directory containing JAR files

See Also: addJarResource

addJarResource

public void addJarResource(File resource)
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

createChildContainer

public PlexusContainer createChildContainer(String name, Set urls)

createChildContainer

public PlexusContainer createChildContainer(String name, ClassRealm realm)

createComponentRealm

public ClassRealm createComponentRealm(String id, List jars)
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

dispose

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

getChildContainer

public 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

getComponentDescriptor

public 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

public 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

public ComponentDescriptor getComponentDescriptor(String role, 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

public ComponentDescriptor getComponentDescriptor(String role, String roleHint, 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

getComponentDescriptorList

public 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

public List getComponentDescriptorList(String role, 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

getComponentDescriptorMap

public 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

public Map getComponentDescriptorMap(String role, 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

getComponentRealm

public ClassRealm getComponentRealm(String realmId)

getContainerRealm

public 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

getContext

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

getCreationDate

public Date getCreationDate()
Returns the date this container was created.

Returns: the date this container was created

getLogger

public Logger getLogger()

Deprecated:

getLoggerManager

public LoggerManager getLoggerManager()

getLookupRealm

public ClassRealm getLookupRealm()
Returns the lookup realm for this container, which is either the container realm or the realm set by {@see MutablePlexusContainer#setLookupRealm(ClassRealm)}.

getLookupRealm

public 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:

getName

public String getName()
Returns the unique name of this container in the container hierarchy.

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

hasChildContainer

public 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

hasComponent

public 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

public 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

isReloadingEnabled

public 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

lookup

public Object lookup(String componentKey)
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

lookup

public Object lookup(String componentKey, ClassRealm realm)
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

lookup

public Object lookup(String role, String roleHint)
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

lookup

public Object lookup(String role, String roleHint, ClassRealm realm)
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

lookup

public Object lookup(Class componentClass)
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

lookup

public Object lookup(Class componentClass, ClassRealm realm)
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

lookup

public Object lookup(Class role, String roleHint)
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

lookup

public Object lookup(Class role, String roleHint, ClassRealm realm)
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

lookupList

public List lookupList(String role)
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

lookupList

public List lookupList(String role, List roles)
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

lookupList

public List lookupList(String role, ClassRealm realm)
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

lookupList

public List lookupList(String role, List roles, ClassRealm realm)
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

lookupList

public List lookupList(Class role, List roles)
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

lookupList

public List lookupList(Class role)
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

lookupList

public List lookupList(Class role, List roles, ClassRealm realm)
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

lookupList

public List lookupList(Class role, ClassRealm realm)
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

lookupMap

public Map lookupMap(String role, List roles)
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

lookupMap

public Map lookupMap(String role)
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

lookupMap

public Map lookupMap(String role, List roles, ClassRealm realm)
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

lookupMap

public Map lookupMap(String role, ClassRealm realm)
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

lookupMap

public Map lookupMap(Class role, List roles)
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

lookupMap

public Map lookupMap(Class role)
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

lookupMap

public Map lookupMap(Class role, List roles, ClassRealm realm)
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

lookupMap

public Map lookupMap(Class role, ClassRealm realm)
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

registerComponentDiscoveryListener

public 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

release

public void release(Object component)
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

public void releaseAll(Map components)
Releases all Mapped component values from the container.

Parameters: components Map of plexus component objects to release

Throws: ComponentLifecycleException

See Also: PlexusContainer

releaseAll

public void releaseAll(List components)
Releases all Listed components from the container.

Parameters: components List of plexus component objects to release

Throws: ComponentLifecycleException

See Also: PlexusContainer

removeChildContainer

public 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

removeComponentDiscoveryListener

public void removeComponentDiscoveryListener(ComponentDiscoveryListener listener)
Removes the listener from this container.

Parameters: listener A listener to remove

setLoggerManager

public void setLoggerManager(LoggerManager loggerManager)

setLookupRealm

public 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 adviced to set it back once the old-style lookups have completed.

setName

public void setName(String name)

setParentPlexusContainer

public void setParentPlexusContainer(PlexusContainer container)
Sets the parent of this container.

Parameters: container the parent of this container, null if none

setReloadingEnabled

public void setReloadingEnabled(boolean reloadingEnabled)
Sets the ability to reload a component's metadata multiple times.

Parameters: reloadingEnabled true is a component may be reloaded