View Javadoc
1   package org.codehaus.plexus;
2   
3   /*
4    * Copyright 2001-2006 Codehaus Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.List;
20  import java.util.Map;
21  
22  import org.codehaus.plexus.classworlds.realm.ClassRealm;
23  import org.codehaus.plexus.component.composition.CycleDetectedInComponentGraphException;
24  import org.codehaus.plexus.component.discovery.ComponentDiscoveryListener;
25  import org.codehaus.plexus.component.repository.ComponentDescriptor;
26  import org.codehaus.plexus.component.repository.exception.ComponentLifecycleException;
27  import org.codehaus.plexus.component.repository.exception.ComponentLookupException;
28  import org.codehaus.plexus.component.repository.exception.ComponentRepositoryException;
29  import org.codehaus.plexus.configuration.PlexusConfigurationException;
30  import org.codehaus.plexus.context.Context;
31  
32  /**
33   * PlexusContainer is the entry-point for loading and accessing other
34   * components.
35   */
36  public interface PlexusContainer
37  {
38      String ROLE = PlexusContainer.class.getName();
39  
40      // ------------------------------------------------------------------------
41      // Lookup
42      // ------------------------------------------------------------------------
43  
44      /**
45       * Looks up and returns a component object with the given unique key or role.
46       * @param role a unique key for the desired component
47       * @return a Plexus component object
48       */
49      Object lookup( String role )
50          throws ComponentLookupException;
51  
52      /**
53       * Looks up and returns a component object with the given unique role/role-hint combination.
54       * @param role a non-unique key for the desired component
55       * @param roleHint a hint for the desired component implementation
56       * @return a Plexus component object
57       */
58      Object lookup( String role, String roleHint )
59          throws ComponentLookupException;
60  
61      /**
62       * Looks up and returns a component object with the given unique key or role.
63       * @param type the unique type of the component within the container
64       * @return a Plexus component object
65       */
66      <T> T lookup( Class<T> type )
67          throws ComponentLookupException;
68  
69      /**
70       * Looks up and returns a component object with the given unique role/role-hint combination.
71       * @param type the non-unique type of the component
72       * @param roleHint a hint for the desired component implementation
73       * @return a Plexus component object
74       */
75      <T> T lookup( Class<T> type, String roleHint )
76          throws ComponentLookupException;
77  
78      /**
79       * Looks up and returns a component object with the given unique role/role-hint combination.
80       * @param type the non-unique type of the component
81       * @param role a non-unique key for the desired component
82       * @param roleHint a hint for the desired component implementation
83       * @return a Plexus component object
84       */
85      <T> T lookup( Class<T> type, String role, String roleHint )
86          throws ComponentLookupException;
87  
88      /**
89       * Looks up and returns a component object matching the given component descriptor.
90       * @param componentDescriptor the descriptor of the component
91       * @return a Plexus component object
92       */
93      <T> T lookup( ComponentDescriptor<T> componentDescriptor )
94          throws ComponentLookupException;
95  
96      /**
97       * Looks up and returns a List of component objects with the given role.
98       * @param role a non-unique key for the desired components
99       * @return a List of component objects
100      */
101     List<Object> lookupList( String role )
102         throws ComponentLookupException;
103 
104     /**
105      * Looks up and returns a List of component objects with the given role.
106      * @param role a non-unique key for the desired components
107      * @return a List of component objects
108      */
109     List<Object> lookupList( String role, List<String> roleHints )
110         throws ComponentLookupException;
111 
112     /**
113      * Looks up and returns a List of component objects with the given role.
114      * @param type the non-unique type of the components
115      * @return a List of component objects
116      */
117     <T> List<T> lookupList( Class<T> type )
118         throws ComponentLookupException;
119 
120     /**
121      * Looks up and returns a List of component objects with the given role.
122      * @param type the non-unique type of the components
123      * @return a List of component objects
124      */
125     <T> List<T> lookupList( Class<T> type, List<String> roleHints )
126         throws ComponentLookupException;
127 
128     /**
129      * Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
130      * @param role a non-unique key for the desired components
131      * @return a Map of component objects
132      */
133     Map<String, Object> lookupMap( String role )
134         throws ComponentLookupException;
135 
136     /**
137      * Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
138      * @param role a non-unique key for the desired components
139      * @return a Map of component objects
140      */
141     Map<String, Object> lookupMap( String role, List<String> roleHints )
142         throws ComponentLookupException;
143 
144     /**
145      * Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
146      * @param type the non-unique type of the components
147      * @return a Map of component objects
148      */
149     <T> Map<String, T> lookupMap( Class<T> type )
150         throws ComponentLookupException;
151 
152     /**
153      * Looks up and returns a Map of component objects with the given role, keyed by all available role-hints.
154      * @param type the non-unique type of the components
155      * @return a Map of component objects
156      */
157     <T> Map<String, T> lookupMap( Class<T> type, List<String> roleHints )
158         throws ComponentLookupException;
159 
160     // ----------------------------------------------------------------------
161     // Component Descriptor Lookup
162     // ----------------------------------------------------------------------
163 
164     /**
165      * Returns the ComponentDescriptor with the given component role and the default role hint.
166      * Searches up the hierarchy until one is found, null if none is found.
167      * @param role a unique role for the desired component's descriptor
168      * @return the ComponentDescriptor with the given component role
169      */
170     ComponentDescriptor<?> getComponentDescriptor( String role );
171 
172     /**
173      * Returns the ComponentDescriptor with the given component role and hint.
174      * Searches up the hierarchy until one is found, null if none is found.
175      * @param role a unique role for the desired component's descriptor
176      * @param roleHint a hint showing which implementation should be used
177      * @return the ComponentDescriptor with the given component role
178      */
179     ComponentDescriptor<?> getComponentDescriptor( String role, String roleHint );
180 
181     /**
182      * Returns the ComponentDescriptor with the given component role and hint.
183      * Searches up the hierarchy until one is found, null if none is found.
184      * @param type the Java type of the desired component
185      * @param role a unique role for the desired component's descriptor
186      * @param roleHint a hint showing which implementation should be used
187      * @return the ComponentDescriptor with the given component role
188      */
189     <T> ComponentDescriptor<T> getComponentDescriptor( Class<T> type, String role, String roleHint );
190 
191     /**
192      * Returns a Map of ComponentDescriptors with the given role, keyed by role-hint. Searches up the hierarchy until
193      * all are found, an empty Map if none are found.
194      * @param role a non-unique key for the desired components
195      * @return a Map of component descriptors keyed by role-hint
196      */
197     Map<String, ComponentDescriptor<?>> getComponentDescriptorMap( String role );
198 
199     /**
200      * Returns a Map of ComponentDescriptors with the given role, keyed by role-hint. Searches up the hierarchy until
201      * all are found, an empty Map if none are found.
202      * @param type the Java type of the desired components
203      * @param role a non-unique key for the desired components
204      * @return a Map of component descriptors keyed by role-hint
205      */
206     <T> Map<String, ComponentDescriptor<T>> getComponentDescriptorMap( Class<T> type, String role );
207 
208     /**
209      * Returns a List of ComponentDescriptors with the given role. Searches up the hierarchy until all are found, an
210      * empty List if none are found.
211      * @param role a non-unique key for the desired components
212      * @return a List of component descriptors
213      */
214     List<ComponentDescriptor<?>> getComponentDescriptorList( String role );
215 
216     /**
217      * Returns a List of ComponentDescriptors with the given role. Searches up the hierarchy until all are found, an
218      * empty List if none are found.
219      * @param type the Java type of the desired components
220      * @param role a non-unique key for the desired components
221      * @return a List of component descriptors
222      */
223     <T> List<ComponentDescriptor<T>> getComponentDescriptorList( Class<T> type,  String role );
224 
225     /**
226      * Adds a component descriptor to this container. componentDescriptor should have realmId set.
227      * @param componentDescriptor
228      * @throws ComponentRepositoryException
229      */
230     void addComponentDescriptor( ComponentDescriptor<?> componentDescriptor )
231         throws CycleDetectedInComponentGraphException;
232 
233     /**
234      * Releases the component from the container. This is dependent upon how the implementation manages the component,
235      * but usually enacts some standard lifecycle shutdown procedure on the component. In every case, the component is
236      * no longer accessible from the container (unless another is created).
237      * @param component the plexus component object to release
238      * @throws ComponentLifecycleException
239      */
240     void release( Object component )
241         throws ComponentLifecycleException;
242 
243     /**
244      * Releases all Mapped component values from the container.
245      * @see PlexusContainer#release( Object component )
246      * @param components Map of plexus component objects to release
247      * @throws ComponentLifecycleException
248      */
249     void releaseAll( Map<String, ?> components )
250         throws ComponentLifecycleException;
251 
252     /**
253      * Releases all Listed components from the container.
254      * @see PlexusContainer#release( Object component )
255      * @param components List of plexus component objects to release
256      * @throws ComponentLifecycleException
257      */
258     void releaseAll( List<?> components )
259         throws ComponentLifecycleException;
260 
261     /**
262      * Returns true if this container has the keyed component.
263      * @param role a non-unique key for the desired component
264      * @return true if this container has the keyed component
265      */
266     boolean hasComponent( String role );
267 
268     /**
269      * Returns true if this container has a component with the given role/role-hint.
270      * @param role a non-unique key for the desired component
271      * @param roleHint a hint for the desired component implementation
272      * @return true if this container has a component with the given role/role-hint
273      */
274     boolean hasComponent( String role, String roleHint );
275 
276     /**
277      * Returns true if this container has a component with the given role/role-hint.
278      * @param type the non-unique type of the component
279      * @return true if this container has a component with the given role/role-hint
280      */
281     boolean hasComponent( Class<?> type );
282 
283     /**
284      * Returns true if this container has a component with the given role/role-hint.
285      * @param type the non-unique type of the component
286      * @param roleHint a hint for the desired component implementation
287      * @return true if this container has a component with the given role/role-hint
288      */
289     boolean hasComponent( Class<?> type, String roleHint );
290 
291     /**
292      * Returns true if this container has a component with the given role/role-hint.
293      * @param type the non-unique type of the component
294      * @param role a non-unique key for the desired component
295      * @param roleHint a hint for the desired component implementation
296      * @return true if this container has a component with the given role/role-hint
297      */
298     boolean hasComponent( Class<?> type, String role, String roleHint );
299 
300     /**
301      * Disposes of this container, which in turn disposes all of it's components. This container should also remove
302      * itself from the container hierarchy.
303      */
304     void dispose();
305 
306     // ----------------------------------------------------------------------
307     // Context
308     // ----------------------------------------------------------------------
309 
310     /**
311      * Add a key/value pair to this container's Context.
312      * @param key any unique object valid to the Context's implementation
313      * @param value any object valid to the Context's implementation
314      */
315     void addContextValue( Object key, Object value );
316 
317     /**
318      * Returns this container's context. A Context is a simple data store used to hold values which may alter the
319      * execution of the Container.
320      * @return this container's context.
321      */
322     Context getContext();
323 
324     /**
325      * Returns the Classworld's ClassRealm of this Container, which acts as the default parent for all contained
326      * components.
327      * @return the ClassRealm of this Container
328      */
329     ClassRealm getContainerRealm();
330 
331     // ----------------------------------------------------------------------
332     // Discovery
333     // ----------------------------------------------------------------------
334 
335     /**
336      * Adds the listener to this container. ComponentDiscoveryListeners have the ability to respond to various
337      * ComponentDiscoverer events.
338      * @param listener A listener which responds to different ComponentDiscoveryEvents
339      */
340     void registerComponentDiscoveryListener( ComponentDiscoveryListener listener );
341 
342     /**
343      * Removes the listener from this container.
344      * @param listener A listener to remove
345      */
346     void removeComponentDiscoveryListener( ComponentDiscoveryListener listener );
347 
348     /**
349      * Discovers components in the given realm.
350      * @param childRealm
351      * @param override whether to override/merge any conflicting components, where the new component takes precedence.
352      * @return
353      * @throws PlexusConfigurationException
354      * @throws ComponentRepositoryException
355      */
356     List<ComponentDescriptor<?>> discoverComponents( ClassRealm childRealm )
357         throws PlexusConfigurationException, CycleDetectedInComponentGraphException;
358 
359     List<ComponentDescriptor<?>> discoverComponents( ClassRealm realm, Object data )
360         throws PlexusConfigurationException, CycleDetectedInComponentGraphException;
361 
362     // ----------------------------------------------------------------------------
363     // Component/Plugin ClassRealm creation
364     // ----------------------------------------------------------------------------
365 
366     ClassRealm createChildRealm( String id );
367 
368     ClassRealm getComponentRealm( String realmId );
369 
370     /**
371      * Dissociate the realm with the specified id from the container. This will
372      * remove all components contained in the realm from the component repository.
373      *
374      * @param componentRealm Realm to remove from the container.
375      */
376     void removeComponentRealm( ClassRealm componentRealm )
377         throws PlexusContainerException;
378 
379     /**
380      * Returns the lookup realm for this container, which is either
381      * the container realm or the realm set by {@see MutablePlexusContainer#setLookupRealm(ClassRealm)}.
382      */
383     ClassRealm getLookupRealm();
384 
385     /**
386      * Sets the lookup realm to use for lookup calls that don't have a ClassRealm parameter.
387      * @param realm the new realm to use.
388      * @return The previous lookup realm. It is advised to set it back once the old-style lookups have completed.
389      */
390     ClassRealm setLookupRealm(ClassRealm realm);
391 
392     /**
393      * XXX ideally i'd like to place this in a plexus container specific utility class.
394      *
395      * Utility method to retrieve the lookup realm for a component instance.
396      * If the component's classloader is a ClassRealm, that realm is returned,
397      * otherwise the result of getLookupRealm is returned.
398      * @param component
399      * @return
400      */
401     ClassRealm getLookupRealm( Object component );
402 
403     void addComponent( Object component, String role )
404         throws CycleDetectedInComponentGraphException;
405 
406     /**
407      * Adds live component instance to this container.
408      *
409      * Component instance is not associated with any class realm and will
410      * be ignored during lookup is lookup realm is provided using thread context
411      * classloader.
412      */
413     <T> void addComponent( T component, Class<?> role, String roleHint );
414 }