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 }