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