1 /* 2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.beans.beancontext; 27 28 import java.util.Iterator; 29 30 import java.util.TooManyListenersException; 31 32 import java.beans.beancontext.BeanContext; 33 34 import java.beans.beancontext.BeanContextServiceProvider; 35 36 import java.beans.beancontext.BeanContextServicesListener; 37 38 39 /** 40 * <p> 41 * The BeanContextServices interface provides a mechanism for a BeanContext 42 * to expose generic "services" to the BeanContextChild objects within. 43 * </p> 44 */ 45 public interface BeanContextServices extends BeanContext, BeanContextServicesListener { 46 47 /** 48 * Adds a service to this BeanContext. 49 * <code>BeanContextServiceProvider</code>s call this method 50 * to register a particular service with this context. 51 * If the service has not previously been added, the 52 * <code>BeanContextServices</code> associates 53 * the service with the <code>BeanContextServiceProvider</code> and 54 * fires a <code>BeanContextServiceAvailableEvent</code> to all 55 * currently registered <code>BeanContextServicesListeners</code>. 56 * The method then returns <code>true</code>, indicating that 57 * the addition of the service was successful. 58 * If the given service has already been added, this method 59 * simply returns <code>false</code>. 60 * @param serviceClass the service to add 61 * @param serviceProvider the <code>BeanContextServiceProvider</code> 62 * associated with the service 63 * @return true if the service was successful added, false otherwise 64 */ 65 boolean addService(Class serviceClass, BeanContextServiceProvider serviceProvider); 66 67 /** 68 * BeanContextServiceProviders wishing to remove 69 * a currently registered service from this context 70 * may do so via invocation of this method. Upon revocation of 71 * the service, the <code>BeanContextServices</code> fires a 72 * <code>BeanContextServiceRevokedEvent</code> to its 73 * list of currently registered 74 * <code>BeanContextServiceRevokedListeners</code> and 75 * <code>BeanContextServicesListeners</code>. 76 * @param serviceClass the service to revoke from this BeanContextServices 77 * @param serviceProvider the BeanContextServiceProvider associated with 78 * this particular service that is being revoked 79 * @param revokeCurrentServicesNow a value of <code>true</code> 80 * indicates an exceptional circumstance where the 81 * <code>BeanContextServiceProvider</code> or 82 * <code>BeanContextServices</code> wishes to immediately 83 * terminate service to all currently outstanding references 84 * to the specified service. 85 */ 86 void revokeService(Class serviceClass, BeanContextServiceProvider serviceProvider, boolean revokeCurrentServicesNow); 87 88 /** 89 * Reports whether or not a given service is 90 * currently available from this context. 91 * @param serviceClass the service in question 92 * @return true if the service is available 93 */ 94 boolean hasService(Class serviceClass); 95 96 /** 97 * A <code>BeanContextChild</code>, or any arbitrary object 98 * associated with a <code>BeanContextChild</code>, may obtain 99 * a reference to a currently registered service from its 100 * nesting <code>BeanContextServices</code> 101 * via invocation of this method. When invoked, this method 102 * gets the service by calling the getService() method on the 103 * underlying <code>BeanContextServiceProvider</code>. 104 * @param child the <code>BeanContextChild</code> 105 * associated with this request 106 * @param requestor the object requesting the service 107 * @param serviceClass class of the requested service 108 * @param serviceSelector the service dependent parameter 109 * @param bcsrl the 110 * <code>BeanContextServiceRevokedListener</code> to notify 111 * if the service should later become revoked 112 * @throws TooManyListenersException if there are too many listeners 113 * @return a reference to this context's named 114 * Service as requested or <code>null</code> 115 */ 116 Object getService(BeanContextChild child, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener bcsrl) throws TooManyListenersException; 117 118 /** 119 * Releases a <code>BeanContextChild</code>'s 120 * (or any arbitrary object associated with a BeanContextChild) 121 * reference to the specified service by calling releaseService() 122 * on the underlying <code>BeanContextServiceProvider</code>. 123 * @param child the <code>BeanContextChild</code> 124 * @param requestor the requestor 125 * @param service the service 126 */ 127 void releaseService(BeanContextChild child, Object requestor, Object service); 128 129 /** 130 * Gets the currently available services for this context. 131 * @return an <code>Iterator</code> consisting of the 132 * currently available services 133 */ 134 Iterator getCurrentServiceClasses(); 135 136 /** 137 * Gets the list of service dependent service parameters 138 * (Service Selectors) for the specified service, by 139 * calling getCurrentServiceSelectors() on the 140 * underlying BeanContextServiceProvider. 141 * @param serviceClass the specified service 142 * @return the currently available service selectors 143 * for the named serviceClass 144 */ 145 Iterator getCurrentServiceSelectors(Class serviceClass); 146 147 /** 148 * Adds a <code>BeanContextServicesListener</code> to this BeanContext 149 * @param bcsl the <code>BeanContextServicesListener</code> to add 150 */ 151 void addBeanContextServicesListener(BeanContextServicesListener bcsl); 152 153 /** 154 * Removes a <code>BeanContextServicesListener</code> 155 * from this <code>BeanContext</code> 156 * @param bcsl the <code>BeanContextServicesListener</code> 157 * to remove from this context 158 */ 159 void removeBeanContextServicesListener(BeanContextServicesListener bcsl); 160 }