001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 *      Portions copyright 2012 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031
032import org.forgerock.i18n.LocalizedIllegalArgumentException;
033import org.forgerock.opendj.ldap.AttributeDescription;
034import org.forgerock.opendj.ldap.ByteString;
035import org.forgerock.opendj.ldap.DN;
036import org.forgerock.opendj.ldap.DecodeException;
037import org.forgerock.opendj.ldap.DecodeOptions;
038import org.forgerock.opendj.ldap.controls.Control;
039import org.forgerock.opendj.ldap.controls.ControlDecoder;
040
041/**
042 * The Compare operation allows a client to compare an assertion value with the
043 * values of a particular attribute in a particular entry in the Directory.
044 * <p>
045 * Note that some directory systems may establish access controls that permit
046 * the values of certain attributes (such as {@code userPassword} ) to be
047 * compared but not interrogated by other means.
048 * <p>
049 * The following excerpt shows how to use the Compare operation to check whether
050 * a member belongs to a (possibly large) static group.
051 *
052 * <pre>
053 * Connection connection = ...;
054 * String groupDN = ...;
055 * String memberDN = ...;
056 *
057 * CompareRequest request =
058 *          Requests.newCompareRequest(groupDN, "member", memberDN);
059 * CompareResult result = connection.compare(request);
060 * if (result.matched()) {
061 *     // The member belongs to the group.
062 * }
063 * </pre>
064 */
065public interface CompareRequest extends Request {
066
067    @Override
068    CompareRequest addControl(Control control);
069
070    /**
071     * Returns the assertion value to be compared.
072     *
073     * @return The assertion value.
074     */
075    ByteString getAssertionValue();
076
077    /**
078     * Returns the assertion value to be compared decoded as a UTF-8 string.
079     *
080     * @return The assertion value decoded as a UTF-8 string.
081     */
082    String getAssertionValueAsString();
083
084    /**
085     * Returns the name of the attribute to be compared.
086     *
087     * @return The name of the attribute.
088     */
089    AttributeDescription getAttributeDescription();
090
091    @Override
092    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
093            throws DecodeException;
094
095    @Override
096    List<Control> getControls();
097
098    /**
099     * Returns the distinguished name of the entry to be compared. The server
100     * shall not dereference any aliases in locating the entry to be compared.
101     *
102     * @return The distinguished name of the entry.
103     */
104    DN getName();
105
106    /**
107     * Sets the assertion value to be compared.
108     * <p>
109     * If the assertion value is not an instance of {@code ByteString} then it
110     * will be converted using the {@link ByteString#valueOf(Object)} method.
111     *
112     * @param value
113     *            The assertion value to be compared.
114     * @return This compare request.
115     * @throws UnsupportedOperationException
116     *             If this compare request does not permit the assertion value
117     *             to be set.
118     * @throws NullPointerException
119     *             If {@code value} was {@code null}.
120     */
121    CompareRequest setAssertionValue(Object value);
122
123    /**
124     * Sets the name of the attribute to be compared.
125     *
126     * @param attributeDescription
127     *            The name of the attribute to be compared.
128     * @return This compare request.
129     * @throws UnsupportedOperationException
130     *             If this compare request does not permit the attribute
131     *             description to be set.
132     * @throws NullPointerException
133     *             If {@code attributeDescription} was {@code null}.
134     */
135    CompareRequest setAttributeDescription(AttributeDescription attributeDescription);
136
137    /**
138     * Sets the name of the attribute to be compared.
139     *
140     * @param attributeDescription
141     *            The name of the attribute to be compared.
142     * @return This compare request.
143     * @throws LocalizedIllegalArgumentException
144     *             If {@code attributeDescription} could not be decoded using
145     *             the default schema.
146     * @throws UnsupportedOperationException
147     *             If this compare request does not permit the attribute
148     *             description to be set.
149     * @throws NullPointerException
150     *             If {@code attributeDescription} was {@code null}.
151     */
152    CompareRequest setAttributeDescription(String attributeDescription);
153
154    /**
155     * Sets the distinguished name of the entry to be compared. The server shall
156     * not dereference any aliases in locating the entry to be compared.
157     *
158     * @param dn
159     *            The distinguished name of the entry to be compared.
160     * @return This compare request.
161     * @throws UnsupportedOperationException
162     *             If this compare request does not permit the distinguished
163     *             name to be set.
164     * @throws NullPointerException
165     *             If {@code dn} was {@code null}.
166     */
167    CompareRequest setName(DN dn);
168
169    /**
170     * Sets the distinguished name of the entry to be compared. The server shall
171     * not dereference any aliases in locating the entry to be compared.
172     *
173     * @param dn
174     *            The distinguished name of the entry to be compared.
175     * @return This compare request.
176     * @throws LocalizedIllegalArgumentException
177     *             If {@code dn} could not be decoded using the default schema.
178     * @throws UnsupportedOperationException
179     *             If this compare request does not permit the distinguished
180     *             name to be set.
181     * @throws NullPointerException
182     *             If {@code dn} was {@code null}.
183     */
184    CompareRequest setName(String dn);
185
186}