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