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:

Entry

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Entries.DiffStrategy Defines the available strategy to compute changes.
static class	Entries.NullEntry An Entry which implements the null object pattern.
static class	Entries.ReplaceStrategy Defines the available strategy to generate changes.

Field Summary

Fields

Modifier and Type	Field and Description
static Option<AttributeFilter>	ATTRIBUTE_FILTER Selects which attributes will be compared.
static Option<Entries.DiffStrategy>	DIFF_STRATEGY Defines the strategy to use to compute changes.
static Option<Entries.ReplaceStrategy>	REPLACE_STRATEGY Defines the strategy to use to generate changes.

Method Summary

Modifier and Type	Method and Description
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).
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.
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.
static boolean	containsObjectClass(Entry entry, ObjectClass objectClass) Check if the provided entry contains the provided object class.
static boolean	containsObjectClass(Entry entry, ObjectClass objectClass, Schema schema) Check if the provided entry contains the provided object class.
static Entry	copyOnWriteEntry(Entry entry, Function<Entry,Entry> copyConstructor) Returns a shallow copy-on-write view of entry.
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.
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.
static Set<ObjectClass>	getObjectClasses(Entry entry) Returns an unmodifiable set containing the object classes associated with the provided entry.
static Set<ObjectClass>	getObjectClasses(Entry entry, Schema schema) Returns an unmodifiable set containing the object classes associated with the provided entry.
static ObjectClass	getStructuralObjectClass(Entry entry) Returns the structural object class associated with the provided entry, or null if none was found.
static ObjectClass	getStructuralObjectClass(Entry entry, Schema schema) Returns the structural object class associated with the provided entry, or null if none was found.
static boolean	isSubEntry(Entry entry) Returns whether the provided entry is a sub entry.
static List<Entry>	makeEntries(String... ldifLines) Builds a list of entries from the provided lines of LDIF.
static Entry	makeEntry(String... ldifLines) Builds an entry from the provided lines of LDIF.
static Entry	modifyEntry(Entry entry, Modification change) Applies the provided modification to an entry.
static Entry	modifyEntry(Entry entry, Modification change, Collection<? super ByteString> conflictingValues) Applies the provided modification to an entry.
static Entry	modifyEntry(Entry entry, ModifyRequest changes) Applies the provided modification request to an entry.
static Entry	modifyEntryPermissive(Entry entry, Collection<Modification> changes) Applies the provided modifications to an entry using "permissive" modify semantics.
static Entry	modifyEntryStrict(Entry entry, Collection<Modification> changes) Applies the provided modifications to an entry using "strict" modify semantics.
static Entry	nullEntry(Dn dn) Returns a read-only empty entry having the provided distinguished name.
static String	toLdif(Entry entry) Returns the LDIF representation of entry.
static Entry	unmodifiableEntry(Entry entry) Returns a read-only view of entry and its attributes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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 Detail

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:

Schema.validateEntry(Entry, SchemaValidationPolicy, Collection)

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:

Schema.validateEntry(Entry, SchemaValidationPolicy, Collection)

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:

Requests.newModifyRequest(Entry, Entry)

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(Dn dn)

Returns a read-only empty entry having the provided distinguished name.

Update attemps 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.