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-2021 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.common.types;
028
029
030
031import java.util.List;
032import java.util.Set;
033
034import com.unboundid.directory.sdk.common.schema.AttributeType;
035import com.unboundid.ldap.sdk.Attribute;
036import com.unboundid.ldap.sdk.DN;
037import com.unboundid.ldap.sdk.Filter;
038import com.unboundid.ldap.sdk.LDAPException;
039import com.unboundid.ldap.sdk.ReadOnlyEntry;
040import com.unboundid.ldap.sdk.SearchScope;
041import com.unboundid.util.NotExtensible;
042import com.unboundid.util.ThreadSafety;
043import 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)
053public 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}