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 }