    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&oslash;y
    025     * @author Jon Tirs&eacute;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    }