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én
023 * @author Aslak Hellesø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 }