    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&oslash;y
    020     * @author Jon Tirs&eacute;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    }