1. /*
  2. * @(#)EventDirContext.java 1.8 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.naming.event;
  8. import javax.naming.Name;
  9. import javax.naming.NamingException;
  10. import javax.naming.directory.DirContext;
  11. import javax.naming.directory.SearchControls;
  12. /**
  13. * Contains methods for registering listeners to be notified
  14. * of events fired when objects named in a directory context changes.
  15. *<p>
  16. * The methods in this interface support identification of objects by
  17. * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2254.txt">RFC 2254</a>
  18. * search filters.
  19. *
  20. *<P>Using the search filter, it is possible to register interest in objects
  21. * that do not exist at the time of registration but later come into existence and
  22. * satisfy the filter. However, there might be limitations in the extent
  23. * to which this can be supported by the service provider and underlying
  24. * protocol/service. If the caller submits a filter that cannot be
  25. * supported in this way, <tt>addNamingListener()</tt> throws an
  26. * <tt>InvalidSearchFilterException</tt>.
  27. *<p>
  28. * See <tt>EventContext</tt> for a description of event source
  29. * and target, and information about listener registration/deregistration
  30. * that are also applicable to methods in this interface.
  31. * See the
  32. * <a href=package-summary.html#THREADING>package description</a>
  33. * for information on threading issues.
  34. *<p>
  35. * A <tt>SearchControls</tt> or array object
  36. * passed as a parameter to any method is owned by the caller.
  37. * The service provider will not modify the object or keep a reference to it.
  38. *
  39. * @author Rosanna Lee
  40. * @author Scott Seligman
  41. * @version 1.8 03/12/19
  42. * @since 1.3
  43. */
  44. public interface EventDirContext extends EventContext, DirContext {
  45. /**
  46. * Adds a listener for receiving naming events fired
  47. * when objects identified by the search filter <tt>filter</tt> at
  48. * the object named by target are modified.
  49. * <p>
  50. * The scope, returningObj flag, and returningAttributes flag from
  51. * the search controls <tt>ctls</tt> are used to control the selection
  52. * of objects that the listener is interested in,
  53. * and determines what information is returned in the eventual
  54. * <tt>NamingEvent</tt> object. Note that the requested
  55. * information to be returned might not be present in the <tt>NamingEvent</tt>
  56. * object if they are unavailable or could not be obtained by the
  57. * service provider or service.
  58. *
  59. * @param target The nonnull name of the object resolved relative to this context.
  60. * @param filter The nonnull string filter (see RFC2254).
  61. * @param ctls The possibly null search controls. If null, the default
  62. * search controls are used.
  63. * @param l The nonnull listener.
  64. * @exception NamingException If a problem was encountered while
  65. * adding the listener.
  66. * @see EventContext#removeNamingListener
  67. * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls)
  68. */
  69. void addNamingListener(Name target, String filter, SearchControls ctls,
  70. NamingListener l) throws NamingException;
  71. /**
  72. * Adds a listener for receiving naming events fired when
  73. * objects identified by the search filter <tt>filter</tt> at the
  74. * object named by the string target name are modified.
  75. * See the overload that accepts a <tt>Name</tt> for details of
  76. * how this method behaves.
  77. *
  78. * @param target The nonnull string name of the object resolved relative to this context.
  79. * @param filter The nonnull string filter (see RFC2254).
  80. * @param ctls The possibly null search controls. If null, the default
  81. * search controls is used.
  82. * @param l The nonnull listener.
  83. * @exception NamingException If a problem was encountered while
  84. * adding the listener.
  85. * @see EventContext#removeNamingListener
  86. * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, javax.naming.directory.SearchControls)
  87. */
  88. void addNamingListener(String target, String filter, SearchControls ctls,
  89. NamingListener l) throws NamingException;
  90. /**
  91. * Adds a listener for receiving naming events fired
  92. * when objects identified by the search filter <tt>filter</tt> and
  93. * filter arguments at the object named by the target are modified.
  94. * The scope, returningObj flag, and returningAttributes flag from
  95. * the search controls <tt>ctls</tt> are used to control the selection
  96. * of objects that the listener is interested in,
  97. * and determines what information is returned in the eventual
  98. * <tt>NamingEvent</tt> object. Note that the requested
  99. * information to be returned might not be present in the <tt>NamingEvent</tt>
  100. * object if they are unavailable or could not be obtained by the
  101. * service provider or service.
  102. *
  103. * @param target The nonnull name of the object resolved relative to this context.
  104. * @param filter The nonnull string filter (see RFC2254).
  105. * @param filterArgs The possibly null array of arguments for the filter.
  106. * @param ctls The possibly null search controls. If null, the default
  107. * search controls are used.
  108. * @param l The nonnull listener.
  109. * @exception NamingException If a problem was encountered while
  110. * adding the listener.
  111. * @see EventContext#removeNamingListener
  112. * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)
  113. */
  114. void addNamingListener(Name target, String filter, Object[] filterArgs,
  115. SearchControls ctls, NamingListener l) throws NamingException;
  116. /**
  117. * Adds a listener for receiving naming events fired when
  118. * objects identified by the search filter <tt>filter</tt>
  119. * and filter arguments at the
  120. * object named by the string target name are modified.
  121. * See the overload that accepts a <tt>Name</tt> for details of
  122. * how this method behaves.
  123. *
  124. * @param target The nonnull string name of the object resolved relative to this context.
  125. * @param filter The nonnull string filter (see RFC2254).
  126. * @param filterArgs The possibly null array of arguments for the filter.
  127. * @param ctls The possibly null search controls. If null, the default
  128. * search controls is used.
  129. * @param l The nonnull listener.
  130. * @exception NamingException If a problem was encountered while
  131. * adding the listener.
  132. * @see EventContext#removeNamingListener
  133. * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls) */
  134. void addNamingListener(String target, String filter, Object[] filterArgs,
  135. SearchControls ctls, NamingListener l) throws NamingException;
  136. }