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 &quot;directives&quot; 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.  The adapter will be wrapped in whatever behaviors that the 
090         * the container has been set up with.  If you want to bypass that behavior for the adapter you are adding, 
091         * you should use Characteristics.NONE like so pico.as(Characteristics.NONE).addAdapter(...)
092         *
093         * @param componentAdapter the adapter
094         *
095         * @return the same instance of MutablePicoContainer
096         *
097         * @throws PicoCompositionException if registration fails.
098         */
099        MutablePicoContainer addAdapter(ComponentAdapter<?> componentAdapter);
100    
101        /**
102         * Unregister a component by key.
103         *
104         * @param componentKey key of the component to unregister.
105         *
106         * @return the ComponentAdapter that was associated with this component.
107         */
108        <T> ComponentAdapter<T> removeComponent(Object componentKey);
109    
110        /**
111         * Unregister a component by instance.
112         *
113         * @param componentInstance the component instance to unregister.
114         *
115         * @return the same instance of MutablePicoContainer
116         */
117        <T> ComponentAdapter<T> removeComponentByInstance(T componentInstance);
118    
119        /**
120         * Make a child container, using the same implementation of MutablePicoContainer as the parent.
121         * It will have a reference to this as parent.  This will list the resulting MPC as a child.
122         * Lifecycle events will be cascaded from parent to child
123         * as a consequence of this.
124         *
125         * @return the new child container.
126         *
127         */
128        MutablePicoContainer makeChildContainer();
129    
130        /**
131         * Add a child container. This action will list the the 'child' as exactly that in the parents scope.
132         * It will not change the child's view of a parent.  That is determined by the constructor arguments of the child
133         * itself. Lifecycle events will be cascaded from parent to child
134         * as a consequence of calling this method.
135         *
136         * @param child the child container
137         *
138         * @return the same instance of MutablePicoContainer
139         *
140         */
141        MutablePicoContainer addChildContainer(PicoContainer child);
142    
143        /**
144         * Remove a child container from this container. It will not change the child's view of a parent.
145         * Lifecycle event will no longer be cascaded from the parent to the child.
146         *
147         * @param child the child container
148         *
149         * @return <code>true</code> if the child container has been removed.
150         *
151         */
152        boolean removeChildContainer(PicoContainer child);
153    
154    
155        /**
156         * You can change the characteristic of registration of all subsequent components in this container.
157         *
158         * @param properties
159         * @return the same Pico instance with changed properties
160         */
161        MutablePicoContainer change(Properties... properties);
162    
163        /**
164         * You can set for the following operation only the characteristic of registration of a component on the fly.
165         *
166         * @param properties
167         * @return the same Pico instance with temporary properties
168         */
169        MutablePicoContainer as(Properties... properties);
170    
171    }