|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
PicoContainer.java | - | - | - | - |
|
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; | |
14 | import java.util.List; | |
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 getComponentInstance(Object 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 getComponentInstanceOfType(Class 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 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 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 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 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 getComponentAdaptersOfType(Class 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 getComponentInstancesOfType(Class 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 | } |
|