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