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