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 }