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