1. /*
  2. * @(#)BeanContextServices.java 1.9 03/01/27
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.beans.beancontext;
  8. import java.util.Iterator;
  9. import java.util.TooManyListenersException;
  10. import java.beans.beancontext.BeanContext;
  11. import java.beans.beancontext.BeanContextServiceProvider;
  12. import java.beans.beancontext.BeanContextServicesListener;
  13. /**
  14. * <p>
  15. * The BeanContextServices interface provides a mechanism for a BeanContext
  16. * to expose generic "services" to the BeanContextChild objects within.
  17. * </p>
  18. */
  19. public interface BeanContextServices extends BeanContext, BeanContextServicesListener {
  20. /**
  21. * Adds a service to this BeanContext.
  22. * <code>BeanContextServiceProvider</code>s call this method
  23. * to register a particular service with this context.
  24. * If the service has not previously been added, the
  25. * <code>BeanContextServices</code> associates
  26. * the service with the <code>BeanContextServiceProvider</code> and
  27. * fires a <code>BeanContextServiceAvailableEvent</code> to all
  28. * currently registered <code>BeanContextServicesListeners</code>.
  29. * The method then returns <code>true</code>, indicating that
  30. * the addition of the service was successful.
  31. * If the given service has already been added, this method
  32. * simply returns <code>false</code>.
  33. * @param serviceClass the service to add
  34. * @param serviceProvider the <code>BeanContextServiceProvider</code>
  35. * associated with the service
  36. */
  37. boolean addService(Class serviceClass, BeanContextServiceProvider serviceProvider);
  38. /**
  39. * BeanContextServiceProviders wishing to remove
  40. * a currently registered service from this context
  41. * may do so via invocation of this method. Upon revocation of
  42. * the service, the <code>BeanContextServices</code> fires a
  43. * <code>BeanContextServiceRevokedEvent</code> to its
  44. * list of currently registered
  45. * <code>BeanContextServiceRevokedListeners</code> and
  46. * <code>BeanContextServicesListeners</code>.
  47. * @param serviceClass the service to revoke from this BeanContextServices
  48. * @param serviceProvider the BeanContextServiceProvider associated with
  49. * this particular service that is being revoked
  50. * @param revokeCurrentServicesNow a value of <code>true</code>
  51. * indicates an exceptional circumstance where the
  52. * <code>BeanContextServiceProvider</code> or
  53. * <code>BeanContextServices</code> wishes to immediately
  54. * terminate service to all currently outstanding references
  55. * to the specified service.
  56. */
  57. void revokeService(Class serviceClass, BeanContextServiceProvider serviceProvider, boolean revokeCurrentServicesNow);
  58. /**
  59. * Reports whether or not a given service is
  60. * currently available from this context.
  61. * @param serviceClass the service in question
  62. * @return true if the service is available
  63. */
  64. boolean hasService(Class serviceClass);
  65. /**
  66. * A <code>BeanContextChild</code>, or any arbitrary object
  67. * associated with a <code>BeanContextChild</code>, may obtain
  68. * a reference to a currently registered service from its
  69. * nesting <code>BeanContextServices</code>
  70. * via invocation of this method. When invoked, this method
  71. * gets the service by calling the getService() method on the
  72. * underlying <code>BeanContextServiceProvider</code>.
  73. * @param child the <code>BeanContextChild</code>
  74. * associated with this request
  75. * @param requestor the object requesting the service
  76. * @param serviceClass class of the requested service
  77. * @param serviceSelector the service dependent parameter
  78. * @param bcsrl the
  79. * <code>BeanContextServiceRevokedListener</code> to notify
  80. * if the service should later become revoked
  81. * @throws TooManyListenersException
  82. * @return a reference to this context's named
  83. * Service as requested or <code>null</code>
  84. */
  85. Object getService(BeanContextChild child, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener bcsrl) throws TooManyListenersException;
  86. /**
  87. * Releases a <code>BeanContextChild</code>'s
  88. * (or any arbitrary object associated with a BeanContextChild)
  89. * reference to the specified service by calling releaseService()
  90. * on the underlying <code>BeanContextServiceProvider</code>.
  91. * @param child the <code>BeanContextChild</code>
  92. * @param requestor the requestor
  93. * @param service the service
  94. */
  95. void releaseService(BeanContextChild child, Object requestor, Object service);
  96. /**
  97. * Gets the currently available services for this context.
  98. * @return an <code>Iterator</code> consisting of the
  99. * currently available services
  100. */
  101. Iterator getCurrentServiceClasses();
  102. /**
  103. * Gets the list of service dependent service parameters
  104. * (Service Selectors) for the specified service, by
  105. * calling getCurrentServiceSelectors() on the
  106. * underlying BeanContextServiceProvider.
  107. * @param serviceClass the specified service
  108. * @return the currently available service selectors
  109. * for the named serviceClass
  110. */
  111. Iterator getCurrentServiceSelectors(Class serviceClass);
  112. /**
  113. * Adds a <code>BeanContextServicesListener</code> to this BeanContext
  114. * @param bcsl the <code>BeanContextServicesListener</code> to add
  115. */
  116. void addBeanContextServicesListener(BeanContextServicesListener bcsl);
  117. /**
  118. * Removes a <code>BeanContextServicesListener</code>
  119. * from this <code>BeanContext</code>
  120. * @param bcsl the <code>BeanContextServicesListener</code>
  121. * to remove from this context
  122. */
  123. void removeBeanContextServicesListener(BeanContextServicesListener bcsl);
  124. }