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&oslash;y
21   * @author Jon Tirs&eacute;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 }
165
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags