com.unboundid.ldif

Class LDIFReader

java.lang.Object

com.unboundid.ldif.LDIFReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

@ThreadSafety(level=NOT_THREADSAFE)
public final class LDIFReader
extends java.lang.Object
implements java.io.Closeable

This class provides an LDIF reader, which can be used to read and decode entries and change records from a data source using the LDAP Data Interchange Format as per RFC 2849.
This class is not synchronized. If multiple threads read from the LDIFReader, they must be synchronized externally.

Example

The following example iterates through all entries contained in an LDIF file and attempts to add them to a directory server:

 LDIFReader ldifReader = new LDIFReader(pathToLDIFFile);

 int entriesRead = 0;
 int entriesAdded = 0;
 int errorsEncountered = 0;
 while (true)
 {
   Entry entry;
   try
   {
     entry = ldifReader.readEntry();
     if (entry == null)
     {
       // All entries have been read.
       break;
     }

     entriesRead++;
   }
   catch (LDIFException le)
   {
     errorsEncountered++;
     if (le.mayContinueReading())
     {
       // A recoverable error occurred while attempting to read a change
       // record, at or near line number le.getLineNumber()
       // The entry will be skipped, but we'll try to keep reading from the
       // LDIF file.
       continue;
     }
     else
     {
       // An unrecoverable error occurred while attempting to read an entry
       // at or near line number le.getLineNumber()
       // No further LDIF processing will be performed.
       break;
     }
   }
   catch (IOException ioe)
   {
     // An I/O error occurred while attempting to read from the LDIF file.
     // No further LDIF processing will be performed.
     errorsEncountered++;
     break;
   }

   LDAPResult addResult;
   try
   {
     addResult = connection.add(entry);
     // If we got here, then the change should have been processed
     // successfully.
     entriesAdded++;
   }
   catch (LDAPException le)
   {
     // If we got here, then the change attempt failed.
     addResult = le.toLDAPResult();
     errorsEncountered++;
   }
 }

 ldifReader.close();
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BUFFER_SIZE The default buffer size (128KB) that will be used when reading from the data source.

Constructor Summary

Constructors

Constructor and Description
LDIFReader(java.io.BufferedReader reader) Creates a new LDIF reader that will use the provided buffered reader to read the LDIF data.
LDIFReader(java.io.BufferedReader reader, int numParseThreads) Creates a new LDIF reader that will read data from the specified buffered reader and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.BufferedReader reader, int numParseThreads, LDIFReaderEntryTranslator entryTranslator) Creates a new LDIF reader that will read data from the specified buffered reader and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.BufferedReader reader, int numParseThreads, LDIFReaderEntryTranslator entryTranslator, LDIFReaderChangeRecordTranslator changeRecordTranslator) Creates a new LDIF reader that will read data from the specified buffered reader and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.File file) Creates a new LDIF reader that will read data from the specified file.
LDIFReader(java.io.File[] files, int numParseThreads, LDIFReaderEntryTranslator entryTranslator) Creates a new LDIF reader that will read data from the specified files in the order in which they are provided and optionally parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.File[] files, int numParseThreads, LDIFReaderEntryTranslator entryTranslator, LDIFReaderChangeRecordTranslator changeRecordTranslator) Creates a new LDIF reader that will read data from the specified files in the order in which they are provided and optionally parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.File[] files, int numParseThreads, LDIFReaderEntryTranslator entryTranslator, LDIFReaderChangeRecordTranslator changeRecordTranslator, java.lang.String characterSet) Creates a new LDIF reader that will read data from the specified files in the order in which they are provided and optionally parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.File file, int numParseThreads) Creates a new LDIF reader that will read data from the specified file and optionally parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.InputStream inputStream) Creates a new LDIF reader that will read data from the provided input stream.
LDIFReader(java.io.InputStream inputStream, int numParseThreads) Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.InputStream inputStream, int numParseThreads, LDIFReaderEntryTranslator entryTranslator) Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.InputStream inputStream, int numParseThreads, LDIFReaderEntryTranslator entryTranslator, LDIFReaderChangeRecordTranslator changeRecordTranslator) Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.io.InputStream inputStream, int numParseThreads, LDIFReaderEntryTranslator entryTranslator, LDIFReaderChangeRecordTranslator changeRecordTranslator, java.lang.String characterSet) Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.
LDIFReader(java.lang.String path) Creates a new LDIF reader that will read data from the specified file.
LDIFReader(java.lang.String path, int numParseThreads) Creates a new LDIF reader that will read data from the specified file and parses the LDIF records asynchronously using the specified number of threads.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this LDIF reader and the underlying LDIF source.
static LDIFChangeRecord	decodeChangeRecord(boolean ignoreDuplicateValues, Schema schema, boolean defaultAdd, java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an LDIF change record.
static LDIFChangeRecord	decodeChangeRecord(boolean defaultAdd, java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an LDIF change record.
static LDIFChangeRecord	decodeChangeRecord(boolean ignoreDuplicateValues, TrailingSpaceBehavior trailingSpaceBehavior, Schema schema, boolean defaultAdd, java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an LDIF change record.
static LDIFChangeRecord	decodeChangeRecord(java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an LDIF change record.
static Entry	decodeEntry(boolean ignoreDuplicateValues, Schema schema, java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an entry.
static Entry	decodeEntry(boolean ignoreDuplicateValues, TrailingSpaceBehavior trailingSpaceBehavior, Schema schema, java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an entry.
static Entry	decodeEntry(java.lang.String... ldifLines) Decodes the provided set of LDIF lines as an entry.
static LDIFRecord	decodeLDIFRecord(DuplicateValueBehavior duplicateValueBehavior, TrailingSpaceBehavior trailingSpaceBehavior, Schema schema, java.lang.String... ldifLines) Decodes the provided set of lines as an LDIF record.
static LDIFRecord	decodeLDIFRecord(java.lang.String... ldifLines) Decodes the provided set of lines as an LDIF record.
DuplicateValueBehavior	getDuplicateValueBehavior() Retrieves the behavior that should be exhibited if the LDIF reader encounters an entry with duplicate values.
java.lang.String	getRelativeBasePath() Retrieves the base path that will be prepended to relative paths in order to obtain an absolute path.
Schema	getSchema() Retrieves the schema that will be used when reading LDIF records, if defined.
TrailingSpaceBehavior	getTrailingSpaceBehavior() Retrieves the behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces.
boolean	ignoreDuplicateValues() Deprecated. Use the getDuplicateValueBehavior() method instead.
LDIFChangeRecord	readChangeRecord() Reads an LDIF change record from the LDIF source.
LDIFChangeRecord	readChangeRecord(boolean defaultAdd) Reads an LDIF change record from the LDIF source.
static java.util.List<Entry>	readEntries(java.io.File file) Reads entries from the specified LDIF file and returns them as a List.
static java.util.List<Entry>	readEntries(java.io.InputStream inputStream) Reads and decodes LDIF entries from the provided input stream and returns them as a List.
static java.util.List<Entry>	readEntries(java.lang.String path) Reads entries from the LDIF file with the specified path and returns them as a List.
Entry	readEntry() Reads an entry from the LDIF source.
LDIFRecord	readLDIFRecord() Reads a record from the LDIF source.
void	setDuplicateValueBehavior(DuplicateValueBehavior duplicateValueBehavior) Specifies the behavior that should be exhibited if the LDIF reader encounters an entry with duplicate values.
void	setIgnoreDuplicateValues(boolean ignoreDuplicateValues) Deprecated. Use the setDuplicateValueBehavior(com.unboundid.ldif.DuplicateValueBehavior) method instead.
void	setRelativeBasePath(java.io.File relativeBasePath) Specifies the base path that will be prepended to relative paths in order to obtain an absolute path.
void	setRelativeBasePath(java.lang.String relativeBasePath) Specifies the base path that will be prepended to relative paths in order to obtain an absolute path.
void	setSchema(Schema schema) Specifies the schema that should be used when reading LDIF records.
void	setStripTrailingSpaces(boolean stripTrailingSpaces) Deprecated. Use the setTrailingSpaceBehavior(com.unboundid.ldif.TrailingSpaceBehavior) method instead.
static void	setSupportControls(boolean supportControls) Specifies whether the LDIF reader will attempt to handle LDAP controls contained in LDIF records.
void	setTrailingSpaceBehavior(TrailingSpaceBehavior trailingSpaceBehavior) Specifies the behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces.
boolean	stripTrailingSpaces() Deprecated. Use the getTrailingSpaceBehavior() method instead.
static boolean	supportControls() Indicates whether the LDIF reader will attempt to handle LDAP controls contained in LDIF records.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The default buffer size (128KB) that will be used when reading from the data source.

See Also:

Constant Field Values

Constructor Detail

LDIFReader

public LDIFReader(@NotNull
                  java.lang.String path)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified file.

Parameters:

path - The path to the file from which the data is to be read. It must not be null.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

LDIFReader

public LDIFReader(@NotNull
                  java.lang.String path,
                  int numParseThreads)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified file and parses the LDIF records asynchronously using the specified number of threads.

Parameters:

path - The path to the file from which the data is to be read. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

See Also:

constructor for more details about asynchronous processing.

LDIFReader

public LDIFReader(@NotNull
                  java.io.File file)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified file.

Parameters:

file - The file from which the data is to be read. It must not be null.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

LDIFReader

public LDIFReader(@NotNull
                  java.io.File file,
                  int numParseThreads)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified file and optionally parses the LDIF records asynchronously using the specified number of threads.

Parameters:

file - The file from which the data is to be read. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

LDIFReader

public LDIFReader(@NotNull
                  java.io.File[] files,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified files in the order in which they are provided and optionally parses the LDIF records asynchronously using the specified number of threads.

Parameters:

files - The files from which the data is to be read. It must not be null or empty.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

LDIFReader

public LDIFReader(@NotNull
                  java.io.File[] files,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator,
                  @Nullable
                  LDIFReaderChangeRecordTranslator changeRecordTranslator)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified files in the order in which they are provided and optionally parses the LDIF records asynchronously using the specified number of threads.

Parameters:

files - The files from which the data is to be read. It must not be null or empty.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

changeRecordTranslator - The LDIFReaderChangeRecordTranslator to apply to change records before they are returned. This is normally null, which causes change records to be returned unaltered. This is particularly useful when parsing the input file in parallel because the change record translation is also done in parallel.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

LDIFReader

public LDIFReader(@NotNull
                  java.io.File[] files,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator,
                  @Nullable
                  LDIFReaderChangeRecordTranslator changeRecordTranslator,
                  @NotNull
                  java.lang.String characterSet)
           throws java.io.IOException

Creates a new LDIF reader that will read data from the specified files in the order in which they are provided and optionally parses the LDIF records asynchronously using the specified number of threads.

Parameters:

files - The files from which the data is to be read. It must not be null or empty.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

changeRecordTranslator - The LDIFReaderChangeRecordTranslator to apply to change records before they are returned. This is normally null, which causes change records to be returned unaltered. This is particularly useful when parsing the input file in parallel because the change record translation is also done in parallel.

characterSet - The character set to use when reading from the input stream. It must not be null.

Throws:

java.io.IOException - If a problem occurs while opening the file for reading.

LDIFReader

public LDIFReader(@NotNull
                  java.io.InputStream inputStream)

Creates a new LDIF reader that will read data from the provided input stream.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

LDIFReader

public LDIFReader(@NotNull
                  java.io.InputStream inputStream,
                  int numParseThreads)

Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

See Also:

constructor for more details about asynchronous processing.

LDIFReader

public LDIFReader(@NotNull
                  java.io.InputStream inputStream,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator)

Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to read entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

See Also:

constructor for more details about asynchronous processing.

LDIFReader

public LDIFReader(@NotNull
                  java.io.InputStream inputStream,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator,
                  @Nullable
                  LDIFReaderChangeRecordTranslator changeRecordTranslator)

Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

changeRecordTranslator - The LDIFReaderChangeRecordTranslator to apply to change records before they are returned. This is normally null, which causes change records to be returned unaltered. This is particularly useful when parsing the input file in parallel because the change record translation is also done in parallel.

See Also:

constructor for more details about asynchronous processing.

LDIFReader

public LDIFReader(@NotNull
                  java.io.InputStream inputStream,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator,
                  @Nullable
                  LDIFReaderChangeRecordTranslator changeRecordTranslator,
                  @NotNull
                  java.lang.String characterSet)

Creates a new LDIF reader that will read data from the specified stream and parses the LDIF records asynchronously using the specified number of threads.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

changeRecordTranslator - The LDIFReaderChangeRecordTranslator to apply to change records before they are returned. This is normally null, which causes change records to be returned unaltered. This is particularly useful when parsing the input file in parallel because the change record translation is also done in parallel.

characterSet - The character set to use when reading from the input stream. It must not be null.

See Also:

constructor for more details about asynchronous processing.

LDIFReader

public LDIFReader(@NotNull
                  java.io.BufferedReader reader)

Creates a new LDIF reader that will use the provided buffered reader to read the LDIF data. The encoding of the underlying Reader must be set to "UTF-8" as required by RFC 2849.

Parameters:

reader - The buffered reader that will be used to read the LDIF data. It must not be null.

LDIFReader

public LDIFReader(@NotNull
                  java.io.BufferedReader reader,
                  int numParseThreads)

Creates a new LDIF reader that will read data from the specified buffered reader and parses the LDIF records asynchronously using the specified number of threads. The encoding of the underlying Reader must be set to "UTF-8" as required by RFC 2849.

Parameters:

reader - The buffered reader that will be used to read the LDIF data. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

See Also:

constructor for more details about asynchronous processing.

LDIFReader

public LDIFReader(@NotNull
                  java.io.BufferedReader reader,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator)

Creates a new LDIF reader that will read data from the specified buffered reader and parses the LDIF records asynchronously using the specified number of threads. The encoding of the underlying Reader must be set to "UTF-8" as required by RFC 2849.

Parameters:

reader - The buffered reader that will be used to read the LDIF data. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file. This should only be set to greater than zero when performance analysis has demonstrated that reading and parsing the LDIF is a bottleneck. The default synchronous processing is normally fast enough. There is little benefit in passing in a value greater than four (unless there is an LDIFReaderEntryTranslator that does time-consuming processing). A value of zero implies the default behavior of reading and parsing LDIF records synchronously when one of the read methods is called.

entryTranslator - The LDIFReaderEntryTranslator to apply to read entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

LDIFReader

public LDIFReader(@NotNull
                  java.io.BufferedReader reader,
                  int numParseThreads,
                  @Nullable
                  LDIFReaderEntryTranslator entryTranslator,
                  @Nullable
                  LDIFReaderChangeRecordTranslator changeRecordTranslator)

Creates a new LDIF reader that will read data from the specified buffered reader and parses the LDIF records asynchronously using the specified number of threads. The encoding of the underlying Reader must be set to "UTF-8" as required by RFC 2849.

Parameters:

reader - The buffered reader that will be used to read the LDIF data. It must not be null.

numParseThreads - If this value is greater than zero, then the specified number of threads will be used to asynchronously read and parse the LDIF file.

entryTranslator - The LDIFReaderEntryTranslator to apply to entries before they are returned. This is normally null, which causes entries to be returned unaltered. This is particularly useful when parsing the input file in parallel because the entry translation is also done in parallel.

changeRecordTranslator - The LDIFReaderChangeRecordTranslator to apply to change records before they are returned. This is normally null, which causes change records to be returned unaltered. This is particularly useful when parsing the input file in parallel because the change record translation is also done in parallel.

Method Detail

readEntries

@NotNull
public static java.util.List<Entry> readEntries(@NotNull
                                                         java.lang.String path)
                                                  throws java.io.IOException,
                                                         LDIFException

Reads entries from the LDIF file with the specified path and returns them as a List. This is a convenience method that should only be used for data sets that are small enough so that running out of memory isn't a concern.

Parameters:

path - The path to the LDIF file containing the entries to be read.

Returns:

A list of the entries read from the given LDIF file.

Throws:

java.io.IOException - If a problem occurs while attempting to read data from the specified file.

LDIFException - If a problem is encountered while attempting to decode data read as LDIF.

readEntries

@NotNull
public static java.util.List<Entry> readEntries(@NotNull
                                                         java.io.File file)
                                                  throws java.io.IOException,
                                                         LDIFException

Reads entries from the specified LDIF file and returns them as a List. This is a convenience method that should only be used for data sets that are small enough so that running out of memory isn't a concern.

Parameters:

file - A reference to the LDIF file containing the entries to be read.

Returns:

A list of the entries read from the given LDIF file.

Throws:

java.io.IOException - If a problem occurs while attempting to read data from the specified file.

LDIFException - If a problem is encountered while attempting to decode data read as LDIF.

readEntries

@NotNull
public static java.util.List<Entry> readEntries(@NotNull
                                                         java.io.InputStream inputStream)
                                                  throws java.io.IOException,
                                                         LDIFException

Reads and decodes LDIF entries from the provided input stream and returns them as a List. This is a convenience method that should only be used for data sets that are small enough so that running out of memory isn't a concern.

Parameters:

inputStream - The input stream from which the entries should be read. The input stream will be closed before returning.

Returns:

A list of the entries read from the given input stream.

Throws:

java.io.IOException - If a problem occurs while attempting to read data from the input stream.

LDIFException - If a problem is encountered while attempting to decode data read as LDIF.

close

public void close()
           throws java.io.IOException

Closes this LDIF reader and the underlying LDIF source.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - If a problem occurs while closing the underlying LDIF source.

ignoreDuplicateValues

@Deprecated
public boolean ignoreDuplicateValues()

Deprecated. Use the getDuplicateValueBehavior() method instead.

Indicates whether to ignore any duplicate values encountered while reading LDIF records.

Returns:

true if duplicate values should be ignored, or false if any LDIF records containing duplicate values should be rejected.

setIgnoreDuplicateValues

@Deprecated
public void setIgnoreDuplicateValues(boolean ignoreDuplicateValues)

Deprecated. Use the setDuplicateValueBehavior(com.unboundid.ldif.DuplicateValueBehavior) method instead.

Specifies whether to ignore any duplicate values encountered while reading LDIF records.

Parameters:

ignoreDuplicateValues - Indicates whether to ignore duplicate attribute values encountered while reading LDIF records.

getDuplicateValueBehavior

@NotNull
public DuplicateValueBehavior getDuplicateValueBehavior()

Retrieves the behavior that should be exhibited if the LDIF reader encounters an entry with duplicate values.

Returns:

The behavior that should be exhibited if the LDIF reader encounters an entry with duplicate values.

setDuplicateValueBehavior

public void setDuplicateValueBehavior(@NotNull
                                      DuplicateValueBehavior duplicateValueBehavior)

Specifies the behavior that should be exhibited if the LDIF reader encounters an entry with duplicate values.

Parameters:

duplicateValueBehavior - The behavior that should be exhibited if the LDIF reader encounters an entry with duplicate values.

stripTrailingSpaces

@Deprecated
public boolean stripTrailingSpaces()

Deprecated. Use the getTrailingSpaceBehavior() method instead.

Indicates whether to strip off any illegal trailing spaces that may appear in LDIF records (e.g., after an entry DN or attribute value). The LDIF specification strongly recommends that any value which legitimately contains trailing spaces be base64-encoded, and any spaces which appear after the end of non-base64-encoded values may therefore be considered invalid. If any such trailing spaces are encountered in an LDIF record and they are not to be stripped, then an LDIFException will be thrown for that record.

Note that this applies only to spaces after the end of a value, and not to spaces which may appear at the end of a line for a value that is wrapped and continued on the next line.

Returns:

true if illegal trailing spaces should be stripped off, or false if LDIF records containing illegal trailing spaces should be rejected.

setStripTrailingSpaces

@Deprecated
public void setStripTrailingSpaces(boolean stripTrailingSpaces)

Deprecated. Use the setTrailingSpaceBehavior(com.unboundid.ldif.TrailingSpaceBehavior) method instead.

Specifies whether to strip off any illegal trailing spaces that may appear in LDIF records (e.g., after an entry DN or attribute value). The LDIF specification strongly recommends that any value which legitimately contains trailing spaces be base64-encoded, and any spaces which appear after the end of non-base64-encoded values may therefore be considered invalid. If any such trailing spaces are encountered in an LDIF record and they are not to be stripped, then an LDIFException will be thrown for that record.

Note that this applies only to spaces after the end of a value, and not to spaces which may appear at the end of a line for a value that is wrapped and continued on the next line.

Parameters:

stripTrailingSpaces - Indicates whether to strip off any illegal trailing spaces, or false if LDIF records containing them should be rejected.

getTrailingSpaceBehavior

@NotNull
public TrailingSpaceBehavior getTrailingSpaceBehavior()

Retrieves the behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces. The LDIF specification strongly recommends that any value which legitimately contains trailing spaces be base64-encoded, but the LDAP SDK LDIF parser may be configured to automatically strip these spaces, to preserve them, or to reject any entry or change record containing them.

Returns:

The behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces.

setTrailingSpaceBehavior

public void setTrailingSpaceBehavior(@NotNull
                                     TrailingSpaceBehavior trailingSpaceBehavior)

Specifies the behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces. The LDIF specification strongly recommends that any value which legitimately contains trailing spaces be base64-encoded, but the LDAP SDK LDIF parser may be configured to automatically strip these spaces, to preserve them, or to reject any entry or change record containing them.

Parameters:

trailingSpaceBehavior - The behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces.

supportControls

public static boolean supportControls()

Indicates whether the LDIF reader will attempt to handle LDAP controls contained in LDIF records. See the documentation for the setSupportControls(boolean) method for a more complete explanation.

Returns:

true if the LDIF reader will attempt to handle controls contained in LDIF records, or false if it will not and they will be treated as regular attributes.

setSupportControls

public static void setSupportControls(boolean supportControls)

Specifies whether the LDIF reader will attempt to handle LDAP controls contained in LDIF records. By default, the LDAP SDK will handle controls in accordance with RFC 2849, so that if the first unwrapped line after the DN starts with "control:", then that record will be assumed to be an LDIF change record that contains one or more LDAP controls. However, this can potentially cause a problem in one corner case: the case in which an LDIF record represents an entry in which the first attribute in the entry is named "control", and when you're either reading a generic LDIF record or you're reading an LDIF change record with defaultAdd set to true. In such case, the LDIF reader would assume that the "control" attribute is trying to specify an LDAP control, and it would either throw an exception if it can't parse the value as a control, or it would return an LDIF add change record without the "control" attribute but with an LDAP control. Calling this method with a value of false will disable the LDIF reader's support for controls so that any record in which the unwrapped line immediately following the DN starts with "control:" will be treated as specifying an attribute named "control" rather than an LDAP control.

Parameters:

supportControls - Specifies whether the LDIF reader will attempt to handle LDAP controls contained in LDIF records.

getRelativeBasePath

@NotNull
public java.lang.String getRelativeBasePath()

Retrieves the base path that will be prepended to relative paths in order to obtain an absolute path. This will only be used for "file:" URLs that have paths which do not begin with a slash.

Returns:

The base path that will be prepended to relative paths in order to obtain an absolute path.

setRelativeBasePath

public void setRelativeBasePath(@NotNull
                                java.lang.String relativeBasePath)

Specifies the base path that will be prepended to relative paths in order to obtain an absolute path. This will only be used for "file:" URLs that have paths which do not begin with a space.

Parameters:

relativeBasePath - The base path that will be prepended to relative paths in order to obtain an absolute path.

setRelativeBasePath

public void setRelativeBasePath(@NotNull
                                java.io.File relativeBasePath)

Specifies the base path that will be prepended to relative paths in order to obtain an absolute path. This will only be used for "file:" URLs that have paths which do not begin with a space.

Parameters:

relativeBasePath - The base path that will be prepended to relative paths in order to obtain an absolute path.

getSchema

@Nullable
public Schema getSchema()

Retrieves the schema that will be used when reading LDIF records, if defined.

Returns:

The schema that will be used when reading LDIF records, or null if no schema should be used and all attributes should be treated as case-insensitive strings.

setSchema

public void setSchema(@Nullable
                      Schema schema)

Specifies the schema that should be used when reading LDIF records.

Parameters:

schema - The schema that should be used when reading LDIF records, or null if no schema should be used and all attributes should be treated as case-insensitive strings.

readLDIFRecord

@Nullable
public LDIFRecord readLDIFRecord()
                                    throws java.io.IOException,
                                           LDIFException

Reads a record from the LDIF source. It may be either an entry or an LDIF change record.

Returns:

The record read from the LDIF source, or null if there are no more entries to be read.

Throws:

java.io.IOException - If a problem occurs while trying to read from the LDIF source.

LDIFException - If the data read could not be parsed as an entry or an LDIF change record.

decodeLDIFRecord

@NotNull
public static LDIFRecord decodeLDIFRecord(@NotNull
                                                   java.lang.String... ldifLines)
                                            throws LDIFException

Decodes the provided set of lines as an LDIF record. It may be either an entry or an LDIF change record.

Parameters:

ldifLines - The set of lines that comprise the LDIF representation of the entry or change record. It must not be null or empty.

Returns:

The decoded LDIF entry or change record.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as an LDIF record.

decodeLDIFRecord

@NotNull
public static LDIFRecord decodeLDIFRecord(@NotNull
                                                   DuplicateValueBehavior duplicateValueBehavior,
                                                   @NotNull
                                                   TrailingSpaceBehavior trailingSpaceBehavior,
                                                   @Nullable
                                                   Schema schema,
                                                   @NotNull
                                                   java.lang.String... ldifLines)
                                            throws LDIFException

Decodes the provided set of lines as an LDIF record. It may be either an entry or an LDIF change record.

Parameters:

duplicateValueBehavior - The behavior that should be exhibited when encountering LDIF records that have duplicate attribute values. It must not be null.

trailingSpaceBehavior - The behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces. It must not be null.

schema - The schema to use when processing the change record, or null if no schema should be used and all values should be treated as case-insensitive strings.

ldifLines - The set of lines that comprise the LDIF representation of the entry or change record. It must not be null or empty.

Returns:

The decoded LDIF entry or change record.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as an LDIF record.

readEntry

@Nullable
public Entry readEntry()
                          throws java.io.IOException,
                                 LDIFException

Reads an entry from the LDIF source.

Returns:

The entry read from the LDIF source, or null if there are no more entries to be read.

Throws:

java.io.IOException - If a problem occurs while attempting to read from the LDIF source.

LDIFException - If the data read could not be parsed as an entry.

readChangeRecord

@Nullable
public LDIFChangeRecord readChangeRecord()
                                            throws java.io.IOException,
                                                   LDIFException

Reads an LDIF change record from the LDIF source. The LDIF record must have a changetype.

Returns:

The change record read from the LDIF source, or null if there are no more records to be read.

Throws:

java.io.IOException - If a problem occurs while attempting to read from the LDIF source.

LDIFException - If the data read could not be parsed as an LDIF change record.

readChangeRecord

@Nullable
public LDIFChangeRecord readChangeRecord(boolean defaultAdd)
                                            throws java.io.IOException,
                                                   LDIFException

Reads an LDIF change record from the LDIF source. Optionally, if the LDIF record does not have a changetype, then it may be assumed to be an add change record.

Parameters:

defaultAdd - Indicates whether an LDIF record not containing a changetype should be retrieved as an add change record. If this is false and the record read does not include a changetype, then an LDIFException will be thrown.

Returns:

The change record read from the LDIF source, or null if there are no more records to be read.

Throws:

java.io.IOException - If a problem occurs while attempting to read from the LDIF source.

LDIFException - If the data read could not be parsed as an LDIF change record.

decodeEntry

@NotNull
public static Entry decodeEntry(@NotNull
                                         java.lang.String... ldifLines)
                                  throws LDIFException

Decodes the provided set of LDIF lines as an entry. The provided set of lines must contain exactly one entry. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry. A default trailing space behavior of TrailingSpaceBehavior.REJECT will be used.

Parameters:

ldifLines - The set of lines that comprise the LDIF representation of the entry. It must not be null or empty.

Returns:

The entry read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as an entry.

decodeEntry

@NotNull
public static Entry decodeEntry(boolean ignoreDuplicateValues,
                                         @Nullable
                                         Schema schema,
                                         @NotNull
                                         java.lang.String... ldifLines)
                                  throws LDIFException

Decodes the provided set of LDIF lines as an entry. The provided set of lines must contain exactly one entry. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry. A default trailing space behavior of TrailingSpaceBehavior.REJECT will be used.

Parameters:

ignoreDuplicateValues - Indicates whether to ignore duplicate attribute values encountered while parsing.

schema - The schema to use when parsing the record, if applicable.

ldifLines - The set of lines that comprise the LDIF representation of the entry. It must not be null or empty.

Returns:

The entry read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as an entry.

decodeEntry

@NotNull
public static Entry decodeEntry(boolean ignoreDuplicateValues,
                                         @NotNull
                                         TrailingSpaceBehavior trailingSpaceBehavior,
                                         @Nullable
                                         Schema schema,
                                         @NotNull
                                         java.lang.String... ldifLines)
                                  throws LDIFException

Decodes the provided set of LDIF lines as an entry. The provided set of lines must contain exactly one entry. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry.

Parameters:

ignoreDuplicateValues - Indicates whether to ignore duplicate attribute values encountered while parsing.

trailingSpaceBehavior - The behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces. It must not be null.

schema - The schema to use when parsing the record, if applicable.

ldifLines - The set of lines that comprise the LDIF representation of the entry. It must not be null or empty.

Returns:

The entry read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as an entry.

decodeChangeRecord

@NotNull
public static LDIFChangeRecord decodeChangeRecord(@NotNull
                                                           java.lang.String... ldifLines)
                                                    throws LDIFException

Decodes the provided set of LDIF lines as an LDIF change record. The provided set of lines must contain exactly one change record and it must include a changetype. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry.

Parameters:

ldifLines - The set of lines that comprise the LDIF representation of the change record. It must not be null or empty.

Returns:

The change record read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as a change record.

decodeChangeRecord

@NotNull
public static LDIFChangeRecord decodeChangeRecord(boolean defaultAdd,
                                                           @NotNull
                                                           java.lang.String... ldifLines)
                                                    throws LDIFException

Decodes the provided set of LDIF lines as an LDIF change record. The provided set of lines must contain exactly one change record. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry.

Parameters:

defaultAdd - Indicates whether an LDIF record not containing a changetype should be retrieved as an add change record. If this is false and the record read does not include a changetype, then an LDIFException will be thrown.

ldifLines - The set of lines that comprise the LDIF representation of the change record. It must not be null or empty.

Returns:

The change record read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as a change record.

decodeChangeRecord

@NotNull
public static LDIFChangeRecord decodeChangeRecord(boolean ignoreDuplicateValues,
                                                           @Nullable
                                                           Schema schema,
                                                           boolean defaultAdd,
                                                           @NotNull
                                                           java.lang.String... ldifLines)
                                                    throws LDIFException

Decodes the provided set of LDIF lines as an LDIF change record. The provided set of lines must contain exactly one change record. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry.

Parameters:

ignoreDuplicateValues - Indicates whether to ignore duplicate attribute values encountered while parsing.

schema - The schema to use when processing the change record, or null if no schema should be used and all values should be treated as case-insensitive strings.

defaultAdd - Indicates whether an LDIF record not containing a changetype should be retrieved as an add change record. If this is false and the record read does not include a changetype, then an LDIFException will be thrown.

ldifLines - The set of lines that comprise the LDIF representation of the change record. It must not be null or empty.

Returns:

The change record read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as a change record.

decodeChangeRecord

@NotNull
public static LDIFChangeRecord decodeChangeRecord(boolean ignoreDuplicateValues,
                                                           @NotNull
                                                           TrailingSpaceBehavior trailingSpaceBehavior,
                                                           @Nullable
                                                           Schema schema,
                                                           boolean defaultAdd,
                                                           @NotNull
                                                           java.lang.String... ldifLines)
                                                    throws LDIFException

Decodes the provided set of LDIF lines as an LDIF change record. The provided set of lines must contain exactly one change record. Long lines may be wrapped as per the LDIF specification, and it is acceptable to have one or more blank lines following the entry.

Parameters:

ignoreDuplicateValues - Indicates whether to ignore duplicate attribute values encountered while parsing.

trailingSpaceBehavior - The behavior that should be exhibited when encountering attribute values which are not base64-encoded but contain trailing spaces. It must not be null.

schema - The schema to use when processing the change record, or null if no schema should be used and all values should be treated as case-insensitive strings.

defaultAdd - Indicates whether an LDIF record not containing a changetype should be retrieved as an add change record. If this is false and the record read does not include a changetype, then an LDIFException will be thrown.

ldifLines - The set of lines that comprise the LDIF representation of the change record. It must not be null or empty.

Returns:

The change record read from LDIF.

Throws:

LDIFException - If the provided LDIF data cannot be decoded as a change record.