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.
addContextValue
public void addContextValue(Object key,
Object value)
Add a key/value pair to this container's Context.
key
- any unique object valid to the Context's implementationvalue
- any object valid to the Context's implementation
addJarRepository
public void addJarRepository(File repository)
Adds a directory of jar resources.
repository
- a directory containing JAR files
addJarResource
public 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).
autowire
public 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).
component
- a valid Plexus component
- a componsed (dependency-injected) component
createAndAutowire
public Object createAndAutowire(String clazz)
throws CompositionException,
ClassNotFoundException,
InstantiationException,
IllegalAccessException
Creates a corrosponding component instance found in this container's classrealm, then autowires it.
clazz
- A class available in this container's ClassRealm
- A newly created and autowired component
createComponentRealm
public 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?
id
- unique key for the ClassRealmjars
- list of JARs to place in the realm.
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.
name
- a key unique amongst this container's children
- 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.
role
- a unique role for the desired component's descriptor
- 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.
role
- a unique role for the desired component's descriptorrealm
- The class realm to search
- 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.
role
- a unique role for the desired component's descriptorroleHint
- a hint showing which implementation should be used
- 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.
role
- a unique role for the desired component's descriptorroleHint
- a hint showing which implementation should be usedrealm
- The class realm to search
- 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.
role
- a non-unique key for the desired components
- 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.
role
- a non-unique key for the desired components
- 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.
role
- a non-unique key for the desired components
- 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.
role
- a non-unique key for the desired components
- 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.
- 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.
- this container's context.
getCreationDate
public Date getCreationDate()
Returns the date this container was created.
- the date this container was created
getLogger
public Logger getLogger()
getLookupRealm
public ClassRealm getLookupRealm()
Returns the lookup realm for this container, which is either
the container realm or the realm set by null.
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.
getName
public String getName()
Returns the unique name of this container in the container hierarchy.
- 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.
name
- a key unique amongst this container's children
- 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.
- 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.
- 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.
- true if a component's metadata may be reloaded
lookup
public Object lookup(Class componentClass)
throws ComponentLookupException
Looks up and returns a component object with the given unique key or role.
componentClass
- a unique key for the desired component
- a Plexus component object
lookup
public Object lookup(Class componentClass,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a component object with the given unique key or role.
componentClass
- a unique key for the desired component
- a Plexus component object
lookup
public Object lookup(Class role,
String roleHint)
throws ComponentLookupException
Looks up and returns a component object with the given unique role/role-hint combination.
role
- a non-unique class key for the desired componentroleHint
- a hint for the desired component implementation
- a Plexus component object
lookup
public Object lookup(Class role,
String roleHint,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a component object with the given unique role/role-hint combination.
role
- a non-unique class key for the desired componentroleHint
- a hint for the desired component implementation
- a Plexus component object
lookup
public Object lookup(String componentKey)
throws ComponentLookupException
Looks up and returns a component object with the given unique key or role.
componentKey
- a unique key for the desired component
- a Plexus component object
lookup
public Object lookup(String componentKey,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a component object with the given unique key or role.
componentKey
- a unique key for the desired component
- a Plexus component object
lookup
public Object lookup(String role,
String roleHint)
throws ComponentLookupException
Looks up and returns a component object with the given unique role/role-hint combination.
role
- a non-unique key for the desired componentroleHint
- a hint for the desired component implementation
- a Plexus component object
lookup
public Object lookup(String role,
String roleHint,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a component object with the given unique role/role-hint combination.
role
- a non-unique key for the desired componentroleHint
- a hint for the desired component implementation
- a Plexus component object
lookupList
public List lookupList(Class role)
throws ComponentLookupException
Looks up and returns a List of component objects with the given role.
role
- a non-unique class key for the desired components
- a List of component objects
lookupList
public List lookupList(Class role,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a List of component objects with the given role.
role
- a non-unique class key for the desired components
- a List of component objects
lookupList
public List lookupList(String role)
throws ComponentLookupException
Looks up and returns a List of component objects with the given role.
role
- a non-unique key for the desired components
- a List of component objects
lookupList
public List lookupList(String role,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a List of component objects with the given role.
role
- a non-unique key for the desired components
- a List of component objects
lookupMap
public 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.
role
- a non-unique class key for the desired components
- a Map of component objects
lookupMap
public Map lookupMap(Class role,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
role
- a non-unique class key for the desired components
- a Map of component objects
lookupMap
public 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.
role
- a non-unique key for the desired components
- a Map of component objects
lookupMap
public Map lookupMap(String role,
ClassRealm realm)
throws ComponentLookupException
Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
role
- a non-unique key for the desired components
- 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.
listener
- A listener which responds to differnet ComponentDiscoveryEvents
release
public 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).
component
- the plexus component object to release
releaseAll
public void releaseAll(List components)
throws ComponentLifecycleException
Releases all Listed components from the container.
components
- List of plexus component objects to release
PlexusContainer.release( Object component )
releaseAll
public void releaseAll(Map components)
throws ComponentLifecycleException
Releases all Mapped component values from the container.
components
- Map of plexus component objects to release
PlexusContainer.release( Object component )
removeChildContainer
public void removeChildContainer(String name)
Removes the keyed child from this container. Does not necessarily dispose the children.
name
- a key unique amongst this container's children
removeComponentDiscoveryListener
public void removeComponentDiscoveryListener(ComponentDiscoveryListener listener)
Removes the listener from this container.
listener
- A listener to remove
resume
public void resume(Object component)
throws ComponentLifecycleException
Attempts to resume execution of the component.
component
- a plexus component
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.
realm
- the new realm to use.
- 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.
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.
reloadingEnabled
- true is a component may be reloaded
suspend
public void suspend(Object component)
throws ComponentLifecycleException
Attempts to suspend execution of the component.
component
- a plexus component