|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
MutablePicoContainer.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 | * Idea by Rachel Davies, Original code by various * | |
9 | *****************************************************************************/ | |
10 | package org.picocontainer; | |
11 | ||
12 | ||
13 | ||
14 | /** | |
15 | * This is the core interface used for registration of components with a container. It is possible to register {@link | |
16 | * #registerComponentImplementation(Object,Class) an implementation class}, {@link #registerComponentInstance(Object) an | |
17 | * instance} or {@link #registerComponent(ComponentAdapter) a ComponentAdapter}. | |
18 | * | |
19 | * @author Paul Hammant | |
20 | * @author Aslak Hellesøy | |
21 | * @author Jon Tirsén | |
22 | * @version $Revision: 1800 $ | |
23 | * @see <a href="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a> | |
24 | * @since 1.0 | |
25 | */ | |
26 | public interface MutablePicoContainer extends PicoContainer { | |
27 | ||
28 | /** | |
29 | * Register a component. | |
30 | * | |
31 | * @param componentKey a key that identifies the component. Must be unique within the container. The type | |
32 | * of the key object has no semantic significance unless explicitly specified in the | |
33 | * documentation of the implementing container. | |
34 | * @param componentImplementation the component's implementation class. This must be a concrete class (ie, a | |
35 | * class that can be instantiated). | |
36 | * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return | |
37 | * value can be safely ignored, as one of the <code>getXXX()</code> methods of the | |
38 | * {@link PicoContainer} interface can be used to retrieve a reference to the component later on. | |
39 | * @throws PicoRegistrationException if registration of the component fails. | |
40 | * @see #registerComponentImplementation(Object,Class,Parameter[]) a variant of this method that allows more control | |
41 | * over the parameters passed into the componentImplementation constructor when constructing an instance. | |
42 | */ | |
43 | ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation) throws PicoRegistrationException; | |
44 | ||
45 | /** | |
46 | * Register a component. | |
47 | * | |
48 | * @param componentKey a key that identifies the component. Must be unique within the container. The type | |
49 | * of the key object has no semantic significance unless explicitly specified in the | |
50 | * documentation of the implementing container. | |
51 | * @param componentImplementation the component's implementation class. This must be a concrete class (ie, a | |
52 | * class that can be instantiated). | |
53 | * @param parameters an array of parameters that gives the container hints about what arguments to pass | |
54 | * to the constructor when it is instantiated. Container implementations may ignore | |
55 | * one or more of these hints. | |
56 | * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return | |
57 | * value can be safely ignored, as one of the <code>getXXX()</code> methods of the | |
58 | * {@link PicoContainer} interface can be used to retrieve a reference to the component later on. | |
59 | * @throws PicoRegistrationException if registration of the component fails. | |
60 | */ | |
61 | ComponentAdapter registerComponentImplementation(Object componentKey, Class componentImplementation, Parameter[] parameters) throws PicoRegistrationException; | |
62 | ||
63 | /** | |
64 | * Register a component using the componentImplementation as key. Calling this method is equivalent to calling | |
65 | * <code>registerComponentImplementation(componentImplementation, componentImplementation)</code>. | |
66 | * | |
67 | * @param componentImplementation the concrete component class. | |
68 | * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return | |
69 | * value can be safely ignored, as one of the <code>getXXX()</code> methods of the | |
70 | * {@link PicoContainer} interface can be used to retrieve a reference to the component later on. | |
71 | * @throws PicoRegistrationException if registration fails. | |
72 | */ | |
73 | ComponentAdapter registerComponentImplementation(Class componentImplementation) throws PicoRegistrationException; | |
74 | ||
75 | /** | |
76 | * Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to | |
77 | * calling * <code>registerComponentImplementation(componentImplementation, componentImplementation)</code>. | |
78 | * | |
79 | * @param componentInstance | |
80 | * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return | |
81 | * value can be safely ignored, as one of the <code>getXXX()</code> methods of the | |
82 | * {@link PicoContainer} interface can be used to retrieve a reference to the component later on. | |
83 | * @throws PicoRegistrationException if registration fails. | |
84 | */ | |
85 | ComponentAdapter registerComponentInstance(Object componentInstance) throws PicoRegistrationException; | |
86 | ||
87 | /** | |
88 | * Register an arbitrary object as a component in the container. This is handy when other components in the same | |
89 | * container have dependencies on this kind of object, but where letting the container manage and instantiate it is | |
90 | * impossible. | |
91 | * <p/> | |
92 | * Beware that too much use of this method is an <a href="http://docs.codehaus.org/display/PICO/Instance+Registration">antipattern</a>. | |
93 | * | |
94 | * @param componentKey a key that identifies the component. Must be unique within the conainer. The type of the | |
95 | * key object has no semantic significance unless explicitly specified in the implementing | |
96 | * container. | |
97 | * @param componentInstance an arbitrary object. | |
98 | * @return the ComponentAdapter that has been associated with this component. In the majority of cases, this return | |
99 | * value can be safely ignored, as one of the <code>getXXX()</code> methods of the | |
100 | * {@link PicoContainer} interface can be used to retrieve a reference to the component later on. | |
101 | * @throws PicoRegistrationException if registration fails. | |
102 | */ | |
103 | ComponentAdapter registerComponentInstance(Object componentKey, Object componentInstance) throws PicoRegistrationException; | |
104 | ||
105 | /** | |
106 | * Register a component via a ComponentAdapter. Use this if you need fine grained control over what | |
107 | * ComponentAdapter to use for a specific component. | |
108 | * | |
109 | * @param componentAdapter the adapter | |
110 | * @return the same adapter that was passed as an argument. | |
111 | * @throws PicoRegistrationException if registration fails. | |
112 | */ | |
113 | ComponentAdapter registerComponent(ComponentAdapter componentAdapter) throws PicoRegistrationException; | |
114 | ||
115 | /** | |
116 | * Unregister a component by key. | |
117 | * | |
118 | * @param componentKey key of the component to unregister. | |
119 | * @return the ComponentAdapter that was associated with this component. | |
120 | */ | |
121 | ComponentAdapter unregisterComponent(Object componentKey); | |
122 | ||
123 | /** | |
124 | * Unregister a component by instance. | |
125 | * | |
126 | * @param componentInstance the component instance to unregister. | |
127 | * @return the ComponentAdapter that was associated with this component. | |
128 | */ | |
129 | ComponentAdapter unregisterComponentByInstance(Object componentInstance); | |
130 | ||
131 | // TODO: For the sake of simplicity/unambiguity - perhaps remove this method and instead expose getComponentAdapterFactory()? --Aslak | |
132 | /** | |
133 | * Make a child container, using the same implementation of MutablePicoContainer as the parent. | |
134 | * It will have a reference to this as parent. This will list the resulting MPC as a child. | |
135 | * Lifecycle events will be cascaded from parent to child | |
136 | * as a consequence of this. | |
137 | * | |
138 | * @return the new child container. | |
139 | * @since 1.1 | |
140 | */ | |
141 | MutablePicoContainer makeChildContainer(); | |
142 | ||
143 | /** | |
144 | * Add a child container. This action will list the the 'child' as exactly that in the parents scope. | |
145 | * It will not change the child's view of a parent. That is determined by the constructor arguments of the child | |
146 | * itself. Lifecycle events will be cascaded from parent to child | |
147 | * as a consequence of calling this method. | |
148 | * | |
149 | * @param child the child container | |
150 | * @return <code>true</code> if the child container was not already in. | |
151 | * @since 1.1 | |
152 | */ | |
153 | boolean addChildContainer(PicoContainer child); | |
154 | ||
155 | /** | |
156 | * Remove a child container from this container. It will not change the child's view of a parent. | |
157 | * Lifecycle event will no longer be cascaded from the parent to the child. | |
158 | * | |
159 | * @param child the child container | |
160 | * @return <code>true</code> if the child container has been removed. | |
161 | * @since 1.1 | |
162 | */ | |
163 | boolean removeChildContainer(PicoContainer child); | |
164 | } |
|