001 /* java.beans.beancontext.BeanContextServices
002 Copyright (C) 1999 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.beans.beancontext;
040
041 import java.util.Iterator;
042 import java.util.TooManyListenersException;
043
044 /**
045 * Allows a <code>BeanContext</code> to provide services to its children.
046 *
047 * @specnote it is unclear whether a <code>BeanContextServices</code>
048 * should delegate unhandled requests to parents. I assume so.
049 * @author John Keiser
050 * @since 1.2
051 */
052
053 public interface BeanContextServices
054 extends BeanContext, BeanContextServicesListener
055 {
056 /**
057 * Register a service to make it available to others.
058 * This class may refuse to add the service based on whatever
059 * information it can gather, including whether the service
060 * provider is trusted.
061 *
062 * @param serviceClass the service class.
063 * @param provider the factory that will actually provide the service.
064 * @return whether the service was added or not.
065 */
066 boolean addService (Class serviceClass,
067 BeanContextServiceProvider provider);
068
069 /**
070 * Make it so that no one else can use this service.
071 * <P>
072 *
073 * If <code>revokeNow</code> is <code>false</code>, the only
074 * effect of this method is to make all subsequent calls to
075 * <code>getService()</code> on this service class fail.
076 * <P>
077 *
078 * If it is <code>true</code>, a message is also sent out to all
079 * listeners on the service and all references to it are released.
080 *
081 * @param serviceClass the service class to revoke.
082 * @param provider the service provider providing the service class.
083 * @param revokeNow whether to release all current references to
084 * the service.
085 */
086 void revokeService (Class serviceClass,
087 BeanContextServiceProvider provider,
088 boolean revokeNow);
089
090 /**
091 * Release your copy of this service.
092 * <P>
093 *
094 * If all copies of the service's class have been relinquished by
095 * the requestor, the <code>BeanContextServiceRevokedListener</code>
096 * previously registered by <code>getService()</code> will be
097 * unregistered.
098 *
099 * @param requestorChild the original <code>BeanContextChild</code>
100 * requesting the service.
101 * @param requestor the original requestor of the service.
102 * @param service the service to relinquish
103 * @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)
104 */
105 void releaseService (BeanContextChild requestorChild, Object requestor,
106 Object service);
107
108 /**
109 * Get a service from this <code>BeanContextServices</code>.
110 * <P>
111 *
112 * The specified listener will be registered to receive a
113 * revocation notice for the specified serviceClass. One
114 * notification per service class per requestor object will be
115 * sent.
116 * <P>
117 *
118 * The listener will be unregistered when all services that were
119 * obtained by that requestor for that service class are released.
120 * <P>
121 *
122 * If the requested service class is not available, or if this
123 * <code>BeanContextServices</code> object chooses not honor the
124 * request because the service class has been revoked or for some
125 * other reason, then this method will return <code>null</code>.
126 * <P>
127 *
128 * This method may throw unchecked exceptions, so watch out.
129 *
130 * @specnote it is not specified what happens when two subsequent
131 * calls are made to <code>getService()</code> with the
132 * same requestor object and service class but different
133 * listeners. Which listener is to be notified?
134 *
135 * @param requestorChild the <code>BeanContextChild</code>
136 * associated with the requestor. Typically this will be
137 * the same as the requestor itself, but since any
138 * <code>Object</code>, even one outside the hierarchy, may
139 * make a request, this parameter is necessary. Only weak
140 * references to this will be retained, and it will never
141 * be changed, only queried in a read-only manner.
142 * @param requestor the actual requestor of the service. Only
143 * weak references to this will be retained, and it will
144 * never be changed, only queried in a read-only manner.
145 * @param serviceClass the <code>Class</code> of the service being
146 * requested.
147 * @param serviceSelector a parameter to customize the service
148 * returned with.
149 * @param listener a listener that will be notified if the service
150 * being requested is revoked.
151 * @return an instance of <code>serviceClass</code> (such that
152 * <code>instanceof</code> serviceClass is true), or
153 * <code>null</code>.
154 */
155 Object getService (BeanContextChild requestorChild, Object requestor,
156 Class serviceClass, Object serviceSelector,
157 BeanContextServiceRevokedListener listener)
158 throws TooManyListenersException;
159
160 /**
161 * Get a list of all service classes supported.
162 * <P>
163 *
164 * This method must synchronize on
165 * <code>BeanContext.globalHierarchyLock</code>.
166 *
167 * @return a list of all service classes supported.
168 * @see java.beans.beancontext.BeanContext#globalHierarchyLock
169 */
170 Iterator getCurrentServiceClasses ();
171
172 /**
173 * Get a list of valid service selectors for the specified service class.
174 * <P>
175 *
176 * If the specified service class does not have a finite number of
177 * valid service selectors, it should return <code>null</code>.
178 * If it takes a general <code>Integer</code> parameter, for
179 * example, you may as well return <code>null</code> or the poor
180 * soul who called this method will be iterating all day.
181 * <P>
182 *
183 * If it has no valid service selectors, it should still return an empty
184 * <code>Iterator</code>.
185 *
186 * @param serviceClass the service class to get selectors for.
187 * @return a list of valid service selectors for the service
188 * class, or <code>null</code>.
189 */
190 Iterator getCurrentServiceSelectors (Class serviceClass);
191
192 /**
193 * Tell whether the specified service class is available.
194 * Iff getService() could return a non-null value for the
195 * specified service, this method will return <code>true</code>.
196 *
197 * @param serviceClass the service class to check on.
198 * @return whether the specified service class is available.
199 */
200 boolean hasService (Class serviceClass);
201
202 /**
203 * Add a listener on all adds and removes of services.
204 * @param listener the listener to add.
205 */
206 void addBeanContextServicesListener (BeanContextServicesListener listener);
207
208 /**
209 * Remove a listener on all adds and removes of services.
210 * @specnote it is not certain whether this should remove this
211 * listener if it was specified in
212 * <code>getService()</code>.
213 * @param listener the listener to add.
214 */
215 void removeBeanContextServicesListener (BeanContextServicesListener listener);
216 }