libjava/java/beans/beancontext/BeanContextServices.java

   1 /* java.beans.beancontext.BeanContextServices
   2    Copyright (C) 1999 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 As a special exception, if you link this library with other files to
  22 produce an executable, this library does not by itself cause the
  23 resulting executable to be covered by the GNU General Public License.
  24 This exception does not however invalidate any other reasons why the
  25 executable file might be covered by the GNU General Public License. */
  26
  27
  28 package java.beans.beancontext;
  29
  30 import java.util.Iterator;
  31
  32 /**
  33  * Allows a <code>BeanContext</code> to provide services to its children.
  34  *
  35  * @specnote it is unclear whether a <code>BeanContextServices</code>
  36  *           should delegate unhandled requests to parents.  I assume so.
  37  * @author John Keiser
  38  * @since JDK1.2
  39  */
  40
  41 public interface BeanContextServices extends BeanContext, BeanContextServicesListener {
  42         /**
  43          * Register a service to make it available to others.
  44          * This class may refuse to add the service based on whatever
  45          * information it can gather, including whether the service
  46          * provider is trusted.
  47          *
  48          * @param serviceClass the service class.
  49          * @param provider the factory that will actually provide the service.
  50          * @return whether the service was added or not.
  51          */
  52         public boolean addService(Class serviceClass, BeanContextServiceProvider provider);
  53
  54         /**
  55          * Make it so that no one else can use this service.
  56          * <P>
  57          *
  58          * If <code>revokeNow</code> is <code>false</code>, the only
  59          * effect of this method is to make all subsequent calls to
  60          * <code>getService()</code> on this service class fail.
  61          * <P>
  62          *
  63          * If it is <code>true</code>, a message is also sent out to all
  64          * listeners on the service and all references to it are released.
  65          *
  66          * @param serviceClass the service class to revoke.
  67          * @param provider the service provider providing the service class.
  68          * @param revokeNow whether to release all current references to
  69          *        the service.
  70          */
  71         public void revokeService(Class serviceClass, BeanContextServiceProvider provider, boolean revokeNow);
  72
  73         /**
  74          * Release your copy of this service.
  75          * <P>
  76          *
  77          * If all copies of the service's class have been relinquished by
  78          * the requestor, the <code>BeanContextServiceRevokedListener</code>
  79          * previously registered by <code>getService()</code> will be
  80          * unregistered.
  81          *
  82          * @param requestorChild the original <code>BeanContextChild</code>
  83          *        requesting the service.
  84          * @param requestor the original requestor of the service.
  85          * @param service the service to relinquish
  86          * @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)
  87          */
  88         public void releaseService(BeanContextChild requestorChild, Object requestor, Object service);
  89
  90         /**
  91          * Get a service from this <code>BeanContextServices</code>.
  92          * <P>
  93          *
  94          * The specified listener will be registered to receive a
  95          * revocation notice for the specified serviceClass.  One
  96          * notification per service class per requestor object will be
  97          * sent.
  98          * <P>
  99          *
 100          * The listener will be unregistered when all services that were
 101          * obtained by that requestor for that service class are released.
 102          * <P>
 103          *
 104          * If the requested service class is not available, or if this
 105          * <code>BeanContextServices</code> object chooses not honor the
 106          * request because the service class has been revoked or for some
 107          * other reason, then this method will return <code>null</code>.
 108          * <P>
 109          *
 110          * This method may throw unchecked exceptions, so watch out.
 111          *
 112          * @specnote it is not specified what happens when two subsequent
 113          *           calls are made to <code>getService()</code> with the
 114          *           same requestor object and service class but different
 115          *           listeners.  Which listener is to be notified?
 116          *
 117          * @param requestorChild the <code>BeanContextChild</code>
 118          *        associated with the requestor.  Typically this will be
 119          *        the same as the requestor itself, but since any
 120          *        <code>Object</code>, even one outside the hierarchy, may
 121          *        make a request, this parameter is necessary.  Only weak
 122          *        references to this will be retained, and it will never
 123          *        be changed, only queried in a read-only manner.
 124          * @param requestor the actual requestor of the service.  Only
 125          *        weak references to this will be retained, and it will
 126          *        never be changed, only queried in a read-only manner.
 127          * @param serviceClass the <code>Class</code> of the service being
 128          *        requested.
 129          * @param serviceSelector a parameter to customize the service
 130          *        returned with.
 131          * @param listener a listener that will be notified if the service
 132          *        being requested is revoked.
 133          * @return an instance of <code>serviceClass</code> (such that
 134          *        <code>instanceof</code> serviceClass is true), or
 135          *        <code>null</code>.
 136          */
 137         public Object getService(BeanContextChild requestorChild, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener listener);
 138
 139         /**
 140          * Get a list of all service classes supported.
 141          * <P>
 142          *
 143          * This method must synchronize on
 144          * <code>BeanContext.globalHierarchyLock</code>.
 145          *
 146          * @return a list of all service classes supported.
 147          * @see java.beans.beancontext.BeanContext#globalHierarchyLock
 148          */
 149         public Iterator getCurrentServiceClasses();
 150
 151         /**
 152          * Get a list of valid service selectors for the specified service class.
 153          * <P>
 154          *
 155          * If the specified service class does not have a finite number of
 156          * valid service selectors, it should return <code>null</code>.
 157          * If it takes a general <code>Integer</code> parameter, for
 158          * example, you may as well return <code>null</code> or the poor
 159          * soul who called this method will be iterating all day.
 160          * <P>
 161          *
 162          * If it has no valid service selectors, it should still return an empty
 163          * <code>Iterator</code>.
 164          *
 165          * @param serviceClass the service class to get selectors for.
 166          * @return a list of valid service selectors for the service
 167          *         class, or <code>null</code>.
 168          */
 169         public Iterator getCurrentServiceSelectors(Class serviceClass);
 170
 171         /**
 172          * Tell whether the specified service class is available.
 173          * Iff getService() could return a non-null value for the
 174          * specified service, this method will return <code>true</code>.
 175          *
 176          * @param serviceClass the service class to check on.
 177          * @return whether the specified service class is availabe.
 178          */
 179         public boolean hasService(Class serviceClass);
 180
 181         /**
 182          * Add a listener on all adds and removes of services.
 183          * @param listener the listener to add.
 184          */
 185         public void addBeanContextServicesListener(BeanContextServicesListener listener);
 186
 187         /**
 188          * Remove a listener on all adds and removes of services.
 189          * @specnote it is not certain whether this should remove this
 190          *           listener if it was specified in
 191          *           <code>getService()</code>.
 192          * @param listener the listener to add.
 193          */
 194         public void removeBeanContextServicesListener(BeanContextServicesListener listener);
 195 }