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 org.picocontainer.defaults.DefaultPicoContainer}.
020 *
021 * @author Paul Hammant
022 * @author Aslak Hellesøy
023 * @author Jon Tirsén
024 * @version $Revision: 2285 $
025 * @see <a href="package-summary.html#package_description">See package description for basic overview how to use
026 * PicoContainer.</a>
027 * @since 1.0
028 */
029 public interface PicoContainer extends Startable, Disposable {
030
031 /**
032 * Retrieve a component instance registered with a specific key. If a component cannot be found in this container,
033 * the parent container (if one exists) will be searched.
034 *
035 * @param componentKey the key 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 getComponentInstance(Object componentKey);
040
041 /**
042 * Find a component instance matching the specified type.
043 *
044 * @param componentType the type of the component
045 * @return an instantiated component matching the class, or <code>null</code> if no component has been registered
046 * with a matching type
047 * @throws PicoException if the instantiation of the component fails
048 */
049 Object getComponentInstanceOfType(Class componentType);
050
051 /**
052 * Retrieve all the registered component instances in the container, (not including those in the parent container).
053 * The components are returned in their order of instantiation, which depends on the dependency order between them.
054 *
055 * @return all the components.
056 * @throws PicoException if the instantiation of the component fails
057 */
058 List getComponentInstances();
059
060 /**
061 * Retrieve the parent container of this container.
062 *
063 * @return a {@link PicoContainer} instance, or <code>null</code> if this container does not have a parent.
064 */
065 PicoContainer getParent();
066
067 /**
068 * Find a component adapter associated with the specified key. If a component adapter cannot be found in this
069 * container, the parent container (if one exists) will be searched.
070 *
071 * @param componentKey the key that the component was registered with.
072 * @return the component adapter associated with this key, or <code>null</code> if no component has been
073 * registered for the specified key.
074 */
075 ComponentAdapter getComponentAdapter(Object componentKey);
076
077 /**
078 * Find a component adapter associated with the specified type. If a component adapter cannot be found in this
079 * container, the parent container (if one exists) will be searched.
080 *
081 * @param componentType the type of the component.
082 * @return the component adapter associated with this class, or <code>null</code> if no component has been
083 * registered for the specified key.
084 */
085 ComponentAdapter getComponentAdapterOfType(Class componentType);
086
087 /**
088 * Retrieve all the component adapters inside this container. The component adapters from the parent container are
089 * not returned.
090 *
091 * @return a collection containing all the {@link ComponentAdapter}s inside this container. The collection will not
092 * be modifiable.
093 * @see #getComponentAdaptersOfType(Class) a variant of this method which returns the component adapters inside this
094 * container that are associated with the specified type.
095 */
096 Collection getComponentAdapters();
097
098 /**
099 * Retrieve all component adapters inside this container that are associated with the specified type. The component
100 * adapters from the parent container are not returned.
101 *
102 * @param componentType the type of the components.
103 * @return a collection containing all the {@link ComponentAdapter}s inside this container that are associated with
104 * the specified type. Changes to this collection will not be reflected in the container itself.
105 */
106 List getComponentAdaptersOfType(Class componentType);
107
108 /**
109 * Verify that the dependencies for all the registered components can be satisfied. No components are instantiated
110 * during the verification process.
111 *
112 * @throws PicoVerificationException if there are unsatisifiable dependencies.
113 * @deprecated since 1.1 - Use "new VerifyingVisitor().traverse(this)"
114 */
115 void verify() throws PicoVerificationException;
116
117 /**
118 * Returns a List of components of a certain componentType. The list is ordered by instantiation order, starting
119 * with the components instantiated first at the beginning.
120 *
121 * @param componentType the searched type.
122 * @return a List of components.
123 * @throws PicoException if the instantiation of a component fails
124 * @since 1.1
125 */
126 List getComponentInstancesOfType(Class componentType);
127
128 /**
129 * Accepts a visitor that should visit the child containers, component adapters and component instances.
130 *
131 * @param visitor the visitor
132 * @since 1.1
133 */
134 void accept(PicoVisitor visitor);
135 }