001 /*****************************************************************************
002 * Copyright (c) PicoContainer Organization. All rights reserved. *
003 * ------------------------------------------------------------------------- *
004 * The software in this package is published under the terms of the BSD *
005 * style license a copy of which has been included with this distribution in *
006 * the LICENSE.txt file. *
007 * *
008 * Idea by Rachel Davies, Original code by various *
009 *****************************************************************************/
010 package org.picocontainer;
011
012 import java.util.Properties;
013
014 /**
015 * This is the core interface used for registration of components with a container. It is possible to register
016 * implementations and instances here
017 *
018 * @author Paul Hammant
019 * @author Aslak Hellesøy
020 * @author Jon Tirsén
021 * @see <a href="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a>
022 */
023 public interface MutablePicoContainer extends PicoContainer, Startable, Disposable {
024
025 /**
026 * Register a component and creates specific instructions on which constructor to use, along with
027 * which components and/or constants to provide as constructor arguments. These "directives" are
028 * provided through an array of <tt>Parameter</tt> objects. Parameter[0] correspondes to the first constructor
029 * argument, Parameter[N] corresponds to the N+1th constructor argument.
030 * <h4>Tips for Parameter usage</h4>
031 * <ul>
032 * <li><strong>Partial Autowiring: </strong>If you have two constructor args to match and you only wish to specify one of the constructors and
033 * let PicoContainer wire the other one, you can use as parameters:
034 * <code><strong>new ComponentParameter()</strong>, new ComponentParameter("someService")</code>
035 * The default constructor for the component parameter indicates auto-wiring should take place for
036 * that parameter.
037 * </li>
038 * <li><strong>Force No-Arg constructor usage:</strong> If you wish to force a component to be constructed with
039 * the no-arg constructor, use a zero length Parameter array. Ex: <code>new Parameter[0]</code>
040 * <ul>
041 *
042 * @param componentKey a key that identifies the component. Must be unique within the container. The type
043 * of the key object has no semantic significance unless explicitly specified in the
044 * documentation of the implementing container.
045 * @param componentImplementationOrInstance
046 * the component's implementation class. This must be a concrete class (ie, a
047 * class that can be instantiated). Or an intance of the compoent.
048 * @param parameters the parameters that gives the container hints about what arguments to pass
049 * to the constructor when it is instantiated. Container implementations may ignore
050 * one or more of these hints.
051 *
052 * @return the same instance of MutablePicoContainer
053 *
054 * @throws PicoCompositionException if registration of the component fails.
055 * @see org.picocontainer.Parameter
056 * @see org.picocontainer.parameters.ConstantParameter
057 * @see org.picocontainer.parameters.ComponentParameter
058 */
059 MutablePicoContainer addComponent(Object componentKey,
060 Object componentImplementationOrInstance,
061 Parameter... parameters);
062
063 /**
064 * Register an arbitrary object. The class of the object will be used as a key. Calling this method is equivalent to
065 * calling <code>addComponent(componentImplementation, componentImplementation)</code>.
066 *
067 * @param implOrInstance Component implementation or instance
068 *
069 * @return the same instance of MutablePicoContainer
070 *
071 * @throws PicoCompositionException if registration fails.
072 */
073 MutablePicoContainer addComponent(Object implOrInstance);
074
075 /**
076 * Register a config item.
077 *
078 * @param name the name of the config item
079 * @param val the value of the config item
080 *
081 * @return the same instance of MutablePicoContainer
082 *
083 * @throws PicoCompositionException if registration fails.
084 */
085 MutablePicoContainer addConfig(String name, Object val);
086
087 /**
088 * Register a component via a ComponentAdapter. Use this if you need fine grained control over what
089 * ComponentAdapter to use for a specific component.
090 *
091 * @param componentAdapter the addAdapter
092 *
093 * @return the same instance of MutablePicoContainer
094 *
095 * @throws PicoCompositionException if registration fails.
096 */
097 MutablePicoContainer addAdapter(ComponentAdapter componentAdapter);
098
099 /**
100 * Unregister a component by key.
101 *
102 * @param componentKey key of the component to unregister.
103 *
104 * @return the ComponentAdapter that was associated with this component.
105 */
106 ComponentAdapter removeComponent(Object componentKey);
107
108 /**
109 * Unregister a component by instance.
110 *
111 * @param componentInstance the component instance to unregister.
112 *
113 * @return the same instance of MutablePicoContainer
114 */
115 ComponentAdapter removeComponentByInstance(Object componentInstance);
116
117 /**
118 * Make a child container, using the same implementation of MutablePicoContainer as the parent.
119 * It will have a reference to this as parent. This will list the resulting MPC as a child.
120 * Lifecycle events will be cascaded from parent to child
121 * as a consequence of this.
122 *
123 * @return the new child container.
124 *
125 */
126 MutablePicoContainer makeChildContainer();
127
128 /**
129 * Add a child container. This action will list the the 'child' as exactly that in the parents scope.
130 * It will not change the child's view of a parent. That is determined by the constructor arguments of the child
131 * itself. Lifecycle events will be cascaded from parent to child
132 * as a consequence of calling this method.
133 *
134 * @param child the child container
135 *
136 * @return the same instance of MutablePicoContainer
137 *
138 */
139 MutablePicoContainer addChildContainer(PicoContainer child);
140
141 /**
142 * Remove a child container from this container. It will not change the child's view of a parent.
143 * Lifecycle event will no longer be cascaded from the parent to the child.
144 *
145 * @param child the child container
146 *
147 * @return <code>true</code> if the child container has been removed.
148 *
149 */
150 boolean removeChildContainer(PicoContainer child);
151
152
153 /**
154 * You can change the characteristic of registration of all subsequent components in this container.
155 *
156 * @param properties
157 * @return the same Pico instance with changed properties
158 */
159 MutablePicoContainer change(Properties... properties);
160
161 /**
162 * You can set for the following operation only the characteristic of registration of a component on the fly.
163 *
164 * @param properties
165 * @return the same Pico instance with temporary properties
166 */
167 MutablePicoContainer as(Properties... properties);
168
169 }