1/* 2 * Copyright (c) 1998, 2014, 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 26package java.beans.beancontext; 27 28import java.util.Iterator; 29 30import java.util.TooManyListenersException; 31 32import java.beans.beancontext.BeanContext; 33 34import java.beans.beancontext.BeanContextServiceProvider; 35 36import 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 */ 45public interface BeanContextServices extends BeanContext, BeanContextServicesListener { 46 47 /** 48 * Adds a service to this BeanContext. 49 * {@code BeanContextServiceProvider}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} associates 53 * the service with the {@code BeanContextServiceProvider} and 54 * fires a {@code BeanContextServiceAvailableEvent} to all 55 * currently registered {@code BeanContextServicesListeners}. 56 * The method then returns {@code true}, 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}. 60 * @param serviceClass the service to add 61 * @param serviceProvider the {@code BeanContextServiceProvider} 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} fires a 72 * {@code BeanContextServiceRevokedEvent} to its 73 * list of currently registered 74 * {@code BeanContextServiceRevokedListeners} and 75 * {@code BeanContextServicesListeners}. 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} 80 * indicates an exceptional circumstance where the 81 * {@code BeanContextServiceProvider} or 82 * {@code BeanContextServices} 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}, or any arbitrary object 98 * associated with a {@code BeanContextChild}, may obtain 99 * a reference to a currently registered service from its 100 * nesting {@code BeanContextServices} 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}. 104 * @param child the {@code BeanContextChild} 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} 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} 115 */ 116 Object getService(BeanContextChild child, Object requestor, Class<?> serviceClass, Object serviceSelector, BeanContextServiceRevokedListener bcsrl) throws TooManyListenersException; 117 118 /** 119 * Releases a {@code BeanContextChild}'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}. 123 * @param child the {@code BeanContextChild} 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} 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} to this BeanContext 149 * @param bcsl the {@code BeanContextServicesListener} to add 150 */ 151 void addBeanContextServicesListener(BeanContextServicesListener bcsl); 152 153 /** 154 * Removes a {@code BeanContextServicesListener} 155 * from this {@code BeanContext} 156 * @param bcsl the {@code BeanContextServicesListener} 157 * to remove from this context 158 */ 159 void removeBeanContextServicesListener(BeanContextServicesListener bcsl); 160} 161