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 }