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