libjava/java/beans/beancontext/BeanContextServiceProvider.java

   1 /* java.beans.beancontext.BeanContextServiceProvider
   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 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.beans.beancontext;
  40
  41 import java.util.Iterator;
  42
  43 /**
  44  * An actual factory for services.
  45  * <P>
  46  *
  47  * It is the <code>BeanContextServiceProvider</code>'s responsibility to
  48  * register itself with whatever <code>BeanContextServices</code> object
  49  * it wishes to provide services through using the
  50  * <code>addService()</code> method.
  51  * <P>
  52  *
  53  * If for some reason it can no longer provide services for a particular
  54  * class, this class must invoke
  55  * <code>BeanContextServices.revokeService(serviceClass,this,true)</code>
  56  * for all the places it has registered the service.
  57  *
  58  * @author John Keiser
  59  * @since JDK1.2
  60  */
  61
  62 public interface BeanContextServiceProvider {
  63         /**
  64          * Get a service.
  65          * Called from <code>BeanContextServices.getService().
  66          * <P>
  67          *
  68          * If the requested service class is not available, or if this
  69          * <code>BeanContextServiceProvider</code> chooses not honor the
  70          * request for some reason, then this method will return
  71          * <code>null</code>.
  72          * <P>
  73          *
  74          * This method may throw unchecked exceptions, so watch out.
  75          *
  76          * @param services the <code>BeanContextServices</code> that wants
  77          *        to get the service.  Only weak references to this will
  78          *        be retained, and it will never be changed, only queried
  79          *        in a read-only manner.
  80          * @param requestor the actual requestor of the service.  Only
  81          *        weak references to this will be retained, and it will
  82          *        never be changed, only queried in a read-only manner.
  83          * @param serviceClass the <code>Class</code> of the service being
  84          *        requested.
  85          * @param serviceSelector a parameter to customize the service
  86          *        returned with.
  87          * @return an instance of <code>serviceClass</code> (such that
  88          *        <code>instanceof</code> serviceClass is true), or
  89          *        <code>null</code>.
  90          * @see java.beans.beancontext.BeanContextServices#getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)
  91          */
  92         Object getService(BeanContextServices services, Object requestor, Class serviceClass, Object serviceSelector);
  93
  94         /**
  95          * Release the service.
  96          * <P>
  97          *
  98          * Called by <code>BeanContextServices.releaseService()</code>.
  99          * <P>
 100          *
 101          * Most <code>BeanContextServiceProvider</code>s won't have to do
 102          * anything here.
 103          *
 104          * @param services the <code>BeanContextServices</code> that wants
 105          *        to release the service.  Only weak references to this will
 106          *        be retained, and it will never be changed, only queried
 107          *        in a read-only manner.
 108          * @param requestor the original requestor of the service.
 109          * @param service the service to relinquish
 110          * @see java.beans.beancontext.BeanContextServices#releaseService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Object)
 111          */
 112         void releaseService(BeanContextServices services, Object requestor, Object service);
 113
 114         /**
 115          * Get a list of valid service selectors for the specified service class.
 116          * This method is called from
 117          * <code>BeanContextServices.getCurrentServiceSelectors()</code>.
 118          * <P>
 119          *
 120          * If the specified service class does not have a finite number of
 121          * valid service selectors, it should return <code>null</code>.
 122          * If it takes a general <code>Integer</code> parameter, for
 123          * example, you may as well return <code>null</code> or the poor
 124          * soul who called this method will be iterating all day.
 125          * <P>
 126          *
 127          * If it has no valid service selectors, it should still return an empty
 128          * <code>Iterator</code>.
 129          *
 130          * @param services the <code>BeanContextServices</code> that wants
 131          *        to get the service selectors.  Only weak references to this will
 132          *        be retained, and it will never be changed, only queried
 133          *        in a read-only manner.
 134          * @param serviceClass the service class to get selectors for.
 135          * @return a list of valid service selectors for the service
 136          *         class, or <code>null</code>.
 137          * @see java.beans.beancontext.BeanContextServices#getCurrentServiceSelectors(java.lang.Class)
 138          */
 139         Iterator getCurrentServiceSelectors(BeanContextServices services, Class serviceClass);
 140 }