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 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2010-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.common.types; 028 029 030 031 import java.util.List; 032 import java.util.Set; 033 034 import com.unboundid.directory.sdk.common.schema.AttributeType; 035 import com.unboundid.ldap.sdk.Attribute; 036 import com.unboundid.ldap.sdk.DN; 037 import com.unboundid.ldap.sdk.Filter; 038 import com.unboundid.ldap.sdk.LDAPException; 039 import com.unboundid.ldap.sdk.ReadOnlyEntry; 040 import com.unboundid.ldap.sdk.SearchScope; 041 import com.unboundid.util.NotExtensible; 042 import com.unboundid.util.ThreadSafety; 043 import com.unboundid.util.ThreadSafetyLevel; 044 045 046 047 /** 048 * This interface defines a set of methods which may be used to interact with an 049 * entry. 050 */ 051 @NotExtensible() 052 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE) 053 public interface Entry 054 { 055 /** 056 * Retrieves the DN of the entry as a string. 057 * 058 * @return The DN of the entry as a string. 059 */ 060 String getDN(); 061 062 063 064 /** 065 * Retrieves a parsed representation of the DN for the entry. 066 * 067 * @return A parsed representation of the DN for the entry. 068 * 069 * @throws LDAPException If a problem occurs while trying to parse the DN. 070 */ 071 DN getParsedDN() 072 throws LDAPException; 073 074 075 076 /** 077 * Retrieves a list of the attributes contained in the entry. It may contain 078 * both real and virtual attributes. 079 * 080 * @return A list of the attributes contained in the entry. 081 */ 082 List<Attribute> getAttributes(); 083 084 085 086 /** 087 * Retrieves a list of the real (i.e., non-virtual) attributes contained in 088 * the entry. 089 * 090 * @return A list of the real attributes contained in the entry. 091 */ 092 List<Attribute> getRealAttributes(); 093 094 095 096 /** 097 * Retrieves a list of the virtual attributes contained in the entry. 098 * 099 * @return A list of the virtual attributes contained in the entry. 100 */ 101 List<Attribute> getVirtualAttributes(); 102 103 104 105 /** 106 * Indicates whether the entry contains an attribute with the specified type. 107 * 108 * @param type The attribute type for which to make the determination. It 109 * must not be {@code null}. 110 * 111 * @return {@code true} if the entry has an attribute with the specified 112 * name, or {@code false} if not. 113 */ 114 boolean hasAttribute(final AttributeType type); 115 116 117 118 /** 119 * Indicates whether the entry contains an attribute with the specified name. 120 * 121 * @param name The name or OID of the attribute for which to make the 122 * determination. It must not be {@code null}. 123 * 124 * @return {@code true} if the entry has an attribute with the specified 125 * name, or {@code false} if not. 126 */ 127 boolean hasAttribute(final String name); 128 129 130 131 /** 132 * Indicates whether the entry contains an attribute with the specified name 133 * and set of options. 134 * 135 * @param type The attribute type for which to make the determination. 136 * It must not be {@code null}. 137 * @param options The set of attribute options for which to make the 138 * determination. It may be {@code null} or empty to 139 * indicate no options. 140 * 141 * @return {@code true} if the entry has an attribute with the specified 142 * name, or {@code false} if not. 143 */ 144 boolean hasAttribute(final AttributeType type, final Set<String> options); 145 146 147 148 /** 149 * Indicates whether the entry contains an attribute with the specified name 150 * and set of options. 151 * 152 * @param name The name or OID of the attribute for which to make the 153 * determination. It must not be {@code null}. 154 * @param options The set of attribute options for which to make the 155 * determination. It may be {@code null} or empty to 156 * indicate no options. 157 * 158 * @return {@code true} if the entry has an attribute with the specified 159 * name, or {@code false} if not. 160 */ 161 boolean hasAttribute(final String name, final Set<String> options); 162 163 164 165 /** 166 * Indicates whether the entry contains an attribute with the specified name 167 * and value. 168 * 169 * @param type The attribute type for the attribute for which to make the 170 * determination. It must not be {@code null}. 171 * @param value The value for which to make the determination. It must not 172 * be {@code null}. 173 * 174 * @return {@code true} if the entry has an attribute with the specified name 175 * and value, or {@code false} if not. 176 */ 177 boolean hasAttributeValue(final AttributeType type, final String value); 178 179 180 181 /** 182 * Indicates whether the entry contains an attribute with the specified name 183 * and value. 184 * 185 * @param name The name or OID of the attribute for which to make the 186 * determination. It must not be {@code null}. 187 * @param value The value for which to make the determination. It must not 188 * be {@code null}. 189 * 190 * @return {@code true} if the entry has an attribute with the specified name 191 * and value, or {@code false} if not. 192 */ 193 boolean hasAttributeValue(final String name, final String value); 194 195 196 197 /** 198 * Indicates whether the entry contains an attribute with the specified name 199 * and value. 200 * 201 * @param type The attribute type for the attribute for which to make the 202 * determination. It must not be {@code null}. 203 * @param value The value for which to make the determination. It must not 204 * be {@code null}. 205 * 206 * @return {@code true} if the entry has an attribute with the specified name 207 * and value, or {@code false} if not. 208 */ 209 boolean hasAttributeValue(final AttributeType type, final byte[] value); 210 211 212 213 /** 214 * Indicates whether the entry contains an attribute with the specified name 215 * and value. 216 * 217 * @param name The name or OID of the attribute for which to make the 218 * determination. It must not be {@code null}. 219 * @param value The value for which to make the determination. It must not 220 * be {@code null}. 221 * 222 * @return {@code true} if the entry has an attribute with the specified name 223 * and value, or {@code false} if not. 224 */ 225 boolean hasAttributeValue(final String name, final byte[] value); 226 227 228 229 /** 230 * Retrieves the attribute with the specified name. This will include all 231 * variants of the attribute type with different sets of attribute options. 232 * 233 * @param type The attribute type for the attribute to retrieve. It must 234 * not be {@code null}. 235 * 236 * @return A list of all occurrences of the requested attribute with any set 237 * of options, or {@code null} if the specified attribute is not 238 * present in the entry. 239 */ 240 List<Attribute> getAttribute(final AttributeType type); 241 242 243 244 /** 245 * Retrieves the attribute with the specified name. This will include all 246 * variants of the attribute type with different sets of attribute options. 247 * 248 * @param name The name or OID of the attribute to retrieve. It must not be 249 * {@code null}. 250 * 251 * @return A list of all occurrences of the requested attribute with any set 252 * of options, or {@code null} if the specified attribute is not 253 * present in the entry. 254 */ 255 List<Attribute> getAttribute(final String name); 256 257 258 259 /** 260 * Retrieves the attribute with the specified name and exact set of options. 261 * 262 * @param type The attribute type for the attribute to retrieve. It must 263 * not be {@code null}. 264 * @param options The set of attribute options for the attribute to 265 * retrieve. It may be {@code null} or empty if there should 266 * not be any options. 267 * 268 * @return The requested attribute, or {@code null} if it is not present in 269 * the entry. 270 */ 271 Attribute getAttribute(final AttributeType type, final Set<String> options); 272 273 274 275 /** 276 * Retrieves the attribute with the specified name and exact set of options. 277 * 278 * @param name The name or OID of the attribute to retrieve. It must not 279 * be {@code null}. 280 * @param options The set of attribute options for the attribute to 281 * retrieve. It may be {@code null} or empty if there should 282 * not be any options. 283 * 284 * @return The requested attribute, or {@code null} if it is not present in 285 * the entry. 286 */ 287 Attribute getAttribute(final String name, final Set<String> options); 288 289 290 291 /** 292 * Indicates whether this entry is within the range of the provided base DN 293 * and scope. 294 * 295 * @param baseDN The base DN for which to make the determination. 296 * @param scope The scope for which to make the determination. 297 * 298 * @return {@code true} if this entry is within the range specified by the 299 * provided base DN and scope, or {@code false} if not. 300 * 301 * @throws LDAPException If the provided string cannot be parsed as a valid 302 * DN. 303 */ 304 boolean matchesBaseAndScope(final String baseDN, final SearchScope scope) 305 throws LDAPException; 306 307 308 309 /** 310 * Indicates whether this entry matches the provided filter. 311 * 312 * @param filter The filter for which to make the determination. It must 313 * not be {@code null}. 314 * 315 * @return {@code true} if this entry matches the provided filter, or 316 * {@code false} if not. 317 * 318 * @throws LDAPException If a problem occurs while making the determination, 319 * or if the provided string cannot be parsed as a 320 * valid filter. 321 */ 322 boolean matchesFilter(final String filter) 323 throws LDAPException; 324 325 326 327 /** 328 * Indicates whether this entry matches the provided filter. 329 * 330 * @param filter The filter for which to make the determination. It must 331 * not be {@code null}. 332 * 333 * @return {@code true} if this entry matches the provided filter, or 334 * {@code false} if not. 335 * 336 * @throws LDAPException If a problem occurs while making the determination, 337 * or if the provided string cannot be parsed as a 338 * valid filter. 339 */ 340 boolean matchesFilter(final Filter filter) 341 throws LDAPException; 342 343 344 345 /** 346 * Converts this server entry to its corresponding LDAP SDK representation. 347 * 348 * @return An LDAP SDK representation of this server entry. 349 */ 350 ReadOnlyEntry toLDAPSDKEntry(); 351 }