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
021 package org.apache.directory.shared.ldap.message;
022
023 import org.apache.directory.shared.ldap.name.LdapDN;
024
025
026 /**
027 * LDAPv3 result structure embedded into Responses. See section 4.1.10 in <a
028 * href="">RFC 2251</a> for a description of the LDAPResult ASN.1 structure,
029 * here's a snippet from it:
030 *
031 * <pre>
032 * The LDAPResult is the construct used in this protocol to return
033 * success or failure indications from servers to clients. In response
034 * to various requests servers will return responses containing fields
035 * of type LDAPResult to indicate the final status of a protocol
036 * operation request.
037 * </pre>
038 *
039 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
040 * @version $Revision: 764131 $
041 */
042 public interface InternalLdapResult
043 {
044 /**
045 * Gets the result code enumeration associated with the response.
046 * Corresponds to the <b> resultCode </b> field within the LDAPResult ASN.1
047 * structure.
048 *
049 * @return the result code enum value.
050 */
051 ResultCodeEnum getResultCode();
052
053
054 /**
055 * Sets the result code enumeration associated with the response.
056 * Corresponds to the <b> resultCode </b> field within the LDAPResult ASN.1
057 * structure.
058 *
059 * @param resultCode
060 * the result code enum value.
061 */
062 void setResultCode( ResultCodeEnum resultCode );
063
064
065 /**
066 * Gets the lowest entry in the directory that was matched. For result codes
067 * of noSuchObject, aliasProblem, invalidDNSyntax and
068 * aliasDereferencingProblem, the matchedDN field is set to the name of the
069 * lowest entry (object or alias) in the directory that was matched. If no
070 * aliases were dereferenced while attempting to locate the entry, this will
071 * be a truncated form of the name provided, or if aliases were
072 * dereferenced, of the resulting name, as defined in section 12.5 of X.511
073 * [8]. The matchedDN field is to be set to a zero length string with all
074 * other result codes.
075 *
076 * @return the Dn of the lowest matched entry.
077 */
078 LdapDN getMatchedDn();
079
080
081 /**
082 * Sets the lowest entry in the directory that was matched.
083 *
084 * @see #getMatchedDn()
085 * @param dn
086 * the Dn of the lowest matched entry.
087 */
088 void setMatchedDn( LdapDN dn );
089
090
091 /**
092 * Gets the descriptive error message associated with the error code. May be
093 * null for SUCCESS, COMPARETRUE, COMPAREFALSE and REFERRAL operations.
094 *
095 * @return the descriptive error message.
096 */
097 String getErrorMessage();
098
099
100 /**
101 * Sets the descriptive error message associated with the error code. May be
102 * null for SUCCESS, COMPARETRUE, and COMPAREFALSE operations.
103 *
104 * @param errorMessage
105 * the descriptive error message.
106 */
107 void setErrorMessage( String errorMessage );
108
109
110 /**
111 * Gets whether or not this result represents a Referral. For referrals the
112 * error code is set to REFERRAL and the referral property is not null.
113 *
114 * @return true if this result represents a referral.
115 */
116 boolean isReferral();
117
118
119 /**
120 * Gets the Referral associated with this LdapResult if the resultCode
121 * property is set to the REFERRAL ResultCodeEnum.
122 *
123 * @return the referral on REFERRAL errors, null on all others.
124 */
125 InternalReferral getReferral();
126
127
128 /**
129 * Sets the Referral associated with this LdapResult if the resultCode
130 * property is set to the REFERRAL ResultCodeEnum. Setting this property
131 * will result in a true return from isReferral and the resultCode should be
132 * set to REFERRAL.
133 *
134 * @param referral
135 * optional referral on REFERRAL errors.
136 */
137 void setReferral( InternalReferral referral );
138 }