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}