39 |
package java.beans.beancontext; |
package java.beans.beancontext; |
40 |
|
|
41 |
import java.util.Iterator; |
import java.util.Iterator; |
42 |
|
import java.util.TooManyListenersException; |
43 |
|
|
44 |
/** |
/** |
45 |
* Allows a <code>BeanContext</code> to provide services to its children. |
* Allows a <code>BeanContext</code> to provide services to its children. |
47 |
* @specnote it is unclear whether a <code>BeanContextServices</code> |
* @specnote it is unclear whether a <code>BeanContextServices</code> |
48 |
* should delegate unhandled requests to parents. I assume so. |
* should delegate unhandled requests to parents. I assume so. |
49 |
* @author John Keiser |
* @author John Keiser |
50 |
* @since JDK1.2 |
* @since 1.2 |
51 |
*/ |
*/ |
52 |
|
|
53 |
public interface BeanContextServices extends BeanContext, BeanContextServicesListener { |
public interface BeanContextServices |
54 |
/** |
extends BeanContext, BeanContextServicesListener |
55 |
* Register a service to make it available to others. |
{ |
56 |
* This class may refuse to add the service based on whatever |
/** |
57 |
* information it can gather, including whether the service |
* Register a service to make it available to others. |
58 |
* provider is trusted. |
* This class may refuse to add the service based on whatever |
59 |
* |
* information it can gather, including whether the service |
60 |
* @param serviceClass the service class. |
* provider is trusted. |
61 |
* @param provider the factory that will actually provide the service. |
* |
62 |
* @return whether the service was added or not. |
* @param serviceClass the service class. |
63 |
*/ |
* @param provider the factory that will actually provide the service. |
64 |
public boolean addService(Class serviceClass, BeanContextServiceProvider provider); |
* @return whether the service was added or not. |
65 |
|
*/ |
66 |
/** |
public boolean addService (Class serviceClass, |
67 |
* Make it so that no one else can use this service. |
BeanContextServiceProvider provider); |
68 |
* <P> |
|
69 |
* |
/** |
70 |
* If <code>revokeNow</code> is <code>false</code>, the only |
* Make it so that no one else can use this service. |
71 |
* effect of this method is to make all subsequent calls to |
* <P> |
72 |
* <code>getService()</code> on this service class fail. |
* |
73 |
* <P> |
* If <code>revokeNow</code> is <code>false</code>, the only |
74 |
* |
* effect of this method is to make all subsequent calls to |
75 |
* If it is <code>true</code>, a message is also sent out to all |
* <code>getService()</code> on this service class fail. |
76 |
* listeners on the service and all references to it are released. |
* <P> |
77 |
* |
* |
78 |
* @param serviceClass the service class to revoke. |
* If it is <code>true</code>, a message is also sent out to all |
79 |
* @param provider the service provider providing the service class. |
* listeners on the service and all references to it are released. |
80 |
* @param revokeNow whether to release all current references to |
* |
81 |
* the service. |
* @param serviceClass the service class to revoke. |
82 |
*/ |
* @param provider the service provider providing the service class. |
83 |
public void revokeService(Class serviceClass, BeanContextServiceProvider provider, boolean revokeNow); |
* @param revokeNow whether to release all current references to |
84 |
|
* the service. |
85 |
/** |
*/ |
86 |
* Release your copy of this service. |
public void revokeService (Class serviceClass, |
87 |
* <P> |
BeanContextServiceProvider provider, |
88 |
* |
boolean revokeNow); |
89 |
* If all copies of the service's class have been relinquished by |
|
90 |
* the requestor, the <code>BeanContextServiceRevokedListener</code> |
/** |
91 |
* previously registered by <code>getService()</code> will be |
* Release your copy of this service. |
92 |
* unregistered. |
* <P> |
93 |
* |
* |
94 |
* @param requestorChild the original <code>BeanContextChild</code> |
* If all copies of the service's class have been relinquished by |
95 |
* requesting the service. |
* the requestor, the <code>BeanContextServiceRevokedListener</code> |
96 |
* @param requestor the original requestor of the service. |
* previously registered by <code>getService()</code> will be |
97 |
* @param service the service to relinquish |
* unregistered. |
98 |
* @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener) |
* |
99 |
*/ |
* @param requestorChild the original <code>BeanContextChild</code> |
100 |
public void releaseService(BeanContextChild requestorChild, Object requestor, Object service); |
* requesting the service. |
101 |
|
* @param requestor the original requestor of the service. |
102 |
/** |
* @param service the service to relinquish |
103 |
* Get a service from this <code>BeanContextServices</code>. |
* @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener) |
104 |
* <P> |
*/ |
105 |
* |
public void releaseService (BeanContextChild requestorChild, Object requestor, |
106 |
* The specified listener will be registered to receive a |
Object service); |
107 |
* revocation notice for the specified serviceClass. One |
|
108 |
* notification per service class per requestor object will be |
/** |
109 |
* sent. |
* Get a service from this <code>BeanContextServices</code>. |
110 |
* <P> |
* <P> |
111 |
* |
* |
112 |
* The listener will be unregistered when all services that were |
* The specified listener will be registered to receive a |
113 |
* obtained by that requestor for that service class are released. |
* revocation notice for the specified serviceClass. One |
114 |
* <P> |
* notification per service class per requestor object will be |
115 |
* |
* sent. |
116 |
* If the requested service class is not available, or if this |
* <P> |
117 |
* <code>BeanContextServices</code> object chooses not honor the |
* |
118 |
* request because the service class has been revoked or for some |
* The listener will be unregistered when all services that were |
119 |
* other reason, then this method will return <code>null</code>. |
* obtained by that requestor for that service class are released. |
120 |
* <P> |
* <P> |
121 |
* |
* |
122 |
* This method may throw unchecked exceptions, so watch out. |
* If the requested service class is not available, or if this |
123 |
* |
* <code>BeanContextServices</code> object chooses not honor the |
124 |
* @specnote it is not specified what happens when two subsequent |
* request because the service class has been revoked or for some |
125 |
* calls are made to <code>getService()</code> with the |
* other reason, then this method will return <code>null</code>. |
126 |
* same requestor object and service class but different |
* <P> |
127 |
* listeners. Which listener is to be notified? |
* |
128 |
* |
* This method may throw unchecked exceptions, so watch out. |
129 |
* @param requestorChild the <code>BeanContextChild</code> |
* |
130 |
* associated with the requestor. Typically this will be |
* @specnote it is not specified what happens when two subsequent |
131 |
* the same as the requestor itself, but since any |
* calls are made to <code>getService()</code> with the |
132 |
* <code>Object</code>, even one outside the hierarchy, may |
* same requestor object and service class but different |
133 |
* make a request, this parameter is necessary. Only weak |
* listeners. Which listener is to be notified? |
134 |
* references to this will be retained, and it will never |
* |
135 |
* be changed, only queried in a read-only manner. |
* @param requestorChild the <code>BeanContextChild</code> |
136 |
* @param requestor the actual requestor of the service. Only |
* associated with the requestor. Typically this will be |
137 |
* weak references to this will be retained, and it will |
* the same as the requestor itself, but since any |
138 |
* never be changed, only queried in a read-only manner. |
* <code>Object</code>, even one outside the hierarchy, may |
139 |
* @param serviceClass the <code>Class</code> of the service being |
* make a request, this parameter is necessary. Only weak |
140 |
* requested. |
* references to this will be retained, and it will never |
141 |
* @param serviceSelector a parameter to customize the service |
* be changed, only queried in a read-only manner. |
142 |
* returned with. |
* @param requestor the actual requestor of the service. Only |
143 |
* @param listener a listener that will be notified if the service |
* weak references to this will be retained, and it will |
144 |
* being requested is revoked. |
* never be changed, only queried in a read-only manner. |
145 |
* @return an instance of <code>serviceClass</code> (such that |
* @param serviceClass the <code>Class</code> of the service being |
146 |
* <code>instanceof</code> serviceClass is true), or |
* requested. |
147 |
* <code>null</code>. |
* @param serviceSelector a parameter to customize the service |
148 |
*/ |
* returned with. |
149 |
public Object getService(BeanContextChild requestorChild, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener listener); |
* @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 |
* Get a list of all service classes supported. |
* <code>instanceof</code> serviceClass is true), or |
153 |
* <P> |
* <code>null</code>. |
154 |
* |
*/ |
155 |
* This method must synchronize on |
public Object getService (BeanContextChild requestorChild, Object requestor, |
156 |
* <code>BeanContext.globalHierarchyLock</code>. |
Class serviceClass, Object serviceSelector, |
157 |
* |
BeanContextServiceRevokedListener listener) |
158 |
* @return a list of all service classes supported. |
throws TooManyListenersException; |
159 |
* @see java.beans.beancontext.BeanContext#globalHierarchyLock |
|
160 |
*/ |
/** |
161 |
public Iterator getCurrentServiceClasses(); |
* Get a list of all service classes supported. |
162 |
|
* <P> |
163 |
/** |
* |
164 |
* Get a list of valid service selectors for the specified service class. |
* This method must synchronize on |
165 |
* <P> |
* <code>BeanContext.globalHierarchyLock</code>. |
166 |
* |
* |
167 |
* If the specified service class does not have a finite number of |
* @return a list of all service classes supported. |
168 |
* valid service selectors, it should return <code>null</code>. |
* @see java.beans.beancontext.BeanContext#globalHierarchyLock |
169 |
* If it takes a general <code>Integer</code> parameter, for |
*/ |
170 |
* example, you may as well return <code>null</code> or the poor |
public Iterator getCurrentServiceClasses (); |
171 |
* soul who called this method will be iterating all day. |
|
172 |
* <P> |
/** |
173 |
* |
* Get a list of valid service selectors for the specified service class. |
174 |
* If it has no valid service selectors, it should still return an empty |
* <P> |
175 |
* <code>Iterator</code>. |
* |
176 |
* |
* If the specified service class does not have a finite number of |
177 |
* @param serviceClass the service class to get selectors for. |
* valid service selectors, it should return <code>null</code>. |
178 |
* @return a list of valid service selectors for the service |
* If it takes a general <code>Integer</code> parameter, for |
179 |
* class, or <code>null</code>. |
* example, you may as well return <code>null</code> or the poor |
180 |
*/ |
* soul who called this method will be iterating all day. |
181 |
public Iterator getCurrentServiceSelectors(Class serviceClass); |
* <P> |
182 |
|
* |
183 |
/** |
* If it has no valid service selectors, it should still return an empty |
184 |
* Tell whether the specified service class is available. |
* <code>Iterator</code>. |
185 |
* Iff getService() could return a non-null value for the |
* |
186 |
* specified service, this method will return <code>true</code>. |
* @param serviceClass the service class to get selectors for. |
187 |
* |
* @return a list of valid service selectors for the service |
188 |
* @param serviceClass the service class to check on. |
* class, or <code>null</code>. |
189 |
* @return whether the specified service class is availabe. |
*/ |
190 |
*/ |
public Iterator getCurrentServiceSelectors (Class serviceClass); |
191 |
public boolean hasService(Class serviceClass); |
|
192 |
|
/** |
193 |
/** |
* Tell whether the specified service class is available. |
194 |
* Add a listener on all adds and removes of services. |
* Iff getService() could return a non-null value for the |
195 |
* @param listener the listener to add. |
* specified service, this method will return <code>true</code>. |
196 |
*/ |
* |
197 |
public void addBeanContextServicesListener(BeanContextServicesListener listener); |
* @param serviceClass the service class to check on. |
198 |
|
* @return whether the specified service class is available. |
199 |
/** |
*/ |
200 |
* Remove a listener on all adds and removes of services. |
public boolean hasService (Class serviceClass); |
201 |
* @specnote it is not certain whether this should remove this |
|
202 |
* listener if it was specified in |
/** |
203 |
* <code>getService()</code>. |
* Add a listener on all adds and removes of services. |
204 |
* @param listener the listener to add. |
* @param listener the listener to add. |
205 |
*/ |
*/ |
206 |
public void removeBeanContextServicesListener(BeanContextServicesListener listener); |
public void |
207 |
|
addBeanContextServicesListener (BeanContextServicesListener listener); |
208 |
|
|
209 |
|
/** |
210 |
|
* Remove a listener on all adds and removes of services. |
211 |
|
* @specnote it is not certain whether this should remove this |
212 |
|
* listener if it was specified in |
213 |
|
* <code>getService()</code>. |
214 |
|
* @param listener the listener to add. |
215 |
|
*/ |
216 |
|
public void |
217 |
|
removeBeanContextServicesListener (BeanContextServicesListener listener); |
218 |
} |
} |