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 package org.picocontainer; 009 010 /** 011 * A component adapter is responsible for providing a specific component instance. An instance of an implementation of 012 * this interface is used inside a {@link PicoContainer} for every registered component or instance. Each 013 * <code>ComponentAdapter</code> instance has to have a key which is unique within that container. The key itself is 014 * either a class type (normally an interface) or an identifier. 015 * 016 * @author Jon Tirsén 017 * @author Paul Hammant 018 * @author Aslak Hellesøy 019 * @version $Revision: 1801 $ 020 * @see MutablePicoContainer an extension of the PicoContainer interface which allows you to modify the contents of the 021 * container. 022 * @since 1.0 023 */ 024 public interface ComponentAdapter { 025 /** 026 * Retrieve the key associated with the component. 027 * 028 * @return the component's key. Should either be a class type (normally an interface) or an identifier that is 029 * unique (within the scope of the current PicoContainer). 030 */ 031 Object getComponentKey(); 032 033 /** 034 * Retrieve the class of the component. 035 * 036 * @return the component's implementation class. Should normally be a concrete class (ie, a class that can be 037 * instantiated). 038 */ 039 Class getComponentImplementation(); 040 041 /** 042 * Retrieve the component instance. This method will usually create a new instance each time it is called, but that 043 * is not required. For example, {@link org.picocontainer.defaults.CachingComponentAdapter} will always return the 044 * same instance. 045 * 046 * @param container the {@link PicoContainer}, that is used to resolve any possible dependencies of the instance. 047 * @return the component instance. 048 * @throws PicoInitializationException if the component could not be instantiated. 049 * @throws PicoIntrospectionException if the component has dependencies which could not be resolved, or 050 * instantiation of the component lead to an ambigous situation within the 051 * container. 052 */ 053 Object getComponentInstance(PicoContainer container) throws PicoInitializationException, PicoIntrospectionException; 054 055 /** 056 * Verify that all dependencies for this adapter can be satisifed. Normally, the adapter should verify this by 057 * checking that the associated PicoContainer contains all the needed dependnecies. 058 * 059 * @param container the {@link PicoContainer}, that is used to resolve any possible dependencies of the instance. 060 * @throws PicoIntrospectionException if one or more dependencies cannot be resolved. 061 */ 062 void verify(PicoContainer container) throws PicoIntrospectionException; 063 064 /** 065 * Accepts a visitor for this ComponentAdapter. The method is normally called by visiting a {@link PicoContainer}, that 066 * cascades the visitor also down to all its ComponentAdapter instances. 067 * 068 * @param visitor the visitor. 069 * @since 1.1 070 */ 071 void accept(PicoVisitor visitor); 072 }