1. /*
  2. * @(#)Control.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.ldap;
  8. /**
  9. * This interface represents an LDAPv3 control as defined in
  10. * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2251.txt">RFC 2251</A>.
  11. *<p>
  12. * The LDAPv3 protocol uses controls to send and receive additional data
  13. * to affect the behavior of predefined operations.
  14. * Controls can be sent along with any LDAP operation to the server.
  15. * These are referred to as <em>request controls</em>. For example, a
  16. * "sort" control can be sent with an LDAP search operation to
  17. * request that the results be returned in a particular order.
  18. * Solicited and unsolicited controls can also be returned with
  19. * responses from the server. Such controls are referred to as
  20. * <em>response controls</em>. For example, an LDAP server might
  21. * define a special control to return change notifications.
  22. *<p>
  23. * This interface is used to represent both request and response controls.
  24. *
  25. * @author Rosanna Lee
  26. * @author Scott Seligman
  27. * @author Vincent Ryan
  28. * @version 1.8 03/12/19
  29. *
  30. * @see ControlFactory
  31. * @since 1.3
  32. */
  33. public interface Control extends java.io.Serializable {
  34. /**
  35. * Indicates a critical control.
  36. * The value of this constant is <tt>true</tt>.
  37. */
  38. public static final boolean CRITICAL = true;
  39. /**
  40. * Indicates a non-critical control.
  41. * The value of this constant is <tt>false</tt>.
  42. */
  43. public static final boolean NONCRITICAL = false;
  44. /**
  45. * Retrieves the object identifier assigned for the LDAP control.
  46. *
  47. * @return The non-null object identifier string.
  48. */
  49. public String getID();
  50. /**
  51. * Determines the criticality of the LDAP control.
  52. * A critical control must not be ignored by the server.
  53. * In other words, if the server receives a critical control
  54. * that it does not support, regardless of whether the control
  55. * makes sense for the operation, the operation will not be performed
  56. * and an <tt>OperationNotSupportedException</tt> will be thrown.
  57. * @return true if this control is critical; false otherwise.
  58. */
  59. public boolean isCritical();
  60. /**
  61. * Retrieves the ASN.1 BER encoded value of the LDAP control.
  62. * The result is the raw BER bytes including the tag and length of
  63. * the control's value. It does not include the controls OID or criticality.
  64. *
  65. * Null is returned if the value is absent.
  66. *
  67. * @return A possibly null byte array representing the ASN.1 BER encoded
  68. * value of the LDAP control.
  69. */
  70. public byte[] getEncodedValue();
  71. // static final long serialVersionUID = -591027748900004825L;
  72. }