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    }