001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *  
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *  
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License. 
018 *  
019 */
020
021package org.apache.directory.api.ldap.model.message;
022
023
024import org.apache.directory.api.ldap.model.name.Dn;
025
026
027/**
028 * LDAPv3 result structure embedded into Responses. See section 4.1.9 in <a
029 * href="http://www.ietf.org/rfc/rfc4511.txt">RFC 4511</a> for a description of 
030 * the LDAPResult ASN.1 structure, here's a snippet from it:
031 * 
032 * <pre>
033 *   The LDAPResult is the construct used in this protocol to return
034 *   success or failure indications from servers to clients. To various
035 *  requests, servers will return responses containing the elements found
036 *  in LDAPResult to indicate the final status of the protocol operation
037 *  request.
038
039 * LDAPResult ::= SEQUENCE {
040 *     resultCode         ENUMERATED {
041 *         success                      (0),
042 *         operationsError              (1),
043 *         protocolError                (2),
044 *         timeLimitExceeded            (3),
045 *         sizeLimitExceeded            (4),
046 *         compareFalse                 (5),
047 *         compareTrue                  (6),
048 *         authMethodNotSupported       (7),
049 *         strongerAuthRequired         (8),
050 *              -- 9 reserved --
051 *         referral                     (10),
052 *         adminLimitExceeded           (11),
053 *         unavailableCriticalExtension (12),
054 *         confidentialityRequired      (13),
055 *         saslBindInProgress           (14),
056 *         noSuchAttribute              (16),
057 *         undefinedAttributeType       (17),
058 *         inappropriateMatching        (18),
059 *         constraintViolation          (19),
060 *         attributeOrValueExists       (20),
061 *         invalidAttributeSyntax       (21),
062 *              -- 22-31 unused --
063 *         noSuchObject                 (32),
064 *         aliasProblem                 (33),
065 *         invalidDNSyntax              (34),
066 *              -- 35 reserved for undefined isLeaf --
067 *         aliasDereferencingProblem    (36),
068 *              -- 37-47 unused --
069 *         inappropriateAuthentication  (48),
070 *         invalidCredentials           (49),
071 *         insufficientAccessRights     (50),
072 *         busy                         (51),
073 *         unavailable                  (52),
074 *         unwillingToPerform           (53),
075 *         loopDetect                   (54),
076 *              -- 55-63 unused --
077 *         namingViolation              (64),
078 *         objectClassViolation         (65),
079 *         notAllowedOnNonLeaf          (66),
080 *         notAllowedOnRDN              (67),
081 *         entryAlreadyExists           (68),
082 *         objectClassModsProhibited    (69),
083 *              -- 70 reserved for CLDAP --
084 *         affectsMultipleDSAs          (71),
085 *              -- 72-79 unused --
086 *         other                        (80),
087 *         ...  },
088 *     matchedDN          LDAPDN,
089 *     diagnosticMessage  LDAPString,
090 *     referral           [3] Referral OPTIONAL }
091 * </pre>
092 * 
093 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
094 */
095public interface LdapResult
096{
097    /**
098     * Gets the result code enumeration associated with the response.
099     * 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}