View Javadoc
1   /*
2    * Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.naming.ldap;
27  
28  import java.io.IOException;
29  import javax.naming.*;
30  import javax.naming.directory.*;
31  import com.sun.jndi.ldap.Ber;
32  import com.sun.jndi.ldap.BerDecoder;
33  import com.sun.jndi.ldap.LdapCtx;
34  
35  /**
36   * Indicates whether the requested sort of search results was successful or not.
37   * When the result code indicates success then the results have been sorted as
38   * requested. Otherwise the sort was unsuccessful and additional details
39   * regarding the cause of the error may have been provided by the server.
40   * <p>
41   * The code sample in {@link SortControl} shows how this class may be used.
42   * <p>
43   * This class implements the LDAPv3 Response Control for server-side sorting
44   * as defined in
45   * <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
46   *
47   * The control's value has the following ASN.1 definition:
48   * <pre>
49   *
50   *     SortResult ::= SEQUENCE {
51   *        sortResult  ENUMERATED {
52   *            success                   (0), -- results are sorted
53   *            operationsError           (1), -- server internal failure
54   *            timeLimitExceeded         (3), -- timelimit reached before
55   *                                           -- sorting was completed
56   *            strongAuthRequired        (8), -- refused to return sorted
57   *                                           -- results via insecure
58   *                                           -- protocol
59   *            adminLimitExceeded       (11), -- too many matching entries
60   *                                           -- for the server to sort
61   *            noSuchAttribute          (16), -- unrecognized attribute
62   *                                           -- type in sort key
63   *            inappropriateMatching    (18), -- unrecognized or inappro-
64   *                                           -- priate matching rule in
65   *                                           -- sort key
66   *            insufficientAccessRights (50), -- refused to return sorted
67   *                                           -- results to this client
68   *            busy                     (51), -- too busy to process
69   *            unwillingToPerform       (53), -- unable to sort
70   *            other                    (80)
71   *            },
72   *      attributeType [0] AttributeType OPTIONAL }
73   *
74   * </pre>
75   *
76   * @since 1.5
77   * @see SortControl
78   * @author Vincent Ryan
79   */
80  final public class SortResponseControl extends BasicControl {
81  
82      /**
83       * The server-side sort response control's assigned object identifier
84       * is 1.2.840.113556.1.4.474.
85       */
86      public static final String OID = "1.2.840.113556.1.4.474";
87  
88      private static final long serialVersionUID = 5142939176006310877L;
89  
90      /**
91       * The sort result code.
92       *
93       * @serial
94       */
95      private int resultCode = 0;
96  
97      /**
98       * The ID of the attribute that caused the sort to fail.
99       *
100      * @serial
101      */
102     private String badAttrId = null;
103 
104     /**
105      * Constructs a control to indicate the outcome of a sort request.
106      *
107      * @param   id              The control's object identifier string.
108      * @param   criticality     The control's criticality.
109      * @param   value           The control's ASN.1 BER encoded value.
110      *                          It is not cloned - any changes to value
111      *                          will affect the contents of the control.
112      * @exception               IOException if an error is encountered
113      *                          while decoding the control's value.
114      */
115     public SortResponseControl(String id, boolean criticality, byte[] value)
116         throws IOException {
117 
118         super(id, criticality, value);
119 
120         // decode value
121         BerDecoder ber = new BerDecoder(value, 0, value.length);
122 
123         ber.parseSeq(null);
124         resultCode = ber.parseEnumeration();
125         if ((ber.bytesLeft() > 0) && (ber.peekByte() == Ber.ASN_CONTEXT)) {
126             badAttrId = ber.parseStringWithTag(Ber.ASN_CONTEXT, true, null);
127         }
128     }
129 
130     /**
131      * Determines if the search results have been successfully sorted.
132      * If an error occurred during sorting a NamingException is thrown.
133      *
134      * @return    true if the search results have been sorted.
135      */
136     public boolean isSorted() {
137         return (resultCode == 0); // a result code of zero indicates success
138     }
139 
140     /**
141      * Retrieves the LDAP result code of the sort operation.
142      *
143      * @return    The result code. A zero value indicates success.
144      */
145     public int getResultCode() {
146         return resultCode;
147     }
148 
149     /**
150      * Retrieves the ID of the attribute that caused the sort to fail.
151      * Returns null if no ID was returned by the server.
152      *
153      * @return The possibly null ID of the bad attribute.
154      */
155     public String getAttributeID() {
156         return badAttrId;
157     }
158 
159     /**
160      * Retrieves the NamingException appropriate for the result code.
161      *
162      * @return A NamingException or null if the result code indicates
163      *         success.
164      */
165     public NamingException getException() {
166 
167         return LdapCtx.mapErrorCode(resultCode, null);
168     }
169 }