KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > framework > component > ComponentManager


1 /* ====================================================================
2  * The Apache Software License, Version 1.1
3  *
4  * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5  * reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  *
19  * 3. The end-user documentation included with the redistribution,
20  * if any, must include the following acknowledgment:
21  * "This product includes software developed by the
22  * Apache Software Foundation (http://www.apache.org/)."
23  * Alternately, this acknowledgment may appear in the software
24  * itself, if and wherever such third-party acknowledgments
25  * normally appear.
26  *
27  * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28  * must not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation. For more
52  * information on the Apache Software Foundation, please see
53  * <http://www.apache.org/>.
54  */
55 package org.apache.avalon.framework.component;
56
57 /**
58  * A <code>ComponentManager</code> selects <code>Component</code>s based on a
59  * role. The contract is that all the <code>Component</code>s implement the
60  * differing roles and there is one <code>Component</code> per role. If you
61  * need to select on of many <code>Component</code>s that implement the same
62  * role, then you need to use a <code>ComponentSelector</code>. Roles are
63  * usually the full interface name.
64  *
65  * <p>
66  * A role is better understood by the analogy of a play. There are many
67  * different roles in a script. Any actor or actress can play any given part
68  * and you get the same results (phrases said, movements made, etc.). The exact
69  * nuances of the performance is different.
70  * </p>
71  *
72  * <p>
73  * Below is a list of things that might be considered the different roles:
74  * </p>
75  *
76  * <ul>
77  * <li> InputAdapter and OutputAdapter</li>
78  * <li> Store and Spool</li>
79  * </ul>
80  *
81  * <p>
82  * The <code>ComponentManager</code> does not specify the methodology of
83  * getting the <code>Component</code>, merely the interface used to get it.
84  * Therefore the <code>ComponentManager</code> can be implemented with a
85  * factory pattern, an object pool, or a simple Hashtable.
86  * </p>
87  *
88  * <p>
89  * <span style="color: red">Deprecated: </span><i>
90  * Use {@link org.apache.avalon.framework.service.ServiceManager} instead.
91  * </i>
92  * </p>
93  *
94  * @see org.apache.avalon.framework.component.Component
95  * @see org.apache.avalon.framework.component.Composable
96  * @see org.apache.avalon.framework.component.ComponentSelector
97  *
98  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
99  * @version CVS $Revision: 1.19 $ $Date: 2003/02/11 15:58:38 $
100  */
101 public interface ComponentManager
102 {
103     /**
104      * Get the <code>Component</code> associated with the given key. For
105      * instance, If the <code>ComponentManager</code> had a
106      * <code>LoggerComponent</code> stored and referenced by key, I would use
107      * the following call:
108      * <pre>
109      * try
110      * {
111      * LoggerComponent log;
112      * myComponent = (LoggerComponent) m_manager.lookup(LoggerComponent.ROLE);
113      * }
114      * catch (...)
115      * {
116      * ...
117      * }
118      * </pre>
119      *
120      * @param key The key name of the <code>Component</code> to retrieve.
121      * @return the desired component
122      * @throws ComponentException if an error occurs
123      */
124     Component lookup( String JavaDoc key )
125         throws ComponentException;
126
127     /**
128      * Check to see if a <code>Component</code> exists for a key.
129      *
130      * @param key a string identifying the key to check.
131      * @return True if the component exists, False if it does not.
132      */
133     boolean hasComponent( String JavaDoc key );
134
135     /**
136      * Return the <code>Component</code> when you are finished with it. This
137      * allows the <code>ComponentManager</code> to handle the End-Of-Life Lifecycle
138      * events associated with the Component. Please note, that no Exceptions
139      * should be thrown at this point. This is to allow easy use of the
140      * ComponentManager system without having to trap Exceptions on a release.
141      *
142      * @param component The Component we are releasing.
143      */
144     void release( Component component );
145 }
146
Popular Tags