001 /*
002 * Copyright 2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.ldap;
027
028 import java.io.IOException;
029 import javax.naming.*;
030 import javax.naming.directory.*;
031 import com.sun.jndi.ldap.Ber;
032 import com.sun.jndi.ldap.BerDecoder;
033 import com.sun.jndi.ldap.LdapCtx;
034
035 /**
036 * Indicates whether the requested sort of search results was successful or not.
037 * When the result code indicates success then the results have been sorted as
038 * requested. Otherwise the sort was unsuccessful and additional details
039 * regarding the cause of the error may have been provided by the server.
040 * <p>
041 * The code sample in {@link SortControl} shows how this class may be used.
042 * <p>
043 * This class implements the LDAPv3 Response Control for server-side sorting
044 * as defined in
045 * <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
046 *
047 * The control's value has the following ASN.1 definition:
048 * <pre>
049 *
050 * SortResult ::= SEQUENCE {
051 * sortResult ENUMERATED {
052 * success (0), -- results are sorted
053 * operationsError (1), -- server internal failure
054 * timeLimitExceeded (3), -- timelimit reached before
055 * -- sorting was completed
056 * strongAuthRequired (8), -- refused to return sorted
057 * -- results via insecure
058 * -- protocol
059 * adminLimitExceeded (11), -- too many matching entries
060 * -- for the server to sort
061 * noSuchAttribute (16), -- unrecognized attribute
062 * -- type in sort key
063 * inappropriateMatching (18), -- unrecognized or inappro-
064 * -- priate matching rule in
065 * -- sort key
066 * insufficientAccessRights (50), -- refused to return sorted
067 * -- results to this client
068 * busy (51), -- too busy to process
069 * unwillingToPerform (53), -- unable to sort
070 * other (80)
071 * },
072 * attributeType [0] AttributeType OPTIONAL }
073 *
074 * </pre>
075 *
076 * @since 1.5
077 * @see SortControl
078 * @author Vincent Ryan
079 */
080 final public class SortResponseControl extends BasicControl {
081
082 /**
083 * The server-side sort response control's assigned object identifier
084 * is 1.2.840.113556.1.4.474.
085 */
086 public static final String OID = "1.2.840.113556.1.4.474";
087
088 private static final long serialVersionUID = 5142939176006310877L;
089
090 /**
091 * The sort result code.
092 *
093 * @serial
094 */
095 private int resultCode = 0;
096
097 /**
098 * The ID of the attribute that caused the sort to fail.
099 *
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,
116 byte[] value) 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)
126 && (ber.peekByte() == Ber.ASN_CONTEXT)) {
127 badAttrId = ber.parseStringWithTag(Ber.ASN_CONTEXT, true,
128 null);
129 }
130 }
131
132 /**
133 * Determines if the search results have been successfully sorted.
134 * If an error occurred during sorting a NamingException is thrown.
135 *
136 * @return true if the search results have been sorted.
137 */
138 public boolean isSorted() {
139 return (resultCode == 0); // a result code of zero indicates success
140 }
141
142 /**
143 * Retrieves the LDAP result code of the sort operation.
144 *
145 * @return The result code. A zero value indicates success.
146 */
147 public int getResultCode() {
148 return resultCode;
149 }
150
151 /**
152 * Retrieves the ID of the attribute that caused the sort to fail.
153 * Returns null if no ID was returned by the server.
154 *
155 * @return The possibly null ID of the bad attribute.
156 */
157 public String getAttributeID() {
158 return badAttrId;
159 }
160
161 /**
162 * Retrieves the NamingException appropriate for the result code.
163 *
164 * @return A NamingException or null if the result code indicates
165 * success.
166 */
167 public NamingException getException() {
168
169 return LdapCtx.mapErrorCode(resultCode, null);
170 }
171 }
|