KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > picocontainer > MutablePicoContainer


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 JavaDoc componentKey, Class JavaDoc 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 JavaDoc componentKey, Class JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc componentKey, Object JavaDoc 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 JavaDoc 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 JavaDoc 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 }
165
Popular Tags