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