1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20
21 package org.apache.directory.api.ldap.model.message;
22
23
24 import org.apache.directory.api.ldap.model.name.Dn;
25
26
27 /**
28 * LDAPv3 result structure embedded into Responses. See section 4.1.9 in <a
29 * href="http://www.ietf.org/rfc/rfc4511.txt">RFC 4511</a> for a description of
30 * the LDAPResult ASN.1 structure, here's a snippet from it:
31 *
32 * <pre>
33 * The LDAPResult is the construct used in this protocol to return
34 * success or failure indications from servers to clients. To various
35 * requests, servers will return responses containing the elements found
36 * in LDAPResult to indicate the final status of the protocol operation
37 * request.
38
39 * LDAPResult ::= SEQUENCE {
40 * resultCode ENUMERATED {
41 * success (0),
42 * operationsError (1),
43 * protocolError (2),
44 * timeLimitExceeded (3),
45 * sizeLimitExceeded (4),
46 * compareFalse (5),
47 * compareTrue (6),
48 * authMethodNotSupported (7),
49 * strongerAuthRequired (8),
50 * -- 9 reserved --
51 * referral (10),
52 * adminLimitExceeded (11),
53 * unavailableCriticalExtension (12),
54 * confidentialityRequired (13),
55 * saslBindInProgress (14),
56 * noSuchAttribute (16),
57 * undefinedAttributeType (17),
58 * inappropriateMatching (18),
59 * constraintViolation (19),
60 * attributeOrValueExists (20),
61 * invalidAttributeSyntax (21),
62 * -- 22-31 unused --
63 * noSuchObject (32),
64 * aliasProblem (33),
65 * invalidDNSyntax (34),
66 * -- 35 reserved for undefined isLeaf --
67 * aliasDereferencingProblem (36),
68 * -- 37-47 unused --
69 * inappropriateAuthentication (48),
70 * invalidCredentials (49),
71 * insufficientAccessRights (50),
72 * busy (51),
73 * unavailable (52),
74 * unwillingToPerform (53),
75 * loopDetect (54),
76 * -- 55-63 unused --
77 * namingViolation (64),
78 * objectClassViolation (65),
79 * notAllowedOnNonLeaf (66),
80 * notAllowedOnRDN (67),
81 * entryAlreadyExists (68),
82 * objectClassModsProhibited (69),
83 * -- 70 reserved for CLDAP --
84 * affectsMultipleDSAs (71),
85 * -- 72-79 unused --
86 * other (80),
87 * ... },
88 * matchedDN LDAPDN,
89 * diagnosticMessage LDAPString,
90 * referral [3] Referral OPTIONAL }
91 * </pre>
92 *
93 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
94 */
95 public interface LdapResult
96 {
97 /**
98 * Gets the result code enumeration associated with the response.
99 * Corresponds to the <b> resultCode </b> field within the LDAPResult ASN.1
100 * structure.
101 *
102 * @return the result code enum value.
103 */
104 ResultCodeEnum getResultCode();
105
106
107 /**
108 * Sets the result code enumeration associated with the response.
109 * Corresponds to the <b> resultCode </b> field within the LDAPResult ASN.1
110 * structure.
111 *
112 * @param resultCode the result code enum value.
113 */
114 void setResultCode( ResultCodeEnum resultCode );
115
116
117 /**
118 * Gets the lowest entry in the directory that was matched. For result codes
119 * of noSuchObject, aliasProblem, invalidDNSyntax and
120 * aliasDereferencingProblem, the matchedDN field is set to the name of the
121 * lowest entry (object or alias) in the directory that was matched. If no
122 * aliases were dereferenced while attempting to locate the entry, this will
123 * be a truncated form of the name provided, or if aliases were
124 * dereferenced, of the resulting name, as defined in section 12.5 of X.511
125 * [8]. The matchedDN field is to be set to a zero length string with all
126 * other result codes.
127 *
128 * @return the Dn of the lowest matched entry.
129 */
130 Dn getMatchedDn();
131
132
133 /**
134 * Sets the lowest entry in the directory that was matched.
135 *
136 * @see #getMatchedDn()
137 * @param dn the Dn of the lowest matched entry.
138 */
139 void setMatchedDn( Dn dn );
140
141
142 /**
143 * Gets the descriptive diagnostic message associated with the error code. May be
144 * null for SUCCESS, COMPARETRUE, COMPAREFALSE and REFERRAL operations.
145 *
146 * @return the descriptive diagnostic message.
147 */
148 String getDiagnosticMessage();
149
150
151 /**
152 * Sets the descriptive diagnostic message associated with the error code. May be
153 * null for SUCCESS, COMPARETRUE, and COMPAREFALSE operations.
154 *
155 * @param diagnosticMessage the descriptive diagnostic message.
156 */
157 void setDiagnosticMessage( String diagnosticMessage );
158
159
160 /**
161 * Gets whether or not this result represents a Referral. For referrals the
162 * error code is set to REFERRAL and the referral property is not null.
163 *
164 * @return true if this result represents a referral.
165 */
166 boolean isReferral();
167
168
169 /**
170 * Gets the Referral associated with this LdapResult if the resultCode
171 * property is set to the REFERRAL ResultCodeEnum.
172 *
173 * @return the referral on REFERRAL resultCode, null on all others.
174 */
175 Referral getReferral();
176
177
178 /**
179 * Sets the Referral associated with this LdapResult if the resultCode
180 * property is set to the REFERRAL ResultCodeEnum. Setting this property
181 * will result in a true return from isReferral and the resultCode should be
182 * set to REFERRAL.
183 *
184 * @param referral optional referral on REFERRAL errors.
185 */
186 void setReferral( Referral referral );
187
188
189 /**
190 * Tells if the LdapResult is a success, with no added information. The
191 * MatchedDn will be empty, as the diagnostic message and the referral.
192 * The ResultCode will always be 0.
193 *
194 * @return True if the LdapResult is SUCCESS.
195 */
196 boolean isDefaultSuccess();
197 }