org.opends.server.util

Class LDIFReader

java.lang.Object

org.opends.server.util.LDIFReader

All Implemented Interfaces:

Closeable, AutoCloseable

@PublicAPI(stability=UNCOMMITTED,
           mayInstantiate=true,
           mayInvoke=true)
public class LDIFReader
extends Object
implements Closeable

This class provides the ability to read information from an LDIF file. It provides support for both standard entries and change entries (as would be used with a tool like ldapmodify).

Field Summary

Fields

Modifier and Type	Field and Description
protected AtomicLong	entriesRead The number of entries that have been read by this LDIF reader, including those that were ignored because they didn't match the criteria, and including those that were rejected because they were invalid in some way.
protected LDIFImportConfig	importConfig The import configuration that specifies what should be imported.
protected List<StringBuilder>	lastEntryBodyLines The lines that comprise the body of the last entry read.
protected List<StringBuilder>	lastEntryHeaderLines The lines that comprise the header (DN and any comments) for the last entry read.
protected long	lastEntryLineNumber The line number on which the last entry started.
protected PluginConfigManager	pluginConfigManager The plugin config manager that will be used if we are to invoke plugins on the entries as they are read.

Constructor Summary

Constructors

Constructor and Description
LDIFReader(LDIFImportConfig importConfig) Creates a new LDIF reader that will read information from the specified file.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this LDIF reader and the underlying file or input stream.
protected Entry	createEntry(Dn entryDN, List<StringBuilder> lines, boolean checkSchema) Parses the provided LDIF lines as an LDAP entry.
long	getEntriesIgnored() Retrieves the total number of entries that have been ignored so far by this LDIF reader because they did not match the import criteria.
long	getEntriesRead() Retrieves the total number of entries read so far by this LDIF reader, including those that have been ignored or rejected.
long	getEntriesRejected() Retrieves the total number of entries rejected so far by this LDIF reader.
protected void	logToRejectWriter(List<StringBuilder> lines, LocalizableMessage message) Log a message to the reject writer if one is configured.
protected void	logToSkipWriter(List<StringBuilder> lines, LocalizableMessage message) Log a message to the reject writer if one is configured.
ChangeRecord	readChangeRecord(boolean defaultAdd) Reads the next change record from the LDIF source.
protected Dn	readDN(LinkedList<StringBuilder> lines) Reads the DN of the entry from the provided list of lines.
Entry	readEntry() Reads the next entry from the LDIF source.
Entry	readEntry(boolean checkSchema) Reads the next entry from the LDIF source.
protected LinkedList<StringBuilder>	readEntryLines() Reads a set of lines from the next entry in the LDIF source.
void	rejectEntry(Entry e, LocalizableMessage message) Log the specified entry and messages in the reject writer.
void	rejectLastEntry(LocalizableMessage message) Rejects the last entry read from the LDIF.

Methods inherited from class java.lang.Object

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

Field Detail

importConfig

protected final LDIFImportConfig importConfig

The import configuration that specifies what should be imported.

lastEntryBodyLines

protected List<StringBuilder> lastEntryBodyLines

The lines that comprise the body of the last entry read.

lastEntryHeaderLines

protected List<StringBuilder> lastEntryHeaderLines

The lines that comprise the header (DN and any comments) for the last entry read.

entriesRead

protected final AtomicLong entriesRead

The number of entries that have been read by this LDIF reader, including those that were ignored because they didn't match the criteria, and including those that were rejected because they were invalid in some way.

lastEntryLineNumber

protected long lastEntryLineNumber

The line number on which the last entry started.

pluginConfigManager

protected final PluginConfigManager pluginConfigManager

The plugin config manager that will be used if we are to invoke plugins on the entries as they are read.

Constructor Detail

LDIFReader

public LDIFReader(LDIFImportConfig importConfig)
           throws IOException

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

Parameters:

importConfig - The import configuration for this LDIF reader. It must not be null.

Throws:

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

Method Detail

readEntry

public Entry readEntry()
                throws IOException,
                       LDIFException

Reads the next entry from the LDIF source.

Returns:

The next entry read from the LDIF source, or null if the end of the LDIF data is reached.

Throws:

IOException - If an I/O problem occurs while reading from the file.

LDIFException - If the information read cannot be parsed as an LDIF entry.

readEntry

public Entry readEntry(boolean checkSchema)
                throws IOException,
                       LDIFException

Reads the next entry from the LDIF source.

Parameters:

checkSchema - Indicates whether this reader should perform schema checking on the entry before returning it to the caller. Note that some basic schema checking (like refusing multiple values for a single-valued attribute) may always be performed.

Returns:

The next entry read from the LDIF source, or null if the end of the LDIF data is reached.

Throws:

IOException - If an I/O problem occurs while reading from the file.

LDIFException - If the information read cannot be parsed as an LDIF entry.

createEntry

protected Entry createEntry(Dn entryDN,
                            List<StringBuilder> lines,
                            boolean checkSchema)
                     throws LDIFException

Parses the provided LDIF lines as an LDAP entry.

Parameters:

entryDN - The parsed entry DN.

lines - The lines of LDIF.

checkSchema - Whether attributes should be validated.

Returns:

The parsed LDAP entry.

Throws:

LDIFException - If the attributes could not be parsed.

readChangeRecord

public ChangeRecord readChangeRecord(boolean defaultAdd)
                              throws IOException,
                                     LDIFException

Reads the next change record from the LDIF source.

Parameters:

defaultAdd - Indicates whether the change type should default to "add" if none is explicitly provided.

Returns:

The next change record from the LDIF source, or null if the end of the LDIF data is reached.

Throws:

IOException - If an I/O problem occurs while reading from the file.

LDIFException - If the information read cannot be parsed as an LDIF entry.

readEntryLines

protected LinkedList<StringBuilder> readEntryLines()
                                            throws IOException,
                                                   LDIFException

Reads a set of lines from the next entry in the LDIF source.

Returns:

A set of lines from the next entry in the LDIF source.

Throws:

IOException - If a problem occurs while reading from the LDIF source.

LDIFException - If the information read is not valid LDIF.

readDN

protected Dn readDN(LinkedList<StringBuilder> lines)
             throws LDIFException

Reads the DN of the entry from the provided list of lines. The DN must be the first line in the list, unless the first line starts with "version", in which case the DN should be the second line.

Parameters:

lines - The set of lines from which the DN should be read.

Returns:

The decoded entry DN.

Throws:

LDIFException - If DN is not the first element in the list (or the second after the LDIF version), or if a problem occurs while trying to parse it.

rejectLastEntry

public void rejectLastEntry(LocalizableMessage message)

Rejects the last entry read from the LDIF. This method is intended for use by components that perform their own validation of entries (e.g., backends during import processing) in which the entry appeared valid to the LDIF reader but some other problem was encountered.

Parameters:

message - A human-readable message providing the reason that the last entry read was not acceptable.

rejectEntry

public void rejectEntry(Entry e,
                        LocalizableMessage message)

Log the specified entry and messages in the reject writer. The method is intended to be used in a threaded environment, where individual import threads need to log an entry and message to the reject file.

Parameters:

e - The entry to log.

message - The message to log.

close

public void close()

Closes this LDIF reader and the underlying file or input stream.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

getEntriesRead

public long getEntriesRead()

Retrieves the total number of entries read so far by this LDIF reader, including those that have been ignored or rejected.

Returns:

The total number of entries read so far by this LDIF reader.

getEntriesIgnored

public long getEntriesIgnored()

Retrieves the total number of entries that have been ignored so far by this LDIF reader because they did not match the import criteria.

Returns:

The total number of entries ignored so far by this LDIF reader.

getEntriesRejected

public long getEntriesRejected()

Retrieves the total number of entries rejected so far by this LDIF reader. This includes both entries that were rejected because of internal validation failure (e.g., they didn't conform to the defined server schema) or an external validation failure (e.g., the component using this LDIF reader didn't accept the entry because it didn't have a parent).

Returns:

The total number of entries rejected so far by this LDIF reader.

logToRejectWriter

protected void logToRejectWriter(List<StringBuilder> lines,
                                 LocalizableMessage message)

Log a message to the reject writer if one is configured.

Parameters:

lines - The set of rejected lines.

message - The associated error message.

logToSkipWriter

protected void logToSkipWriter(List<StringBuilder> lines,
                               LocalizableMessage message)

Log a message to the reject writer if one is configured.

Parameters:

lines - The set of rejected lines.

message - The associated error message.