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 }