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 }