Package 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 -
Method Summary
Modifier and TypeMethodDescriptionvoid
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).Assembles a component and returns it.createAndAutowire
(String clazz) Creates a corrosponding component instance found in this container's classrealm, then autowires it.createChildContainer
(String name, Set urls) createChildContainer
(String name, org.codehaus.plexus.classworlds.realm.ClassRealm realm) 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.getChildContainer
(String name) Returns a child container with the unique name.getComponentDescriptor
(String role) Returns the ComponentDescriptor with the given component role and the default role hint.getComponentDescriptor
(String role, String roleHint) Returns the ComponentDescriptor with the given component role and hint.getComponentDescriptor
(String role, String roleHint, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Returns the ComponentDescriptor with the given component role and hint.getComponentDescriptor
(String role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Returns the ComponentDescriptor with the given component role and the default role hint.Returns a List of ComponentDescriptors with the given role.getComponentDescriptorList
(String role, org.codehaus.plexus.classworlds.realm.ClassRealm componentRealm) Returns a List of ComponentDescriptors with the given role.Returns a Map of ComponentDescriptors with the given role, keyed by role-hint.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
Returns the Classworld's ClassRealm of this Container, which acts as the default parent for all contained components.Returns this container's context.Returns the date this container was created.Deprecated.org.codehaus.plexus.classworlds.realm.ClassRealm
Returns the lookup realm for this container, which is either the container realm or the realm set by .org.codehaus.plexus.classworlds.realm.ClassRealm
getLookupRealm
(Object component) XXX ideally i'd like to place this in a plexus container specific utility class.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
Returns true if a component's metadata may be reloaded, otherwise, it may be loaded only once.Looks up and returns a component object with the given unique key or role.Looks up and returns a component object with the given unique role/role-hint combination.Looks up and returns a component object with the given unique role/role-hint combination.Looks up and returns a component object with the given unique key or role.Looks up and returns a component object with the given unique key or role.Looks up and returns a component object with the given unique role/role-hint combination.Looks up and returns a component object with the given unique role/role-hint combination.Looks up and returns a component object with the given unique key or role.lookupList
(Class role) Looks up and returns a List of component objects with the given role.lookupList
(Class role, List roles) Looks up and returns a List of component objects with the given role.lookupList
(Class role, List roles, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a List of component objects with the given role.lookupList
(Class role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a List of component objects with the given role.lookupList
(String role) Looks up and returns a List of component objects with the given role.lookupList
(String role, List roles) Looks up and returns a List of component objects with the given role.lookupList
(String role, List roles, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a List of component objects with the given role.lookupList
(String role, org.codehaus.plexus.classworlds.realm.ClassRealm realm) Looks up and returns a List of component objects with the given role.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.void
Adds the listener to this container.void
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
Removes the listener from this container.void
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
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
Attempts to suspend execution of the component.
-
Field Details
-
ROLE
-
-
Method Details
-
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
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
Removes the keyed child from this container. Does not necessarily dispose the children.- Parameters:
name
- a key unique amongst this container's children
-
getChildContainer
Returns a child container with the unique name.- Parameters:
name
- a key unique amongst this container's children- Returns:
- the keyed child container
-
lookup
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
Looks up and returns a component object with the given unique role/role-hint combination.- Parameters:
role
- a non-unique key for the desired componentroleHint
- 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 componentroleHint
- a hint for the desired component implementation- Returns:
- a Plexus component object
- Throws:
ComponentLookupException
-
lookup
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
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 componentroleHint
- 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 componentroleHint
- a hint for the desired component implementation- Returns:
- a Plexus component object
- Throws:
ComponentLookupException
-
lookupList
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
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(String role, List roles, 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
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
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, List roles, 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
-
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
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
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, List roles, 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(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
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
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, List roles, 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
-
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
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
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 descriptorroleHint
- 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 descriptorrealm
- 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 descriptorroleHint
- a hint showing which implementation should be usedrealm
- The class realm to search- Returns:
- the ComponentDescriptor with the given component role
-
getComponentDescriptorMap
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
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
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
Releases all Mapped component values from the container.- Parameters:
components
- Map of plexus component objects to release- Throws:
ComponentLifecycleException
- See Also:
-
releaseAll
Releases all Listed components from the container.- Parameters:
components
- List of plexus component objects to release- Throws:
ComponentLifecycleException
- See Also:
-
hasComponent
Returns true if this container has the keyed component.- Parameters:
role
-- Returns:
- true if this container has the keyed component
-
hasComponent
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
Attempts to suspend execution of the component.- Parameters:
component
- a plexus component- Throws:
ComponentLifecycleException
-
resume
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
Add a key/value pair to this container's Context.- Parameters:
key
- any unique object valid to the Context's implementationvalue
- 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
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
Removes the listener from this container.- Parameters:
listener
- A listener to remove
-
addJarRepository
Adds a directory of jar resources.- Parameters:
repository
- a directory containing JAR files- See Also:
-
addJarResource
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
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:
-
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
-
getLoggerManager
LoggerManager getLoggerManager() -
getLogger
Logger getLogger()Deprecated. -
setName
-
setParentPlexusContainer
Sets the parent of this container.- Parameters:
container
- the parent of this container, null if none
-
createChildContainer
- Throws:
PlexusContainerException
-
createChildContainer
PlexusContainer createChildContainer(String name, org.codehaus.plexus.classworlds.realm.ClassRealm realm) 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 ClassRealmjars
- list of JARs to place in the realm.- Throws:
PlexusContainerException
- See Also:
-
getComponentRealm
-
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
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
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:
-