1. /*
  2. * @(#)SortResponseControl.java 1.3 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. import java.io.IOException;
  9. import javax.naming.*;
  10. import javax.naming.directory.*;
  11. import com.sun.jndi.ldap.Ber;
  12. import com.sun.jndi.ldap.BerDecoder;
  13. import com.sun.jndi.ldap.LdapCtx;
  14. /**
  15. * Indicates whether the requested sort of search results was successful or not.
  16. * When the result code indicates success then the results have been sorted as
  17. * requested. Otherwise the sort was unsuccessful and additional details
  18. * regarding the cause of the error may have been provided by the server.
  19. * <p>
  20. * The code sample in {@link SortControl} shows how this class may be used.
  21. * <p>
  22. * This class implements the LDAPv3 Response Control for server-side sorting
  23. * as defined in
  24. * <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
  25. *
  26. * The control's value has the following ASN.1 definition:
  27. * <pre>
  28. *
  29. * SortResult ::= SEQUENCE {
  30. * sortResult ENUMERATED {
  31. * success (0), -- results are sorted
  32. * operationsError (1), -- server internal failure
  33. * timeLimitExceeded (3), -- timelimit reached before
  34. * -- sorting was completed
  35. * strongAuthRequired (8), -- refused to return sorted
  36. * -- results via insecure
  37. * -- protocol
  38. * adminLimitExceeded (11), -- too many matching entries
  39. * -- for the server to sort
  40. * noSuchAttribute (16), -- unrecognized attribute
  41. * -- type in sort key
  42. * inappropriateMatching (18), -- unrecognized or inappro-
  43. * -- priate matching rule in
  44. * -- sort key
  45. * insufficientAccessRights (50), -- refused to return sorted
  46. * -- results to this client
  47. * busy (51), -- too busy to process
  48. * unwillingToPerform (53), -- unable to sort
  49. * other (80)
  50. * },
  51. * attributeType [0] AttributeType OPTIONAL }
  52. *
  53. * </pre>
  54. *
  55. * @since 1.5
  56. * @see SortControl
  57. * @author Vincent Ryan
  58. */
  59. final public class SortResponseControl extends BasicControl {
  60. /**
  61. * The server-side sort response control's assigned object identifier
  62. * is 1.2.840.113556.1.4.474.
  63. */
  64. public static final String OID = "1.2.840.113556.1.4.474";
  65. private static final long serialVersionUID = 5142939176006310877L;
  66. /**
  67. * The sort result code.
  68. *
  69. * @serial
  70. */
  71. private int resultCode = 0;
  72. /**
  73. * The ID of the attribute that caused the sort to fail.
  74. *
  75. * @serial
  76. */
  77. private String badAttrId = null;
  78. /**
  79. * Constructs a control to indicate the outcome of a sort request.
  80. *
  81. * @param id The control's object identifier string.
  82. * @param criticality The control's criticality.
  83. * @param value The control's ASN.1 BER encoded value.
  84. * It is not cloned - any changes to value
  85. * will affect the contents of the control.
  86. * @exception IOException if an error is encountered
  87. * while decoding the control's value.
  88. */
  89. public SortResponseControl(String id, boolean criticality, byte[] value)
  90. throws IOException {
  91. super(id, criticality, value);
  92. // decode value
  93. BerDecoder ber = new BerDecoder(value, 0, value.length);
  94. ber.parseSeq(null);
  95. resultCode = ber.parseEnumeration();
  96. if ((ber.bytesLeft() > 0) && (ber.peekByte() == Ber.ASN_CONTEXT)) {
  97. badAttrId = ber.parseStringWithTag(Ber.ASN_CONTEXT, true, null);
  98. }
  99. }
  100. /**
  101. * Determines if the search results have been successfully sorted.
  102. * If an error occurred during sorting a NamingException is thrown.
  103. *
  104. * @return true if the search results have been sorted.
  105. */
  106. public boolean isSorted() {
  107. return (resultCode == 0); // a result code of zero indicates success
  108. }
  109. /**
  110. * Retrieves the LDAP result code of the sort operation.
  111. *
  112. * @return The result code. A zero value indicates success.
  113. */
  114. public int getResultCode() {
  115. return resultCode;
  116. }
  117. /**
  118. * Retrieves the ID of the attribute that caused the sort to fail.
  119. * Returns null if no ID was returned by the server.
  120. *
  121. * @return The possibly null ID of the bad attribute.
  122. */
  123. public String getAttributeID() {
  124. return badAttrId;
  125. }
  126. /**
  127. * Retrieves the NamingException appropriate for the result code.
  128. *
  129. * @return A NamingException or null if the result code indicates
  130. * success.
  131. */
  132. public NamingException getException() {
  133. return LdapCtx.mapErrorCode(resultCode, null);
  134. }
  135. }