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