KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > beans > beancontext > BeanContextServices


1 /*
2  * @(#)BeanContextServices.java 1.10 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.beans.beancontext;
9
10 import java.util.Iterator JavaDoc;
11
12 import java.util.TooManyListenersException JavaDoc;
13
14 import java.beans.beancontext.BeanContext JavaDoc;
15
16 import java.beans.beancontext.BeanContextServiceProvider JavaDoc;
17
18 import java.beans.beancontext.BeanContextServicesListener JavaDoc;
19
20
21 /**
22  * <p>
23  * The BeanContextServices interface provides a mechanism for a BeanContext
24  * to expose generic "services" to the BeanContextChild objects within.
25  * </p>
26  */

27 public interface BeanContextServices extends BeanContext JavaDoc, BeanContextServicesListener JavaDoc {
28
29     /**
30      * Adds a service to this BeanContext.
31      * <code>BeanContextServiceProvider</code>s call this method
32      * to register a particular service with this context.
33      * If the service has not previously been added, the
34      * <code>BeanContextServices</code> associates
35      * the service with the <code>BeanContextServiceProvider</code> and
36      * fires a <code>BeanContextServiceAvailableEvent</code> to all
37      * currently registered <code>BeanContextServicesListeners</code>.
38      * The method then returns <code>true</code>, indicating that
39      * the addition of the service was successful.
40      * If the given service has already been added, this method
41      * simply returns <code>false</code>.
42      * @param serviceClass the service to add
43      * @param serviceProvider the <code>BeanContextServiceProvider</code>
44      * associated with the service
45      */

46     boolean addService(Class JavaDoc serviceClass, BeanContextServiceProvider JavaDoc serviceProvider);
47
48     /**
49      * BeanContextServiceProviders wishing to remove
50      * a currently registered service from this context
51      * may do so via invocation of this method. Upon revocation of
52      * the service, the <code>BeanContextServices</code> fires a
53      * <code>BeanContextServiceRevokedEvent</code> to its
54      * list of currently registered
55      * <code>BeanContextServiceRevokedListeners</code> and
56      * <code>BeanContextServicesListeners</code>.
57      * @param serviceClass the service to revoke from this BeanContextServices
58      * @param serviceProvider the BeanContextServiceProvider associated with
59      * this particular service that is being revoked
60      * @param revokeCurrentServicesNow a value of <code>true</code>
61      * indicates an exceptional circumstance where the
62      * <code>BeanContextServiceProvider</code> or
63      * <code>BeanContextServices</code> wishes to immediately
64      * terminate service to all currently outstanding references
65      * to the specified service.
66      */

67     void revokeService(Class JavaDoc serviceClass, BeanContextServiceProvider JavaDoc serviceProvider, boolean revokeCurrentServicesNow);
68
69     /**
70      * Reports whether or not a given service is
71      * currently available from this context.
72      * @param serviceClass the service in question
73      * @return true if the service is available
74      */

75     boolean hasService(Class JavaDoc serviceClass);
76
77     /**
78      * A <code>BeanContextChild</code>, or any arbitrary object
79      * associated with a <code>BeanContextChild</code>, may obtain
80      * a reference to a currently registered service from its
81      * nesting <code>BeanContextServices</code>
82      * via invocation of this method. When invoked, this method
83      * gets the service by calling the getService() method on the
84      * underlying <code>BeanContextServiceProvider</code>.
85      * @param child the <code>BeanContextChild</code>
86      * associated with this request
87      * @param requestor the object requesting the service
88      * @param serviceClass class of the requested service
89      * @param serviceSelector the service dependent parameter
90      * @param bcsrl the
91      * <code>BeanContextServiceRevokedListener</code> to notify
92      * if the service should later become revoked
93      * @throws TooManyListenersException
94      * @return a reference to this context's named
95      * Service as requested or <code>null</code>
96      */

97     Object JavaDoc getService(BeanContextChild JavaDoc child, Object JavaDoc requestor, Class JavaDoc serviceClass, Object JavaDoc serviceSelector, BeanContextServiceRevokedListener JavaDoc bcsrl) throws TooManyListenersException JavaDoc;
98
99     /**
100      * Releases a <code>BeanContextChild</code>'s
101      * (or any arbitrary object associated with a BeanContextChild)
102      * reference to the specified service by calling releaseService()
103      * on the underlying <code>BeanContextServiceProvider</code>.
104      * @param child the <code>BeanContextChild</code>
105      * @param requestor the requestor
106      * @param service the service
107      */

108     void releaseService(BeanContextChild JavaDoc child, Object JavaDoc requestor, Object JavaDoc service);
109
110     /**
111      * Gets the currently available services for this context.
112      * @return an <code>Iterator</code> consisting of the
113      * currently available services
114      */

115     Iterator JavaDoc getCurrentServiceClasses();
116
117     /**
118      * Gets the list of service dependent service parameters
119      * (Service Selectors) for the specified service, by
120      * calling getCurrentServiceSelectors() on the
121      * underlying BeanContextServiceProvider.
122      * @param serviceClass the specified service
123      * @return the currently available service selectors
124      * for the named serviceClass
125      */

126     Iterator JavaDoc getCurrentServiceSelectors(Class JavaDoc serviceClass);
127
128     /**
129      * Adds a <code>BeanContextServicesListener</code> to this BeanContext
130      * @param bcsl the <code>BeanContextServicesListener</code> to add
131      */

132     void addBeanContextServicesListener(BeanContextServicesListener JavaDoc bcsl);
133
134     /**
135      * Removes a <code>BeanContextServicesListener</code>
136      * from this <code>BeanContext</code>
137      * @param bcsl the <code>BeanContextServicesListener</code>
138      * to remove from this context
139      */

140     void removeBeanContextServicesListener(BeanContextServicesListener JavaDoc bcsl);
141 }
142
Popular Tags