PicoContainer


1   /*****************************************************************************
2    * Copyright (C) PicoContainer Organization. All rights reserved.            *
3    * ------------------------------------------------------------------------- *
4    * The software in this package is published under the terms of the BSD      *
5    * style license a copy of which has been included with this distribution in *
6    * the LICENSE.txt file.                                                     *
7    *                                                                           *
8    * Original code by                                                          *
9    *****************************************************************************/
10  package org.picocontainer;
11  
12  
13  import java.util.Collection  ;
14  import java.util.List  ;
15  
16  /**
17   * This is the core interface for PicoContainer. It is used to retrieve component instances from the container; it only
18   * has accessor methods (in addition to  the {@link #verify()} method). In order to register components in a
19   * PicoContainer, use a {@link MutablePicoContainer}, such as {@link org.picocontainer.defaults.DefaultPicoContainer}.
20   *
21   * @author Paul Hammant
22   * @author Aslak Helles&oslash;y
23   * @author Jon Tirs&eacute;n
24   * @version $Revision: 1820 $
25   * @see <a HREF="package-summary.html#package_description">See package description for basic overview how to use PicoContainer.</a>
26   * @since 1.0
27   */
28  public interface PicoContainer extends Startable, Disposable {
29      // TODO: Paul will improve by refactoring to use injected monitor
30  //    public static boolean SHOULD_LOG = "true".equals(System.getProperty("org.picocontainer.trace"));
31  
32      /**
33       * Retrieve a component instance registered with a specific key. If a component cannot be found in this container,
34       * the parent container (if one exists) will be searched.
35       * 
36       * @param componentKey the key that the component was registered with.
37       * @return an instantiated component, or <code>null</code> if no component has been registered for the specified
38       *         key.
39       */
40      Object   getComponentInstance(Object   componentKey);
41  
42      /**
43       * Find a component instance matching the specified type.
44       * 
45       * @param componentType the type of the component.
46       * @return the adapter matching the class.
47       */
48      Object   getComponentInstanceOfType(Class   componentType);
49  
50      /**
51       * Retrieve all the registered component instances in the container, (not including those in the parent container).
52       * The components are returned in their order of instantiation, which depends on the dependency order between them.
53       * 
54       * @return all the components.
55       */
56      List   getComponentInstances();
57  
58      /**
59       * Retrieve the parent container of this container.
60       * 
61       * @return a {@link PicoContainer} instance, or <code>null</code> if this container does not have a parent.
62       */
63      PicoContainer getParent();
64  
65      /**
66       * Find a component adapter associated with the specified key. If a component adapter cannot be found in this
67       * container, the parent container (if one exists) will be searched.
68       * 
69       * @param componentKey the key that the component was registered with.
70       * @return the component adapter associated with this key, or <code>null</code> if no component has been registered
71       *         for the specified key.
72       */
73      ComponentAdapter getComponentAdapter(Object   componentKey);
74  
75      /**
76       * Find a component adapter associated with the specified type. If a component adapter cannot be found in this
77       * container, the parent container (if one exists) will be searched.
78       * 
79       * @param componentType the type of the component.
80       * @return the component adapter associated with this class, or <code>null</code> if no component has been
81       *         registered for the specified key.
82       */
83      ComponentAdapter getComponentAdapterOfType(Class   componentType);
84  
85      /**
86       * Retrieve all the component adapters inside this container. The component adapters from the parent container are
87       * not returned.
88       *
89       * @return a collection containing all the {@link ComponentAdapter}s inside this container. The collection will
90       *         not be modifiable.
91       * @see #getComponentAdaptersOfType(Class) a variant of this method which returns the component adapters inside this
92       *      container that are associated with the specified type.
93       */
94      Collection   getComponentAdapters();
95  
96      /**
97       * Retrieve all component adapters inside this container that are associated with the specified type. The component
98       * adapters from the parent container are not returned.
99       * 
100      * @param componentType the type of the components.
101      * @return a collection containing all the {@link ComponentAdapter}s inside this container that are associated with
102      *         the specified type. Changes to this collection will not be reflected in the container itself.
103      */
104     List   getComponentAdaptersOfType(Class   componentType);
105 
106     /**
107      * Verify that the dependencies for all the registered components can be satisfied. No components are
108      * instantiated during the verification process.
109      * 
110      * @throws PicoVerificationException if there are unsatisifiable dependencies.
111      * @deprecated since 1.1 - Use new VerifyingVisitor().traverse(this)
112     */
113     void verify() throws PicoVerificationException;
114 
115     /**
116      * Returns a List of components of a certain componentType. The list is ordered by instantiation order,
117      * starting with the components instantiated first at the beginning.
118      * @param componentType the searched type.
119      * @return a List of components.
120      * @throws PicoException
121      * @since 1.1
122      */
123     List   getComponentInstancesOfType(Class   componentType) throws PicoException;
124 
125     /**
126      * Accepts a visitor that should visit the child containers, component adapters and component instances.
127      * @param visitor the visitor
128      * @since 1.1
129      */
130     void accept(PicoVisitor visitor);
131 }
132
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags