Package org.forgerock.opendj.ldif

Class Ldif

java.lang.Object

org.forgerock.opendj.ldif.Ldif

public final class Ldif
extends Object

This class contains common utility methods for creating and manipulating readers and writers.

Method Summary

Modifier and Type	Method	Description
static ChangeRecordWriter	copyTo(ChangeRecordReader input, ChangeRecordWriter output)	Copies the content of input to output.
static EntryWriter	copyTo(EntryReader input, EntryWriter output)	Copies the content of input to output.
static ChangeRecordReader	diff(EntryReader source, EntryReader target)	Compares the content of source to the content of target and returns the differences in a change record reader.
static ChangeRecordReader	diff(EntryReader source, EntryReader target, Options options)	Compares the content of source to the content of target and returns the differences in a change record reader.
static ChangeRecord	makeChangeRecord(String... ldifLines)	Parses the provided array of LDIF lines as a single LDIF change record.
static List<Entry>	makeEntries(String... ldifLines)	Builds a list of entries from the provided lines of LDIF.
static List<Entry>	makeEntries(List<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	makeEntry(List<String> ldifLines)	Builds an entry from the provided lines of LDIF.
static Flowable<ChangeRecord>	newChangeRecordPublisher(Supplier<? extends ChangeRecordReader> factory)	Returns a Flowable view of a ChangeRecordReader, creating a new reader for each subscriber.
static ChangeRecordReader	newChangeRecordReader(Iterable<? extends ChangeRecord> changes)	Returns a change record reader over the provided change record collection.
static ChangeRecordReader	newChangeRecordReader(Iterator<? extends ChangeRecord> changes)	Returns a change record reader over the provided change record iterator.
static Flowable<Entry>	newEntryPublisher(Supplier<? extends EntryReader> factory)	Returns a Flowable view of a EntryReader, creating a new reader for each subscriber.
static EntryReader	newEntryReader(Iterable<? extends Entry> entries)	Returns an entry reader over the provided entry collection.
static EntryReader	newEntryReader(Iterator<? extends Entry> entries)	Returns an entry reader over the provided entry iterator.
static EntryReader	patch(EntryReader input, ChangeRecordReader patch)	Applies the set of changes contained in patch to the content of input and returns the result in an entry reader.
static EntryReader	patch(EntryReader input, ChangeRecordReader patch, RejectedChangeRecordListener listener)	Applies the set of changes contained in patch to the content of input and returns the result in an entry reader.
static EntryReader	search(EntryReader input, SearchRequest search)	Returns a filtered view of input containing only those entries which match the search base DN, scope, and filtered defined in search.
static EntryReader	search(EntryReader input, SearchRequest search, Schema schema)	Returns a filtered view of input containing only those entries which match the search base DN, scope, and filtered defined in search.
static String	toLdif(Entry entry)	Returns the LDIF representation of entry.
static String	toLdif(ChangeRecord change)	Returns the LDIF representation of change.

Methods inherited from class java.lang.Object

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

Method Detail

newChangeRecordPublisher

public static Flowable<ChangeRecord> newChangeRecordPublisher(Supplier<? extends ChangeRecordReader> factory)

Returns a Flowable view of a ChangeRecordReader, creating a new reader for each subscriber.

Parameters:

factory - The factory which will be invoked for each subscriber.

Returns:

The Flowable view of a ChangeRecordReader.

newEntryPublisher

public static Flowable<Entry> newEntryPublisher(Supplier<? extends EntryReader> factory)

Returns a Flowable view of a EntryReader, creating a new reader for each subscriber.

Parameters:

factory - The factory which will be invoked for each subscriber.

Returns:

The Flowable view of a EntryReader.

copyTo

public static ChangeRecordWriter copyTo(ChangeRecordReader input,
                                        ChangeRecordWriter output)
                                 throws IOException

Copies the content of input to output. This method does not close input or output.

Parameters:

input - The input change record reader.

output - The output change record reader.

Returns:

The output change record reader.

Throws:

IOException - If an unexpected IO error occurred.

copyTo

public static EntryWriter copyTo(EntryReader input,
                                 EntryWriter output)
                          throws IOException

Copies the content of input to output. This method does not close input or output.

Parameters:

input - The input entry reader.

output - The output entry reader.

Returns:

The output entry reader.

Throws:

IOException - If an unexpected IO error occurred.

diff

public static ChangeRecordReader diff(EntryReader source,
                                      EntryReader target)
                               throws IOException

Compares the content of source to the content of target and returns the differences in a change record reader. Closing the returned reader will cause source and target to be closed as well.

NOTE: this method reads the content of source and target into memory before calculating the differences, and is therefore not suited for use in cases where a very large number of entries are to be compared.

Parameters:

source - The entry reader containing the source entries to be compared.

target - The entry reader containing the target entries to be compared.

Returns:

A change record reader containing the differences.

Throws:

IOException - If an unexpected IO error occurred.

diff

public static ChangeRecordReader diff(EntryReader source,
                                      EntryReader target,
                                      Options options)
                               throws IOException

Compares the content of source to the content of target and returns the differences in a change record reader. Closing the returned reader will cause source and target to be closed as well.

NOTE: this method reads the content of source and target into memory before calculating the differences, and is therefore not suited for use in cases where a very large number of entries are to be compared.

Parameters:

source - The entry reader containing the source entries to be compared.

target - The entry reader containing the target entries to be compared.

options - Options to control how entries are compared.

Returns:

A change record reader containing the differences.

Throws:

IOException - If an unexpected IO error occurred.

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.

makeEntry

public static Entry makeEntry(List<String> ldifLines)

Builds an entry from the provided lines of LDIF.

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.

See Also:

makeEntry(String...)

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.

makeEntries

public static List<Entry> makeEntries(List<String> ldifLines)

Builds a list of entries from the provided lines of LDIF.

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.

See Also:

makeEntries(String...)

newChangeRecordReader

public static ChangeRecordReader newChangeRecordReader(Iterable<? extends ChangeRecord> changes)

Returns a change record reader over the provided change record collection.

Parameters:

changes - The change record collection.

Returns:

A change record reader over the provided change record collection.

newChangeRecordReader

public static ChangeRecordReader newChangeRecordReader(Iterator<? extends ChangeRecord> changes)

Returns a change record reader over the provided change record iterator.

Parameters:

changes - The change record collection.

Returns:

A change record reader over the provided change record iterator.

newEntryReader

public static EntryReader newEntryReader(Iterable<? extends Entry> entries)

Returns an entry reader over the provided entry collection.

Parameters:

entries - The entry collection.

Returns:

An entry reader over the provided entry collection.

newEntryReader

public static EntryReader newEntryReader(Iterator<? extends Entry> entries)

Returns an entry reader over the provided entry iterator.

Parameters:

entries - The entry iterator.

Returns:

An entry reader over the provided entry iterator.

patch

public static EntryReader patch(EntryReader input,
                                ChangeRecordReader patch)
                         throws IOException

Applies the set of changes contained in patch to the content of input and returns the result in an entry reader. This method ignores missing entries, and overwrites existing entries. Closing the returned reader will cause input and patch to be closed as well.

NOTE: this method reads the content of input into memory before applying the changes, and is therefore not suited for use in cases where a very large number of entries are to be patched.

NOTE: this method will not perform modifications required in order to maintain referential integrity. In particular, if an entry references another entry using a DN valued attribute and the referenced entry is deleted, then the DN reference will not be removed. The same applies to renamed entries and their references.

Parameters:

input - The entry reader containing the set of entries to be patched.

patch - The change record reader containing the set of changes to be applied.

Returns:

An entry reader containing the patched entries.

Throws:

IOException - If an unexpected IO error occurred.

patch

public static EntryReader patch(EntryReader input,
                                ChangeRecordReader patch,
                                RejectedChangeRecordListener listener)
                         throws IOException

Applies the set of changes contained in patch to the content of input and returns the result in an entry reader. Closing the returned reader will cause input and patch to be closed as well.

NOTE: this method reads the content of input into memory before applying the changes, and is therefore not suited for use in cases where a very large number of entries are to be patched.

NOTE: this method will not perform modifications required in order to maintain referential integrity. In particular, if an entry references another entry using a DN valued attribute and the referenced entry is deleted, then the DN reference will not be removed. The same applies to renamed entries and their references.

Parameters:

input - The entry reader containing the set of entries to be patched.

patch - The change record reader containing the set of changes to be applied.

listener - The rejected change listener.

Returns:

An entry reader containing the patched entries.

Throws:

IOException - If an unexpected IO error occurred.

search

public static EntryReader search(EntryReader input,
                                 SearchRequest search)

Returns a filtered view of input containing only those entries which match the search base DN, scope, and filtered defined in search. In addition, returned entries will be filtered according to any attribute filtering criteria defined in the search request.

The filter and attribute descriptions will be decoded using the default schema.

Parameters:

input - The entry reader containing the set of entries to be filtered.

search - The search request defining the filtering criteria.

Returns:

A filtered view of input containing only those entries which match the provided search request.

search

public static EntryReader search(EntryReader input,
                                 SearchRequest search,
                                 Schema schema)

Returns a filtered view of input containing only those entries which match the search base DN, scope, and filtered defined in search. In addition, returned entries will be filtered according to any attribute filtering criteria defined in the search request.

The filter and attribute descriptions will be decoded using the provided schema.

Parameters:

input - The entry reader containing the set of entries to be filtered.

search - The search request defining the filtering criteria.

schema - The schema which should be used to decode the search filter and attribute descriptions.

Returns:

A filtered view of input containing only those entries which match the provided search request.

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.

toLdif

public static String toLdif(ChangeRecord change)

Returns the LDIF representation of change. No wrapping will be performed. This method can be useful when debugging applications.

Parameters:

change - The change record to be converted to LDIF.

Returns:

The LDIF representation of change.

makeChangeRecord

public static ChangeRecord makeChangeRecord(String... ldifLines)

Parses the provided array of LDIF lines as a single LDIF change record.

This method is tolerant to missing change types.

Parameters:

ldifLines - The lines of LDIF to be parsed.

Returns:

The parsed LDIF change record.

Throws:

LocalizedIllegalArgumentException - If ldifLines did not contain an LDIF change record, if it contained multiple change records, if contained malformed LDIF, or if the change record could not be decoded using the default schema.

NullPointerException - If ldifLines was null.