KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > picocontainer > PicoContainer


1 /*****************************************************************************
2  * Copyright (C) PicoContainer Organization. All rights reserved. *
3  * ------------------------------------------------------------------------- *
4  * The software in this package is published under the terms of the BSD *
5  * style license a copy of which has been included with this distribution in *
6  * the LICENSE.txt file. *
7  * *
8  * Original code by *
9  *****************************************************************************/

10 package org.picocontainer;
11
12
13 import java.util.Collection JavaDoc;
14 import java.util.List JavaDoc;
15
16 /**
17  * This is the core interface for PicoContainer. It is used to retrieve component instances from the container; it only
18  * has accessor methods (in addition to the {@link #verify()} method). In order to register components in a
19  * PicoContainer, use a {@link MutablePicoContainer}, such as {@link org.picocontainer.defaults.DefaultPicoContainer}.
20  *
21  * @author Paul Hammant
22  * @author Aslak Hellesøy
23  * @author Jon Tirsén
24  * @version $Revision: 1820 $
25  * @see <a HREF="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a>
26  * @since 1.0
27  */

28 public interface PicoContainer extends Startable, Disposable {
29     // TODO: Paul will improve by refactoring to use injected monitor
30
// public static boolean SHOULD_LOG = "true".equals(System.getProperty("org.picocontainer.trace"));
31

32     /**
33      * Retrieve a component instance registered with a specific key. If a component cannot be found in this container,
34      * the parent container (if one exists) will be searched.
35      *
36      * @param componentKey the key that the component was registered with.
37      * @return an instantiated component, or <code>null</code> if no component has been registered for the specified
38      * key.
39      */

40     Object JavaDoc getComponentInstance(Object JavaDoc componentKey);
41
42     /**
43      * Find a component instance matching the specified type.
44      *
45      * @param componentType the type of the component.
46      * @return the adapter matching the class.
47      */

48     Object JavaDoc getComponentInstanceOfType(Class JavaDoc componentType);
49
50     /**
51      * Retrieve all the registered component instances in the container, (not including those in the parent container).
52      * The components are returned in their order of instantiation, which depends on the dependency order between them.
53      *
54      * @return all the components.
55      */

56     List JavaDoc getComponentInstances();
57
58     /**
59      * Retrieve the parent container of this container.
60      *
61      * @return a {@link PicoContainer} instance, or <code>null</code> if this container does not have a parent.
62      */

63     PicoContainer getParent();
64
65     /**
66      * Find a component adapter associated with the specified key. If a component adapter cannot be found in this
67      * container, the parent container (if one exists) will be searched.
68      *
69      * @param componentKey the key that the component was registered with.
70      * @return the component adapter associated with this key, or <code>null</code> if no component has been registered
71      * for the specified key.
72      */

73     ComponentAdapter getComponentAdapter(Object JavaDoc componentKey);
74
75     /**
76      * Find a component adapter associated with the specified type. If a component adapter cannot be found in this
77      * container, the parent container (if one exists) will be searched.
78      *
79      * @param componentType the type of the component.
80      * @return the component adapter associated with this class, or <code>null</code> if no component has been
81      * registered for the specified key.
82      */

83     ComponentAdapter getComponentAdapterOfType(Class JavaDoc componentType);
84
85     /**
86      * Retrieve all the component adapters inside this container. The component adapters from the parent container are
87      * not returned.
88      *
89      * @return a collection containing all the {@link ComponentAdapter}s inside this container. The collection will
90      * not be modifiable.
91      * @see #getComponentAdaptersOfType(Class) a variant of this method which returns the component adapters inside this
92      * container that are associated with the specified type.
93      */

94     Collection JavaDoc getComponentAdapters();
95
96     /**
97      * Retrieve all component adapters inside this container that are associated with the specified type. The component
98      * adapters from the parent container are not returned.
99      *
100      * @param componentType the type of the components.
101      * @return a collection containing all the {@link ComponentAdapter}s inside this container that are associated with
102      * the specified type. Changes to this collection will not be reflected in the container itself.
103      */

104     List JavaDoc getComponentAdaptersOfType(Class JavaDoc componentType);
105
106     /**
107      * Verify that the dependencies for all the registered components can be satisfied. No components are
108      * instantiated during the verification process.
109      *
110      * @throws PicoVerificationException if there are unsatisifiable dependencies.
111      * @deprecated since 1.1 - Use new VerifyingVisitor().traverse(this)
112     */

113     void verify() throws PicoVerificationException;
114
115     /**
116      * Returns a List of components of a certain componentType. The list is ordered by instantiation order,
117      * starting with the components instantiated first at the beginning.
118      * @param componentType the searched type.
119      * @return a List of components.
120      * @throws PicoException
121      * @since 1.1
122      */

123     List JavaDoc getComponentInstancesOfType(Class JavaDoc componentType) throws PicoException;
124
125     /**
126      * Accepts a visitor that should visit the child containers, component adapters and component instances.
127      * @param visitor the visitor
128      * @since 1.1
129      */

130     void accept(PicoVisitor visitor);
131 }
132
Popular Tags