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     * Original code by                                                          *
009     *****************************************************************************/
010    package org.picocontainer;
011    
012    import java.util.Collection;
013    import java.util.List;
014    
015    
016    /**
017     * This is the core interface for PicoContainer. It is used to retrieve component instances from the container; it only
018     * has accessor methods (in addition to the {@link #accept(PicoVisitor)} method). In order to register components in a
019     * PicoContainer, use a {@link MutablePicoContainer}, such as {@link org.picocontainer.defaults.DefaultPicoContainer}.
020     * 
021     * @author Paul Hammant
022     * @author Aslak Hellesøy
023     * @author Jon Tirsén
024     * @version $Revision: 2285 $
025     * @see <a href="package-summary.html#package_description">See package description for basic overview how to use
026     *      PicoContainer.</a>
027     * @since 1.0
028     */
029    public interface PicoContainer extends Startable, Disposable {
030    
031        /**
032         * Retrieve a component instance registered with a specific key. If a component cannot be found in this container,
033         * the parent container (if one exists) will be searched.
034         * 
035         * @param componentKey the key that the component was registered with.
036         * @return an instantiated component, or <code>null</code> if no component has been registered for the specified
037         *         key.
038         */
039        Object getComponentInstance(Object componentKey);
040    
041        /**
042         * Find a component instance matching the specified type.
043         * 
044         * @param componentType the type of the component
045         * @return an instantiated component matching the class, or <code>null</code> if no component has been registered
046         *         with a matching type
047         * @throws PicoException if the instantiation of the component fails
048         */
049        Object getComponentInstanceOfType(Class componentType);
050    
051        /**
052         * Retrieve all the registered component instances in the container, (not including those in the parent container).
053         * The components are returned in their order of instantiation, which depends on the dependency order between them.
054         * 
055         * @return all the components.
056         * @throws PicoException if the instantiation of the component fails
057         */
058        List getComponentInstances();
059    
060        /**
061         * Retrieve the parent container of this container.
062         * 
063         * @return a {@link PicoContainer} instance, or <code>null</code> if this container does not have a parent.
064         */
065        PicoContainer getParent();
066    
067        /**
068         * Find a component adapter associated with the specified key. If a component adapter cannot be found in this
069         * container, the parent container (if one exists) will be searched.
070         * 
071         * @param componentKey the key that the component was registered with.
072         * @return the component adapter associated with this key, or <code>null</code> if no component has been
073         *         registered for the specified key.
074         */
075        ComponentAdapter getComponentAdapter(Object componentKey);
076    
077        /**
078         * Find a component adapter associated with the specified type. If a component adapter cannot be found in this
079         * container, the parent container (if one exists) will be searched.
080         * 
081         * @param componentType the type of the component.
082         * @return the component adapter associated with this class, or <code>null</code> if no component has been
083         *         registered for the specified key.
084         */
085        ComponentAdapter getComponentAdapterOfType(Class componentType);
086    
087        /**
088         * Retrieve all the component adapters inside this container. The component adapters from the parent container are
089         * not returned.
090         * 
091         * @return a collection containing all the {@link ComponentAdapter}s inside this container. The collection will not
092         *         be modifiable.
093         * @see #getComponentAdaptersOfType(Class) a variant of this method which returns the component adapters inside this
094         *      container that are associated with the specified type.
095         */
096        Collection getComponentAdapters();
097    
098        /**
099         * Retrieve all component adapters inside this container that are associated with the specified type. The component
100         * adapters from the parent container are not returned.
101         * 
102         * @param componentType the type of the components.
103         * @return a collection containing all the {@link ComponentAdapter}s inside this container that are associated with
104         *         the specified type. Changes to this collection will not be reflected in the container itself.
105         */
106        List getComponentAdaptersOfType(Class componentType);
107    
108        /**
109         * Verify that the dependencies for all the registered components can be satisfied. No components are instantiated
110         * during the verification process.
111         * 
112         * @throws PicoVerificationException if there are unsatisifiable dependencies.
113         * @deprecated since 1.1 - Use "new VerifyingVisitor().traverse(this)"
114         */
115        void verify() throws PicoVerificationException;
116    
117        /**
118         * Returns a List of components of a certain componentType. The list is ordered by instantiation order, starting
119         * with the components instantiated first at the beginning.
120         * 
121         * @param componentType the searched type.
122         * @return a List of components.
123         * @throws PicoException if the instantiation of a component fails
124         * @since 1.1
125         */
126        List getComponentInstancesOfType(Class componentType);
127    
128        /**
129         * Accepts a visitor that should visit the child containers, component adapters and component instances.
130         * 
131         * @param visitor the visitor
132         * @since 1.1
133         */
134        void accept(PicoVisitor visitor);
135    }