/[classpath]/classpath/java/beans/beancontext/BeanContextServices.java
ViewVC logotype

Diff of /classpath/java/beans/beancontext/BeanContextServices.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.3 by mark, Tue Jan 22 22:26:59 2002 UTC revision 1.4 by mkoch, Tue Mar 18 13:30:21 2003 UTC
# Line 39  exception statement from your version. * Line 39  exception statement from your version. *
39  package java.beans.beancontext;  package java.beans.beancontext;
40    
41  import java.util.Iterator;  import java.util.Iterator;
42    import java.util.TooManyListenersException;
43    
44  /**  /**
45   * Allows a <code>BeanContext</code> to provide services to its children.   * Allows a <code>BeanContext</code> to provide services to its children.
# Line 46  import java.util.Iterator; Line 47  import java.util.Iterator;
47   * @specnote it is unclear whether a <code>BeanContextServices</code>   * @specnote it is unclear whether a <code>BeanContextServices</code>
48   *           should delegate unhandled requests to parents.  I assume so.   *           should delegate unhandled requests to parents.  I assume so.
49   * @author John Keiser   * @author John Keiser
50   * @since JDK1.2   * @since 1.2
51   */   */
52    
53  public interface BeanContextServices extends BeanContext, BeanContextServicesListener {  public interface BeanContextServices
54          /**    extends BeanContext, BeanContextServicesListener
55           * Register a service to make it available to others.  {
56           * This class may refuse to add the service based on whatever    /**
57           * information it can gather, including whether the service     * Register a service to make it available to others.
58           * provider is trusted.     * This class may refuse to add the service based on whatever
59           *     * information it can gather, including whether the service
60           * @param serviceClass the service class.     * provider is trusted.
61           * @param provider the factory that will actually provide the service.     *
62           * @return whether the service was added or not.     * @param serviceClass the service class.
63           */     * @param provider the factory that will actually provide the service.
64          public boolean addService(Class serviceClass, BeanContextServiceProvider provider);     * @return whether the service was added or not.
65       */
66          /**    public boolean addService (Class serviceClass,
67           * Make it so that no one else can use this service.                               BeanContextServiceProvider provider);
68           * <P>  
69           *    /**
70           * If <code>revokeNow</code> is <code>false</code>, the only     * Make it so that no one else can use this service.
71           * effect of this method is to make all subsequent calls to     * <P>
72           * <code>getService()</code> on this service class fail.     *
73           * <P>     * If <code>revokeNow</code> is <code>false</code>, the only
74           *     * effect of this method is to make all subsequent calls to
75           * If it is <code>true</code>, a message is also sent out to all     * <code>getService()</code> on this service class fail.
76           * listeners on the service and all references to it are released.     * <P>
77           *     *
78           * @param serviceClass the service class to revoke.     * If it is <code>true</code>, a message is also sent out to all
79           * @param provider the service provider providing the service class.     * listeners on the service and all references to it are released.
80           * @param revokeNow whether to release all current references to     *
81           *        the service.     * @param serviceClass the service class to revoke.
82           */     * @param provider the service provider providing the service class.
83          public void revokeService(Class serviceClass, BeanContextServiceProvider provider, boolean revokeNow);     * @param revokeNow whether to release all current references to
84       *        the service.
85          /**     */
86           * Release your copy of this service.    public void revokeService (Class serviceClass,
87           * <P>                               BeanContextServiceProvider provider,
88           *                               boolean revokeNow);
89           * If all copies of the service's class have been relinquished by  
90           * the requestor, the <code>BeanContextServiceRevokedListener</code>    /**
91           * previously registered by <code>getService()</code> will be     * Release your copy of this service.
92           * unregistered.     * <P>
93           *     *
94           * @param requestorChild the original <code>BeanContextChild</code>     * If all copies of the service's class have been relinquished by
95           *        requesting the service.     * the requestor, the <code>BeanContextServiceRevokedListener</code>
96           * @param requestor the original requestor of the service.     * previously registered by <code>getService()</code> will be
97           * @param service the service to relinquish     * unregistered.
98           * @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)     *
99           */     * @param requestorChild the original <code>BeanContextChild</code>
100          public void releaseService(BeanContextChild requestorChild, Object requestor, Object service);     *        requesting the service.
101       * @param requestor the original requestor of the service.
102          /**     * @param service the service to relinquish
103           * Get a service from this <code>BeanContextServices</code>.     * @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)
104           * <P>     */
105           *    public void releaseService (BeanContextChild requestorChild, Object requestor,
106           * The specified listener will be registered to receive a                                Object service);
107           * revocation notice for the specified serviceClass.  One  
108           * notification per service class per requestor object will be    /**
109           * sent.     * Get a service from this <code>BeanContextServices</code>.
110           * <P>     * <P>
111           *     *
112           * The listener will be unregistered when all services that were     * The specified listener will be registered to receive a
113           * obtained by that requestor for that service class are released.     * revocation notice for the specified serviceClass.  One
114           * <P>     * notification per service class per requestor object will be
115           *     * sent.
116           * If the requested service class is not available, or if this     * <P>
117           * <code>BeanContextServices</code> object chooses not honor the     *
118           * request because the service class has been revoked or for some     * The listener will be unregistered when all services that were
119           * other reason, then this method will return <code>null</code>.     * obtained by that requestor for that service class are released.
120           * <P>     * <P>
121           *     *
122           * This method may throw unchecked exceptions, so watch out.     * If the requested service class is not available, or if this
123           *     * <code>BeanContextServices</code> object chooses not honor the
124           * @specnote it is not specified what happens when two subsequent     * request because the service class has been revoked or for some
125           *           calls are made to <code>getService()</code> with the     * other reason, then this method will return <code>null</code>.
126           *           same requestor object and service class but different     * <P>
127           *           listeners.  Which listener is to be notified?     *
128           *     * This method may throw unchecked exceptions, so watch out.
129           * @param requestorChild the <code>BeanContextChild</code>     *
130           *        associated with the requestor.  Typically this will be     * @specnote it is not specified what happens when two subsequent
131           *        the same as the requestor itself, but since any     *           calls are made to <code>getService()</code> with the
132           *        <code>Object</code>, even one outside the hierarchy, may     *           same requestor object and service class but different
133           *        make a request, this parameter is necessary.  Only weak     *           listeners.  Which listener is to be notified?
134           *        references to this will be retained, and it will never     *
135           *        be changed, only queried in a read-only manner.     * @param requestorChild the <code>BeanContextChild</code>
136           * @param requestor the actual requestor of the service.  Only     *        associated with the requestor.  Typically this will be
137           *        weak references to this will be retained, and it will     *        the same as the requestor itself, but since any
138           *        never be changed, only queried in a read-only manner.     *        <code>Object</code>, even one outside the hierarchy, may
139           * @param serviceClass the <code>Class</code> of the service being     *        make a request, this parameter is necessary.  Only weak
140           *        requested.     *        references to this will be retained, and it will never
141           * @param serviceSelector a parameter to customize the service     *        be changed, only queried in a read-only manner.
142           *        returned with.     * @param requestor the actual requestor of the service.  Only
143           * @param listener a listener that will be notified if the service     *        weak references to this will be retained, and it will
144           *        being requested is revoked.     *        never be changed, only queried in a read-only manner.
145           * @return an instance of <code>serviceClass</code> (such that     * @param serviceClass the <code>Class</code> of the service being
146           *        <code>instanceof</code> serviceClass is true), or     *        requested.
147           *        <code>null</code>.     * @param serviceSelector a parameter to customize the service
148           */     *        returned with.
149          public Object getService(BeanContextChild requestorChild, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener listener);     * @param listener a listener that will be notified if the service
150       *        being requested is revoked.
151          /**     * @return an instance of <code>serviceClass</code> (such that
152           * Get a list of all service classes supported.     *        <code>instanceof</code> serviceClass is true), or
153           * <P>     *        <code>null</code>.
154           *     */
155           * This method must synchronize on    public Object getService (BeanContextChild requestorChild, Object requestor,
156           * <code>BeanContext.globalHierarchyLock</code>.                              Class serviceClass, Object serviceSelector,
157           *                              BeanContextServiceRevokedListener listener)
158           * @return a list of all service classes supported.      throws TooManyListenersException;
159           * @see java.beans.beancontext.BeanContext#globalHierarchyLock  
160           */    /**
161          public Iterator getCurrentServiceClasses();     * Get a list of all service classes supported.
162       * <P>
163          /**     *
164           * Get a list of valid service selectors for the specified service class.     * This method must synchronize on
165           * <P>     * <code>BeanContext.globalHierarchyLock</code>.
166           *     *
167           * If the specified service class does not have a finite number of     * @return a list of all service classes supported.
168           * valid service selectors, it should return <code>null</code>.     * @see java.beans.beancontext.BeanContext#globalHierarchyLock
169           * If it takes a general <code>Integer</code> parameter, for     */
170           * example, you may as well return <code>null</code> or the poor    public Iterator getCurrentServiceClasses ();
171           * soul who called this method will be iterating all day.  
172           * <P>    /**
173           *     * Get a list of valid service selectors for the specified service class.
174           * If it has no valid service selectors, it should still return an empty     * <P>
175           * <code>Iterator</code>.     *
176           *     * If the specified service class does not have a finite number of
177           * @param serviceClass the service class to get selectors for.     * valid service selectors, it should return <code>null</code>.
178           * @return a list of valid service selectors for the service     * If it takes a general <code>Integer</code> parameter, for
179           *         class, or <code>null</code>.     * example, you may as well return <code>null</code> or the poor
180           */     * soul who called this method will be iterating all day.
181          public Iterator getCurrentServiceSelectors(Class serviceClass);     * <P>
182       *
183          /**     * If it has no valid service selectors, it should still return an empty
184           * Tell whether the specified service class is available.     * <code>Iterator</code>.
185           * Iff getService() could return a non-null value for the     *
186           * specified service, this method will return <code>true</code>.     * @param serviceClass the service class to get selectors for.
187           *     * @return a list of valid service selectors for the service
188           * @param serviceClass the service class to check on.     *         class, or <code>null</code>.
189           * @return whether the specified service class is availabe.     */
190           */    public Iterator getCurrentServiceSelectors (Class serviceClass);
191          public boolean hasService(Class serviceClass);  
192      /**
193          /**     * Tell whether the specified service class is available.
194           * Add a listener on all adds and removes of services.     * Iff getService() could return a non-null value for the
195           * @param listener the listener to add.     * specified service, this method will return <code>true</code>.
196           */     *
197          public void addBeanContextServicesListener(BeanContextServicesListener listener);     * @param serviceClass the service class to check on.
198       * @return whether the specified service class is available.
199          /**     */
200           * Remove a listener on all adds and removes of services.    public boolean hasService (Class serviceClass);
201           * @specnote it is not certain whether this should remove this  
202           *           listener if it was specified in    /**
203           *           <code>getService()</code>.     * Add a listener on all adds and removes of services.
204           * @param listener the listener to add.     * @param listener the listener to add.
205           */     */
206          public void removeBeanContextServicesListener(BeanContextServicesListener listener);    public void
207      addBeanContextServicesListener (BeanContextServicesListener listener);
208    
209      /**
210       * Remove a listener on all adds and removes of services.
211       * @specnote it is not certain whether this should remove this
212       *           listener if it was specified in
213       *           <code>getService()</code>.
214       * @param listener the listener to add.
215       */
216      public void
217      removeBeanContextServicesListener (BeanContextServicesListener listener);
218  }  }

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26