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 }