Java tutorial
/* * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.beans.beancontext; import java.util.Iterator; import java.util.TooManyListenersException; import java.beans.beancontext.BeanContext; import java.beans.beancontext.BeanContextServiceProvider; import java.beans.beancontext.BeanContextServicesListener; /** * <p> * The BeanContextServices interface provides a mechanism for a BeanContext * to expose generic "services" to the BeanContextChild objects within. * </p> */ public interface BeanContextServices extends BeanContext, BeanContextServicesListener { /** * Adds a service to this BeanContext. * {@code BeanContextServiceProvider}s call this method * to register a particular service with this context. * If the service has not previously been added, the * {@code BeanContextServices} associates * the service with the {@code BeanContextServiceProvider} and * fires a {@code BeanContextServiceAvailableEvent} to all * currently registered {@code BeanContextServicesListeners}. * The method then returns {@code true}, indicating that * the addition of the service was successful. * If the given service has already been added, this method * simply returns {@code false}. * @param serviceClass the service to add * @param serviceProvider the {@code BeanContextServiceProvider} * associated with the service * @return true if the service was successful added, false otherwise */ boolean addService(Class<?> serviceClass, BeanContextServiceProvider serviceProvider); /** * BeanContextServiceProviders wishing to remove * a currently registered service from this context * may do so via invocation of this method. Upon revocation of * the service, the {@code BeanContextServices} fires a * {@code BeanContextServiceRevokedEvent} to its * list of currently registered * {@code BeanContextServiceRevokedListeners} and * {@code BeanContextServicesListeners}. * @param serviceClass the service to revoke from this BeanContextServices * @param serviceProvider the BeanContextServiceProvider associated with * this particular service that is being revoked * @param revokeCurrentServicesNow a value of {@code true} * indicates an exceptional circumstance where the * {@code BeanContextServiceProvider} or * {@code BeanContextServices} wishes to immediately * terminate service to all currently outstanding references * to the specified service. */ void revokeService(Class<?> serviceClass, BeanContextServiceProvider serviceProvider, boolean revokeCurrentServicesNow); /** * Reports whether or not a given service is * currently available from this context. * @param serviceClass the service in question * @return true if the service is available */ boolean hasService(Class<?> serviceClass); /** * A {@code BeanContextChild}, or any arbitrary object * associated with a {@code BeanContextChild}, may obtain * a reference to a currently registered service from its * nesting {@code BeanContextServices} * via invocation of this method. When invoked, this method * gets the service by calling the getService() method on the * underlying {@code BeanContextServiceProvider}. * @param child the {@code BeanContextChild} * associated with this request * @param requestor the object requesting the service * @param serviceClass class of the requested service * @param serviceSelector the service dependent parameter * @param bcsrl the * {@code BeanContextServiceRevokedListener} to notify * if the service should later become revoked * @throws TooManyListenersException if there are too many listeners * @return a reference to this context's named * Service as requested or {@code null} */ Object getService(BeanContextChild child, Object requestor, Class<?> serviceClass, Object serviceSelector, BeanContextServiceRevokedListener bcsrl) throws TooManyListenersException; /** * Releases a {@code BeanContextChild}'s * (or any arbitrary object associated with a BeanContextChild) * reference to the specified service by calling releaseService() * on the underlying {@code BeanContextServiceProvider}. * @param child the {@code BeanContextChild} * @param requestor the requestor * @param service the service */ void releaseService(BeanContextChild child, Object requestor, Object service); /** * Gets the currently available services for this context. * @return an {@code Iterator} consisting of the * currently available services */ Iterator<?> getCurrentServiceClasses(); /** * Gets the list of service dependent service parameters * (Service Selectors) for the specified service, by * calling getCurrentServiceSelectors() on the * underlying BeanContextServiceProvider. * @param serviceClass the specified service * @return the currently available service selectors * for the named serviceClass */ Iterator<?> getCurrentServiceSelectors(Class<?> serviceClass); /** * Adds a {@code BeanContextServicesListener} to this BeanContext * @param bcsl the {@code BeanContextServicesListener} to add */ void addBeanContextServicesListener(BeanContextServicesListener bcsl); /** * Removes a {@code BeanContextServicesListener} * from this {@code BeanContext} * @param bcsl the {@code BeanContextServicesListener} * to remove from this context */ void removeBeanContextServicesListener(BeanContextServicesListener bcsl); }