ajava.beans.beancontext.BeanContextServices Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of a-javabeans8 Show documentation
Adapted (moved from java.beans to ajava.beans) OpenJDK8 javabeans for Android. It's used by A-Jetty (Jetty 9.2 adapted for Android.)
The newest version!
/*
 * Copyright (c) 1998, 2013, 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 ajava.beans.beancontext;

import java.util.Iterator;

import java.util.TooManyListenersException;

import ajava.beans.beancontext.BeanContext;

import ajava.beans.beancontext.BeanContextServiceProvider;

import ajava.beans.beancontext.BeanContextServicesListener;


/**
 * 
 * The BeanContextServices interface provides a mechanism for a BeanContext
 * to expose generic "services" to the BeanContextChild objects within.
 * 
 */
public interface BeanContextServices extends BeanContext, BeanContextServicesListener {

    /**
     * Adds a service to this BeanContext.
     * BeanContextServiceProviders call this method
     * to register a particular service with this context.
     * If the service has not previously been added, the
     * BeanContextServices associates
     * the service with the BeanContextServiceProvider and
     * fires a BeanContextServiceAvailableEvent to all
     * currently registered BeanContextServicesListeners.
     * The method then returns true, indicating that
     * the addition of the service was successful.
     * If the given service has already been added, this method
     * simply returns false.
     * @param serviceClass     the service to add
     * @param serviceProvider  the 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 BeanContextServices fires a
     * BeanContextServiceRevokedEvent to its
     * list of currently registered
     * BeanContextServiceRevokedListeners and
     * 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 true
     * indicates an exceptional circumstance where the
     * BeanContextServiceProvider or
     * 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 BeanContextChild, or any arbitrary object
     * associated with a BeanContextChild, may obtain
     * a reference to a currently registered service from its
     * nesting BeanContextServices
     * via invocation of this method. When invoked, this method
     * gets the service by calling the getService() method on the
     * underlying BeanContextServiceProvider.
     * @param child the 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
     * 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 null
     */
    Object getService(BeanContextChild child, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener bcsrl) throws TooManyListenersException;

    /**
     * Releases a BeanContextChild's
     * (or any arbitrary object associated with a BeanContextChild)
     * reference to the specified service by calling releaseService()
     * on the underlying BeanContextServiceProvider.
     * @param child the 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 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 BeanContextServicesListener to this BeanContext
     * @param bcsl the BeanContextServicesListener to add
     */
    void addBeanContextServicesListener(BeanContextServicesListener bcsl);

    /**
     * Removes a BeanContextServicesListener
     * from this BeanContext
     * @param bcsl the BeanContextServicesListener
     * to remove from this context
     */
    void removeBeanContextServicesListener(BeanContextServicesListener bcsl);
}