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-2012 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.
078 *
079 * @return A list of the attributes contained in the entry.
080 */
081 List<Attribute> getAttributes();
082
083
084
085 /**
086 * Indicates whether the entry contains an attribute with the specified type.
087 *
088 * @param type The attribute type for which to make the determination. It
089 * must not be {@code null}.
090 *
091 * @return {@code true} if the entry has an attribute with the specified
092 * name, or {@code false} if not.
093 */
094 boolean hasAttribute(final AttributeType type);
095
096
097
098 /**
099 * Indicates whether the entry contains an attribute with the specified name.
100 *
101 * @param name The name or OID of the attribute for which to make the
102 * determination. It must not be {@code null}.
103 *
104 * @return {@code true} if the entry has an attribute with the specified
105 * name, or {@code false} if not.
106 */
107 boolean hasAttribute(final String name);
108
109
110
111 /**
112 * Indicates whether the entry contains an attribute with the specified name
113 * and set of options.
114 *
115 * @param type The attribute type for which to make the determination.
116 * It must not be {@code null}.
117 * @param options The set of attribute options for which to make the
118 * determination. It may be {@code null} or empty to
119 * indicate no options.
120 *
121 * @return {@code true} if the entry has an attribute with the specified
122 * name, or {@code false} if not.
123 */
124 boolean hasAttribute(final AttributeType type, final Set<String> options);
125
126
127
128 /**
129 * Indicates whether the entry contains an attribute with the specified name
130 * and set of options.
131 *
132 * @param name The name or OID of the attribute for which to make the
133 * determination. It must not be {@code null}.
134 * @param options The set of attribute options for which to make the
135 * determination. It may be {@code null} or empty to
136 * indicate no options.
137 *
138 * @return {@code true} if the entry has an attribute with the specified
139 * name, or {@code false} if not.
140 */
141 boolean hasAttribute(final String name, final Set<String> options);
142
143
144
145 /**
146 * Indicates whether the entry contains an attribute with the specified name
147 * and value.
148 *
149 * @param type The attribute type for the attribute for which to make the
150 * determination. It must not be {@code null}.
151 * @param value The value for which to make the determination. It must not
152 * be {@code null}.
153 *
154 * @return {@code true} if the entry has an attribute with the specified name
155 * and value, or {@code false} if not.
156 */
157 boolean hasAttributeValue(final AttributeType type, final String value);
158
159
160
161 /**
162 * Indicates whether the entry contains an attribute with the specified name
163 * and value.
164 *
165 * @param name The name or OID of the attribute for which to make the
166 * determination. It must not be {@code null}.
167 * @param value The value for which to make the determination. It must not
168 * be {@code null}.
169 *
170 * @return {@code true} if the entry has an attribute with the specified name
171 * and value, or {@code false} if not.
172 */
173 boolean hasAttributeValue(final String name, final String value);
174
175
176
177 /**
178 * Indicates whether the entry contains an attribute with the specified name
179 * and value.
180 *
181 * @param type The attribute type for the attribute for which to make the
182 * determination. It must not be {@code null}.
183 * @param value The value for which to make the determination. It must not
184 * be {@code null}.
185 *
186 * @return {@code true} if the entry has an attribute with the specified name
187 * and value, or {@code false} if not.
188 */
189 boolean hasAttributeValue(final AttributeType type, final byte[] value);
190
191
192
193 /**
194 * Indicates whether the entry contains an attribute with the specified name
195 * and value.
196 *
197 * @param name The name or OID of the attribute for which to make the
198 * determination. It must not be {@code null}.
199 * @param value The value for which to make the determination. It must not
200 * be {@code null}.
201 *
202 * @return {@code true} if the entry has an attribute with the specified name
203 * and value, or {@code false} if not.
204 */
205 boolean hasAttributeValue(final String name, final byte[] value);
206
207
208
209 /**
210 * Retrieves the attribute with the specified name. This will include all
211 * variants of the attribute type with different sets of attribute options.
212 *
213 * @param type The attribute type for the attribute to retrieve. It must
214 * not be {@code null}.
215 *
216 * @return A list of all occurrences of the requested attribute with any set
217 * of options, or {@code null} if the specified attribute is not
218 * present in the entry.
219 */
220 List<Attribute> getAttribute(final AttributeType type);
221
222
223
224 /**
225 * Retrieves the attribute with the specified name. This will include all
226 * variants of the attribute type with different sets of attribute options.
227 *
228 * @param name The name or OID of the attribute to retrieve. It must not be
229 * {@code null}.
230 *
231 * @return A list of all occurrences of the requested attribute with any set
232 * of options, or {@code null} if the specified attribute is not
233 * present in the entry.
234 */
235 List<Attribute> getAttribute(final String name);
236
237
238
239 /**
240 * Retrieves the attribute with the specified name and exact set of options.
241 *
242 * @param type The attribute type for the attribute to retrieve. It must
243 * not be {@code null}.
244 * @param options The set of attribute options for the attribute to
245 * retrieve. It may be {@code null} or empty if there should
246 * not be any options.
247 *
248 * @return The requested attribute, or {@code null} if it is not present in
249 * the entry.
250 */
251 Attribute getAttribute(final AttributeType type, final Set<String> options);
252
253
254
255 /**
256 * Retrieves the attribute with the specified name and exact set of options.
257 *
258 * @param name The name or OID of the attribute to retrieve. It must not
259 * be {@code null}.
260 * @param options The set of attribute options for the attribute to
261 * retrieve. It may be {@code null} or empty if there should
262 * not be any options.
263 *
264 * @return The requested attribute, or {@code null} if it is not present in
265 * the entry.
266 */
267 Attribute getAttribute(final String name, final Set<String> options);
268
269
270
271 /**
272 * Indicates whether this entry is within the range of the provided base DN
273 * and scope.
274 *
275 * @param baseDN The base DN for which to make the determination.
276 * @param scope The scope for which to make the determination.
277 *
278 * @return {@code true} if this entry is within the range specified by the
279 * provided base DN and scope, or {@code false} if not.
280 *
281 * @throws LDAPException If the provided string cannot be parsed as a valid
282 * DN.
283 */
284 boolean matchesBaseAndScope(final String baseDN, final SearchScope scope)
285 throws LDAPException;
286
287
288
289 /**
290 * Indicates whether this entry matches the provided filter.
291 *
292 * @param filter The filter for which to make the determination. It must
293 * not be {@code null}.
294 *
295 * @return {@code true} if this entry matches the provided filter, or
296 * {@code false} if not.
297 *
298 * @throws LDAPException If a problem occurs while making the determination,
299 * or if the provided string cannot be parsed as a
300 * valid filter.
301 */
302 boolean matchesFilter(final String filter)
303 throws LDAPException;
304
305
306
307 /**
308 * Indicates whether this entry matches the provided filter.
309 *
310 * @param filter The filter for which to make the determination. It must
311 * not be {@code null}.
312 *
313 * @return {@code true} if this entry matches the provided filter, or
314 * {@code false} if not.
315 *
316 * @throws LDAPException If a problem occurs while making the determination,
317 * or if the provided string cannot be parsed as a
318 * valid filter.
319 */
320 boolean matchesFilter(final Filter filter)
321 throws LDAPException;
322
323
324
325 /**
326 * Converts this server entry to its corresponding LDAP SDK representation.
327 *
328 * @return An LDAP SDK representation of this server entry.
329 */
330 ReadOnlyEntry toLDAPSDKEntry();
331 }