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  ;
11  
12  import java.util.TooManyListenersException  ;
13  
14  import java.beans.beancontext.BeanContext  ;
15  
16  import java.beans.beancontext.BeanContextServiceProvider  ;
17  
18  import java.beans.beancontext.BeanContextServicesListener  ;
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  , BeanContextServicesListener   {
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   serviceClass, BeanContextServiceProvider   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   serviceClass, BeanContextServiceProvider   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   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   getService(BeanContextChild   child, Object   requestor, Class   serviceClass, Object   serviceSelector, BeanContextServiceRevokedListener   bcsrl) throws TooManyListenersException  ;
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   child, Object   requestor, Object   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   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   getCurrentServiceSelectors(Class   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   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   bcsl);
141 }
142
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags