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    /**
014     * This class provides control over the arguments that will be passed to a constructor. It can be used for finer control over
015     * what arguments are passed to a particular constructor.
016     * 
017     * @author Jon Tirsén
018     * @author Aslak Hellesøy
019     * @author Thomas Heller
020     * @see MutablePicoContainer#registerComponentImplementation(Object,Class,Parameter[]) a method on the
021     *      {@link MutablePicoContainer} interface which allows passing in of an array of {@linkplain Parameter Parameters}.
022     * @see org.picocontainer.defaults.ComponentParameter an implementation of this interface that allows you to specify the key
023     *      used for resolving the parameter.
024     * @see org.picocontainer.defaults.ConstantParameter an implementation of this interface that allows you to specify a constant
025     *      that will be used for resolving the parameter.
026     * @since 1.0
027     */
028    public interface Parameter {
029        /**
030         * Retrieve the object from the Parameter that statisfies the expected type.
031         * 
032         * @param container the container from which dependencies are resolved.
033         * @param adapter the {@link ComponentAdapter} that is asking for the instance
034         * @param expectedType the type that the returned instance needs to match.
035         * @return the instance or <code>null</code> if no suitable instance can be found.
036         * @throws PicoInitializationException if a referenced component could not be instantiated.
037         * @since 1.1
038         */
039        Object resolveInstance(PicoContainer container, ComponentAdapter adapter, Class expectedType);
040    
041        /**
042         * Check if the Parameter can statisfy the expected type using the container.
043         * 
044         * @param container the container from which dependencies are resolved.
045         * @param adapter the {@link ComponentAdapter} that is asking for the instance
046         * @param expectedType the required type
047         * @return <code>true</code> if the component parameter can be resolved.
048         * @since 1.1
049         */
050        boolean isResolvable(PicoContainer container, ComponentAdapter adapter, Class expectedType);
051    
052        /**
053         * Verify that the Parameter can statisfied the expected type using the container
054         * 
055         * @param container the container from which dependencies are resolved.
056         * @param adapter the {@link ComponentAdapter} that is asking for the verification
057         * @param expectedType the required type
058         * @throws PicoIntrospectionException if parameter and its dependencies cannot be resolved
059         * @since 1.1
060         */
061        void verify(PicoContainer container, ComponentAdapter adapter, Class expectedType);
062    
063        /**
064         * Accepts a visitor for this Parameter. The method is normally called by visiting a {@link ComponentAdapter}, that
065         * cascades the {@linkplain PicoVisitor visitor} also down to all its {@linkplain Parameter Parameters}.
066         * 
067         * @param visitor the visitor.
068         * @since 1.1
069         */
070        void accept(PicoVisitor visitor);
071    }