    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 Jon Tirsen                        *
    009     *****************************************************************************/
    010
    011    package org.picocontainer;
    012
    013    import org.picocontainer.parameters.ComponentParameter;
    014
    015    import java.lang.annotation.Annotation;
    016    import java.lang.reflect.Type;
    017
    018    /**
    019     * This class provides control over the arguments that will be passed to a constructor. It can be used for finer control over
    020     * what arguments are passed to a particular constructor.
    021     *
    022     * @author Jon Tirs&eacute;n
    023     * @author Aslak Helles&oslash;y
    024     * @author Thomas Heller
    025     * @see MutablePicoContainer#addComponent(Object,Object,Parameter[]) a method on the
    026     *      {@link MutablePicoContainer} interface which allows passing in of an array of {@linkplain Parameter Parameters}.
    027     * @see org.picocontainer.parameters.ComponentParameter an implementation of this interface that allows you to specify the key
    028     *      used for resolving the parameter.
    029     * @see org.picocontainer.parameters.ConstantParameter an implementation of this interface that allows you to specify a constant
    030     *      that will be used for resolving the parameter.
    031     */
    032    public interface Parameter {
    033
    034            /**
    035             * Zero parameter is used when you wish a component to be instantiated with its default constructor.  Ex:
    036             * <div class="source">
    037             *      <pre>
    038             *              MutablePicoContainer mpc = new PicoBuilder().build();
    039             *              mpc.addComponent(Map.class, HashMap.class, Parameter.ZERO);
    040             *              mpc.addComponent(List.class, ArrayList.class, Parameter.ZERO);
    041             *      </pre>
    042             * </div>
    043             * <p>By specifying the default constructor in this example code, you allow PicoContainer to recognize
    044             * that HashMap(Collection) should <em>not</em> be used and avoid a CircularDependencyException.</p>
    045             */
    046        Parameter[] ZERO = new Parameter[0];
    047        Parameter[] DEFAULT = new Parameter[]{ ComponentParameter.DEFAULT };
    048
    049        /**
    050         * Retrieve the object from the Parameter that satisfies the expected type.
    051         *
    052         * @param container             the container from which dependencies are resolved.
    053         * @param adapter               the {@link ComponentAdapter} that is asking for the instance
    054         * @param expectedType          the type that the returned instance needs to match.
    055         * @param expectedNameBinding Expected parameter name
    056         *
    057         * @param useNames
    058         * @param binding
    059         * @return the instance or <code>null</code> if no suitable instance can be found.
    060         *
    061         * @throws PicoCompositionException if a referenced component could not be instantiated.
    062         */
    063         Object resolveInstance(PicoContainer container, ComponentAdapter<?> adapter,
    064                               Type expectedType, NameBinding expectedNameBinding,
    065                               boolean useNames, Annotation binding);
    066
    067        /**
    068         * Check if the Parameter can satisfy the expected type using the container.
    069         *
    070         * @param container             the container from which dependencies are resolved.
    071         * @param adapter               the {@link org.picocontainer.ComponentAdapter} that is asking for the instance
    072         * @param expectedType          the required type
    073         * @param expectedNameBinding Expected parameter name
    074         *
    075         * @param useNames
    076         * @param binding
    077         * @return <code>true</code> if the component parameter can be resolved.
    078         *
    079         */
    080        boolean isResolvable(PicoContainer container, ComponentAdapter<?> adapter,
    081                                    Type expectedType, NameBinding expectedNameBinding,
    082                                    boolean useNames, Annotation binding);
    083
    084        /**
    085         * Verify that the Parameter can satisfy the expected type using the container
    086         *
    087         * @param container             the container from which dependencies are resolved.
    088         * @param adapter               the {@link ComponentAdapter} that is asking for the verification
    089         * @param expectedType          the required type
    090         * @param expectedNameBinding Expected parameter name
    091         *
    092         * @param useNames
    093         * @param binding
    094         * @throws PicoCompositionException if parameter and its dependencies cannot be resolved
    095         */
    096        void verify(PicoContainer container, ComponentAdapter<?> adapter,
    097                    Type expectedType, NameBinding expectedNameBinding,
    098                    boolean useNames, Annotation binding);
    099
    100        /**
    101         * Accepts a visitor for this Parameter. The method is normally called by visiting a {@link ComponentAdapter}, that
    102         * cascades the {@linkplain PicoVisitor visitor} also down to all its {@linkplain Parameter Parameters}.
    103         *
    104         * @param visitor the visitor.
    105         *
    106         */
    107        void accept(PicoVisitor visitor);
    108    }