Package org.forgerock.opendj.ldap

Class Entries

java.lang.Object
org.forgerock.opendj.ldap.Entries
public final class Entries extends Object
This class contains methods for creating and manipulating entries.
See Also:

  • Field Details

    • ATTRIBUTE_FILTER

      public static final Option<AttributeFilter> ATTRIBUTE_FILTER
      Selects which attributes will be compared. By default all user attributes will be compared.

    • REPLACE_STRATEGY

      public static final Option<Entries.ReplaceStrategy> REPLACE_STRATEGY
      Defines the strategy to use to generate changes.

    • DIFF_STRATEGY

      public static final Option<Entries.DiffStrategy> DIFF_STRATEGY
      Defines the strategy to use to compute changes.

  • Method Details

    • compareByName

      public static Comparator<Entry> compareByName()
      Returns a Comparator which can be used to compare entries by name using the natural order for DN comparisons (parent before children).

      In order to sort entries in reverse order (children first) use the following code: 

       Collections.reverseOrder(Entries.compareByName());
      For more complex sort orders involving one or more attributes refer to the SortKey class.
      Returns:
      The Comparator.

    • conformsToSchema

      public static boolean conformsToSchema(Entry entry, SchemaValidationPolicy policy, Collection<LocalizableMessage> errorMessages, Schema schema)
      Returns true if the provided entry is valid according to the specified schema and schema validation policy.

      If attribute value validation is enabled then following checks will be performed:

      • checking that there is at least one value
      • checking that single-valued attributes contain only a single value
      In particular, attribute values will not be checked for conformance to their syntax since this is expected to have already been performed while adding the values to the entry.
      Parameters:
      entry - The entry to be validated.
      policy - The schema validation policy.
      errorMessages - A collection into which any schema validation warnings or error messages can be placed, or null if they should not be saved.
      schema - The schema against which the entry will be validated.
      Returns:
      true if the provided entry is valid according to the specified schema and schema validation policy.
      See Also:

    • conformsToSchema

      public static boolean conformsToSchema(Entry entry, SchemaValidationPolicy policy, Collection<LocalizableMessage> errorMessages)
      Returns true if the provided entry is valid according to the default schema and schema validation policy.

      If attribute value validation is enabled then following checks will be performed:

      • checking that there is at least one value
      • checking that single-valued attributes contain only a single value
      In particular, attribute values will not be checked for conformance to their syntax since this is expected to have already been performed while adding the values to the entry.
      Parameters:
      entry - The entry to be validated.
      policy - The schema validation policy.
      errorMessages - A collection into which any schema validation warnings or error messages can be placed, or null if they should not be saved.
      Returns:
      true if the provided entry is valid according to the default schema and schema validation policy.
      See Also:

    • containsObjectClass

      public static boolean containsObjectClass(Entry entry, ObjectClass objectClass)
      Check if the provided entry contains the provided object class.

      This method uses the default schema for decoding the object class attribute values.

      If the default schema is strict then the provided object class must be recognized by the schema, otherwise the method will return false.

      Parameters:
      entry - The entry which is checked against the object class.
      objectClass - The object class to check.
      Returns:
      true if the entry contains the object class.

    • containsObjectClass

      public static boolean containsObjectClass(Entry entry, ObjectClass objectClass, Schema schema)
      Check if the provided entry contains the provided object class.

      If the provided schema is strict then the provided object class must be recognized by the schema, otherwise the method will return false.

      Parameters:
      entry - The entry which is checked against the object class.
      objectClass - The object class to check.
      schema - The schema which should be used for decoding the object class attribute values.
      Returns:
      true if the entry contains the object class.

    • diffEntries

      public static ModifyRequest diffEntries(Entry fromEntry, Entry toEntry)
      Creates a new modify request containing a list of modifications which can be used to transform fromEntry into entry toEntry.

      The changes will be generated using a default set of options. More specifically, only user attributes will be compared, attributes will be compared using their matching rules, and all generated changes will be reversible: it will contain only modifications of type DELETE then ADD.

      Finally, the modify request will use the distinguished name taken from fromEntry. This method will not check to see if both fromEntry and toEntry have the same distinguished name.

      This method is equivalent to: 

       ModifyRequest request = Requests.newModifyRequest(fromEntry, toEntry);
      Or: 
       ModifyRequest request = diffEntries(fromEntry, toEntry, Options.defaultOptions());
      Parameters:
      fromEntry - The source entry.
      toEntry - The destination entry.
      Returns:
      A modify request containing a list of modifications which can be used to transform fromEntry into entry toEntry. The returned request will always be non-null but may not contain any modifications.
      Throws:
      NullPointerException - If fromEntry or toEntry were null.
      See Also:

    • diffEntries

      public static ModifyRequest diffEntries(Entry fromEntry, Entry toEntry, Options options)
      Creates a new modify request containing a list of modifications which can be used to transform fromEntry into entry toEntry.

      The changes will be generated using the provided set of Options.

      Finally, the modify request will use the distinguished name taken from fromEntry. This method will not check to see if both fromEntry and toEntry have the same distinguished name.

      Parameters:
      fromEntry - The source entry.
      toEntry - The destination entry.
      options - The set of options which will control which attributes are compared, how they are compared, and the type of modifications generated.
      Returns:
      A modify request containing a list of modifications which can be used to transform fromEntry into entry toEntry. The returned request will always be non-null but may not contain any modifications.
      Throws:
      NullPointerException - If fromEntry, toEntry, or options were null.

    • getObjectClasses

      public static Set<ObjectClass> getObjectClasses(Entry entry)
      Returns an unmodifiable set containing the object classes associated with the provided entry. If the default schema is strict then unrecognized object classes will not be included in the returned set, otherwise place-holder object classes will be returned.

      This method uses the default schema for decoding the object class attribute values.

      Parameters:
      entry - The entry whose object classes are required.
      Returns:
      An unmodifiable set containing the object classes associated with the provided entry.

    • getObjectClasses

      public static Set<ObjectClass> getObjectClasses(Entry entry, Schema schema)
      Returns an unmodifiable set containing the object classes associated with the provided entry. If the provided schema is strict then unrecognized object classes will not be included in the returned set, otherwise place-holder object classes will be returned.
      Parameters:
      entry - The entry whose object classes are required.
      schema - The schema which should be used for decoding the object class attribute values.
      Returns:
      An unmodifiable set containing the object classes associated with the provided entry.

    • getStructuralObjectClass

      public static ObjectClass getStructuralObjectClass(Entry entry)
      Returns the structural object class associated with the provided entry, or null if none was found. If the entry contains multiple structural object classes then the first will be returned. This method will ignore unrecognized object classes.

      This method uses the default schema for decoding the object class attribute values.

      Parameters:
      entry - The entry whose structural object class is required.
      Returns:
      The structural object class associated with the provided entry, or null if none was found.

    • getStructuralObjectClass

      public static ObjectClass getStructuralObjectClass(Entry entry, Schema schema)
      Returns the structural object class associated with the provided entry, or null if none was found. If the entry contains multiple structural object classes then the first will be returned. This method will ignore unrecognized object classes.
      Parameters:
      entry - The entry whose structural object class is required.
      schema - The schema which should be used for decoding the object class attribute values.
      Returns:
      The structural object class associated with the provided entry, or null if none was found.

    • isSubEntry

      public static boolean isSubEntry(Entry entry)
      Returns whether the provided entry is a sub entry.
      Parameters:
      entry - The entry to be checked.
      Returns:
      true if the entry is a sub entry, false otherwise.

    • makeEntry

      public static Entry makeEntry(String... ldifLines)
      Builds an entry from the provided lines of LDIF.

      Sample usage: 

       Entry john = makeEntry(
   "dn: cn=John Smith,dc=example,dc=com",
   "objectclass: inetorgperson",
   "cn: John Smith",
   "sn: Smith",
   "givenname: John");
      Parameters:
      ldifLines - LDIF lines that contains entry definition.
      Returns:
      an entry
      Throws:
      LocalizedIllegalArgumentException - If ldifLines did not contain an LDIF entry, or contained multiple entries, or contained malformed LDIF, or if the entry could not be decoded using the default schema.
      NullPointerException - If ldifLines was null.

    • makeEntries

      public static List<Entry> makeEntries(String... ldifLines)
      Builds a list of entries from the provided lines of LDIF.

      Sample usage: 

       List<Entry> smiths = TestCaseUtils.makeEntries(
   "dn: cn=John Smith,dc=example,dc=com",
   "objectclass: inetorgperson",
   "cn: John Smith",
   "sn: Smith",
   "givenname: John",
   "",
   "dn: cn=Jane Smith,dc=example,dc=com",
   "objectclass: inetorgperson",
   "cn: Jane Smith",
   "sn: Smith",
   "givenname: Jane");
      Parameters:
      ldifLines - LDIF lines that contains entries definition. Entries are separated by an empty string: "".
      Returns:
      a non empty list of entries
      Throws:
      LocalizedIllegalArgumentException - If ldifLines did not contain LDIF entries, or contained malformed LDIF, or if the entries could not be decoded using the default schema.
      NullPointerException - If ldifLines was null.

    • modifyEntry

      public static Entry modifyEntry(Entry entry, Modification change) throws LdapException
      Applies the provided modification to an entry. This method implements "permissive" modify semantics, ignoring attempts to add duplicate values or attempts to remove values which do not exist.
      Parameters:
      entry - The entry to be modified.
      change - The modification to be applied to the entry.
      Returns:
      A reference to the updated entry.
      Throws:
      LdapException - If an error occurred while performing the change such as an attempt to increment a value which is not a number. The entry will not have been modified.

    • modifyEntry

      public static Entry modifyEntry(Entry entry, Modification change, Collection<? super ByteString> conflictingValues) throws LdapException
      Applies the provided modification to an entry. This method implements "permissive" modify semantics, recording attempts to add duplicate values or attempts to remove values which do not exist in the provided collection if provided.
      Parameters:
      entry - The entry to be modified.
      change - The modification to be applied to the entry.
      conflictingValues - A collection into which duplicate or missing values will be added, or null if conflicting values should not be saved.
      Returns:
      A reference to the updated entry.
      Throws:
      LdapException - If an error occurred while performing the change such as an attempt to increment a value which is not a number. The entry will not have been modified.

    • modifyEntry

      public static Entry modifyEntry(Entry entry, ModifyRequest changes) throws LdapException
      Applies the provided modification request to an entry. This method will utilize "permissive" modify semantics if the request contains the PermissiveModifyRequestControl.
      Parameters:
      entry - The entry to be modified.
      changes - The modification request to be applied to the entry.
      Returns:
      A reference to the updated entry.
      Throws:
      LdapException - If an error occurred while performing the changes such as an attempt to add duplicate values, remove values which do not exist, or increment a value which is not a number. The entry may have been modified.

    • modifyEntryPermissive

      public static Entry modifyEntryPermissive(Entry entry, Collection<Modification> changes) throws LdapException
      Applies the provided modifications to an entry using "permissive" modify semantics.
      Parameters:
      entry - The entry to be modified.
      changes - The modification request to be applied to the entry.
      Returns:
      A reference to the updated entry.
      Throws:
      LdapException - If an error occurred while performing the changes such as an attempt to increment a value which is not a number. The entry may have been modified.

    • modifyEntryStrict

      public static Entry modifyEntryStrict(Entry entry, Collection<Modification> changes) throws LdapException
      Applies the provided modifications to an entry using "strict" modify semantics. Attempts to add duplicate values or attempts to remove values which do not exist will cause the update to fail.
      Parameters:
      entry - The entry to be modified.
      changes - The modification request to be applied to the entry.
      Returns:
      A reference to the updated entry.
      Throws:
      LdapException - If an error occurred while performing the changes such as an attempt to add duplicate values, remove values which do not exist, or increment a value which is not a number. The entry may have been modified.

    • toLdif

      public static String toLdif(Entry entry)
      Returns the LDIF representation of entry. All attributes will be included and no wrapping will be performed. This method can be useful when debugging applications.
      Parameters:
      entry - The entry to be converted to LDIF.
      Returns:
      The LDIF representation of entry.

    • unmodifiableEntry

      public static Entry unmodifiableEntry(Entry entry)
      Returns a read-only view of entry and its attributes. Query operations on the returned entry and its attributes "read-through" to the underlying entry or attribute, and attempts to modify the returned entry and its attributes either directly or indirectly via an iterator result in an UnsupportedOperationException.
      Parameters:
      entry - The entry for which a read-only view is to be returned.
      Returns:
      A read-only view of entry.
      Throws:
      NullPointerException - If entry was null.

    • copyOnWriteEntry

      public static Entry copyOnWriteEntry(Entry entry, Function<Entry,Entry> copyConstructor)
      Returns a shallow copy-on-write view of entry. Query operations on the returned entry and its attributes "read-through" to the underlying entry or attribute. Attempts to add, replace, or remove attributes result in the entry being lazily copied. Attribute iterables, such as those returned by Entry.getAllAttributes() are read-only (do not support removal).
      Parameters:
      entry - The entry for which a copy-on-write view is to be returned.
      copyConstructor - The copy constructor for lazily copying the entry.
      Returns:
      A copy-on-write view of entry.
      Throws:
      NullPointerException - If entry was null.

    • nullEntry

      public static Entry nullEntry()
      Returns a read-only empty entry having the empty distinguished name.

      Update attempts on the returned entry will be ignored.

      All attribute parsing attempts performed on this entry will return an empty attribute. Hence, using this factory can be useful to prevent null checks in client code.

      Returns:
      The empty entry.

    • nullEntry

      public static Entry nullEntry(Dn dn)
      Returns a read-only empty entry having the provided distinguished name.

      Update attempts on the returned entry will be ignored.

      All attribute parsing attempts performed on this entry will return an empty attribute. Hence, using this factory can be useful to prevent null checks in client code.

      Parameters:
      dn - The entry distinguished name.
      Returns:
      The empty entry.