LDIFWriter (UnboundID LDAP SDK for Java 6.0.9)

java.lang.Object
- com.unboundid.ldif.LDIFWriter

All Implemented Interfaces:: java.io.Closeable, java.lang.AutoCloseable

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

This class provides an LDIF writer, which can be used to write entries and change records in the LDAP Data Interchange Format as per RFC 2849.

Example

The following example performs a search to find all users in the "Sales" department and then writes their entries to an LDIF file:

 // Perform a search to find all users who are members of the sales
 // department.
 SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
      SearchScope.SUB, Filter.createEqualityFilter("ou", "Sales"));
 SearchResult searchResult;
 try
 {
   searchResult = connection.search(searchRequest);
 }
 catch (LDAPSearchException lse)
 {
   searchResult = lse.getSearchResult();
 }
 LDAPTestUtils.assertResultCodeEquals(searchResult, ResultCode.SUCCESS);

 // Write all of the matching entries to LDIF.
 int entriesWritten = 0;
 LDIFWriter ldifWriter = new LDIFWriter(pathToLDIF);
 for (SearchResultEntry entry : searchResult.getSearchEntries())
 {
   ldifWriter.writeEntry(entry);
   entriesWritten++;
 }

 ldifWriter.close();

Constructor Summary

Constructors
Constructor and Description
`LDIFWriter(java.io.File file)` Creates a new LDIF writer that will write entries to the provided file.
`LDIFWriter(java.io.OutputStream outputStream)` Creates a new LDIF writer that will write entries to the provided output stream.
`LDIFWriter(java.io.OutputStream outputStream, int parallelThreads)` Creates a new LDIF writer that will write entries to the provided output stream optionally using parallelThreads when writing batches of LDIF records.
`LDIFWriter(java.io.OutputStream outputStream, int parallelThreads, LDIFWriterEntryTranslator entryTranslator)` Creates a new LDIF writer that will write entries to the provided output stream optionally using parallelThreads when writing batches of LDIF records.
`LDIFWriter(java.io.OutputStream outputStream, int parallelThreads, LDIFWriterEntryTranslator entryTranslator, LDIFWriterChangeRecordTranslator changeRecordTranslator)` Creates a new LDIF writer that will write entries to the provided output stream optionally using parallelThreads when writing batches of LDIF records.
`LDIFWriter(java.lang.String path)` Creates a new LDIF writer that will write entries to the provided file.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`close()` Closes this LDIF writer and the underlying LDIF target.
`static boolean`	`commentAboutBase64EncodedValues()` Indicates whether the LDIF writer should generate comments that attempt to provide unencoded representations (with special characters escaped) of any base64-encoded values in entries and change records that are written by this writer.
`static java.lang.String`	`encodeNameAndValue(java.lang.String name, ASN1OctetString value)` Creates a string consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
`static void`	`encodeNameAndValue(java.lang.String name, ASN1OctetString value, ByteStringBuffer buffer, int wrapColumn)` Appends a string to the provided buffer consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
`static void`	`encodeNameAndValue(java.lang.String name, ASN1OctetString value, java.lang.StringBuilder buffer)` Appends a string to the provided buffer consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
`static void`	`encodeNameAndValue(java.lang.String name, ASN1OctetString value, java.lang.StringBuilder buffer, int wrapColumn)` Appends a string to the provided buffer consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
`void`	`flush()` Flushes the output stream used by this LDIF writer to ensure any buffered data is written out.
`static Base64EncodingStrategy`	`getBase64EncodingStrategy()` Retrieves the strategy that the LDIF writer should use for determining whether values need to be base64-encoded.
`int`	`getWrapColumn()` Retrieves the column at which to wrap long lines.
`static void`	`setBase64EncodingStrategy(Base64EncodingStrategy base64EncodingStrategy)` Specifies the strategy that the LDIF writer should use for determining whether values need to be base64-encoded.
`static void`	`setCommentAboutBase64EncodedValues(boolean commentAboutBase64EncodedValues)` Specifies whether the LDIF writer should generate comments that attempt to provide unencoded representations (with special characters escaped) of any base64-encoded values in entries and change records that are written by this writer.
`void`	`setWrapColumn(int wrapColumn)` Specifies the column at which to wrap long lines.
`static java.util.List<java.lang.String>`	`wrapLines(int wrapColumn, java.util.List<java.lang.String> ldifLines)` Performs any appropriate wrapping for the provided set of LDIF lines.
`static java.util.List<java.lang.String>`	`wrapLines(int wrapColumn, java.lang.String... ldifLines)` Performs any appropriate wrapping for the provided set of LDIF lines.
`void`	`writeChangeRecord(LDIFChangeRecord changeRecord)` Writes the provided change record in LDIF form.
`void`	`writeChangeRecord(LDIFChangeRecord changeRecord, java.lang.String comment)` Writes the provided change record in LDIF form, preceded by the provided comment.
`void`	`writeComment(java.lang.String comment, boolean spaceBefore, boolean spaceAfter)` Writes the provided comment to the LDIF target, wrapping long lines as necessary.
`void`	`writeEntry(Entry entry)` Writes the provided entry in LDIF form.
`void`	`writeEntry(Entry entry, java.lang.String comment)` Writes the provided entry in LDIF form, preceded by the provided comment.
`void`	`writeLDIFRecord(LDIFRecord record)` Writes the provided record in LDIF form.
`void`	`writeLDIFRecord(LDIFRecord record, java.lang.String comment)` Writes the provided record in LDIF form, preceded by the provided comment.
`void`	`writeLDIFRecords(java.util.List<? extends LDIFRecord> ldifRecords)` Writes the provided list of LDIF records (most likely Entries) to the output.
`void`	`writeVersionHeader()` Writes the LDIF version header (i.e.,"version: 1").

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LDIFWriter
```
public LDIFWriter(@NotNull
          java.lang.String path)
           throws java.io.IOException
```
    Creates a new LDIF writer that will write entries to the provided file.
    
    Parameters:
    path - The path to the LDIF file to be written. It must not be null.
    
    Throws:
    
    java.io.IOException - If a problem occurs while opening the provided file for writing.
  - LDIFWriter
```
public LDIFWriter(@NotNull
          java.io.File file)
           throws java.io.IOException
```
    Creates a new LDIF writer that will write entries to the provided file.
    
    Parameters:
    file - The LDIF file to be written. It must not be null.
    
    Throws:
    
    java.io.IOException - If a problem occurs while opening the provided file for writing.
  - LDIFWriter
```
public LDIFWriter(@NotNull
          java.io.OutputStream outputStream)
```
    Creates a new LDIF writer that will write entries to the provided output stream.
    
    Parameters:
    outputStream - The output stream to which the data is to be written. It must not be null.
  - LDIFWriter
```
public LDIFWriter(@NotNull
          java.io.OutputStream outputStream,
          int parallelThreads)
```
    Creates a new LDIF writer that will write entries to the provided output stream optionally using parallelThreads when writing batches of LDIF records.
    
    Parameters:
    outputStream - The output stream to which the data is to be written. It must not be null.
    parallelThreads - If this value is greater than zero, then the specified number of threads will be used to encode entries before writing them to the output for the writeLDIFRecords(List) method. Note this is the only output method that will use multiple threads. This should only be set to greater than zero when performance analysis has demonstrated that writing the LDIF is a bottleneck. The default synchronous processing is normally fast enough. There is no benefit in passing in a value greater than the number of processors in the system. A value of zero implies the default behavior of reading and parsing LDIF records synchronously when one of the read methods is called.
  - LDIFWriter
```
public LDIFWriter(@NotNull
          java.io.OutputStream outputStream,
          int parallelThreads,
          @Nullable
          LDIFWriterEntryTranslator entryTranslator)
```
    Creates a new LDIF writer that will write entries to the provided output stream optionally using parallelThreads when writing batches of LDIF records.
    
    Parameters:
    outputStream - The output stream to which the data is to be written. It must not be null.
    parallelThreads - If this value is greater than zero, then the specified number of threads will be used to encode entries before writing them to the output for the writeLDIFRecords(List) method. Note this is the only output method that will use multiple threads. This should only be set to greater than zero when performance analysis has demonstrated that writing the LDIF is a bottleneck. The default synchronous processing is normally fast enough. There is no benefit in passing in a value greater than the number of processors in the system. A value of zero implies the default behavior of reading and parsing LDIF records synchronously when one of the read methods is called.
    entryTranslator - An optional translator that will be used to alter entries before they are actually written. This may be null if no translator is needed.
  - LDIFWriter
```
public LDIFWriter(@NotNull
          java.io.OutputStream outputStream,
          int parallelThreads,
          @Nullable
          LDIFWriterEntryTranslator entryTranslator,
          @Nullable
          LDIFWriterChangeRecordTranslator changeRecordTranslator)
```
    Creates a new LDIF writer that will write entries to the provided output stream optionally using parallelThreads when writing batches of LDIF records.
    
    Parameters:
    outputStream - The output stream to which the data is to be written. It must not be null.
    parallelThreads - If this value is greater than zero, then the specified number of threads will be used to encode entries before writing them to the output for the writeLDIFRecords(List) method. Note this is the only output method that will use multiple threads. This should only be set to greater than zero when performance analysis has demonstrated that writing the LDIF is a bottleneck. The default synchronous processing is normally fast enough. There is no benefit in passing in a value greater than the number of processors in the system. A value of zero implies the default behavior of reading and parsing LDIF records synchronously when one of the read methods is called.
    entryTranslator - An optional translator that will be used to alter entries before they are actually written. This may be null if no translator is needed.
    changeRecordTranslator - An optional translator that will be used to alter change records before they are actually written. This may be null if no translator is needed.
- Method Detail
  - flush
```
public void flush()
           throws java.io.IOException
```
    Flushes the output stream used by this LDIF writer to ensure any buffered data is written out.
    
    Throws:
    
    java.io.IOException - If a problem occurs while attempting to flush the output stream.
  - close
```
public void close()
           throws java.io.IOException
```
    Closes this LDIF writer and the underlying LDIF target.
    
    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 target.
  - getWrapColumn
```
public int getWrapColumn()
```
    Retrieves the column at which to wrap long lines.
    
    Returns:
    The column at which to wrap long lines, or zero to indicate that long lines should not be wrapped.
  - setWrapColumn
```
public void setWrapColumn(int wrapColumn)
```
    Specifies the column at which to wrap long lines. A value of zero indicates that long lines should not be wrapped.
    
    Parameters:
    wrapColumn - The column at which to wrap long lines.
  - commentAboutBase64EncodedValues
```
public static boolean commentAboutBase64EncodedValues()
```
    Indicates whether the LDIF writer should generate comments that attempt to provide unencoded representations (with special characters escaped) of any base64-encoded values in entries and change records that are written by this writer.
    
    Returns:
    true if the LDIF writer should generate comments that attempt to provide unencoded representations of any base64-encoded values, or false if not.
  - setCommentAboutBase64EncodedValues
```
public static void setCommentAboutBase64EncodedValues(boolean commentAboutBase64EncodedValues)
```
    Specifies whether the LDIF writer should generate comments that attempt to provide unencoded representations (with special characters escaped) of any base64-encoded values in entries and change records that are written by this writer.
    
    Parameters:
    commentAboutBase64EncodedValues - Indicates whether the LDIF writer should generate comments that attempt to provide unencoded representations (with special characters escaped) of any base64-encoded values in entries and change records that are written by this writer.
  - getBase64EncodingStrategy
```
@NotNull
public static Base64EncodingStrategy getBase64EncodingStrategy()
```
    Retrieves the strategy that the LDIF writer should use for determining whether values need to be base64-encoded.
    
    Returns:
    The strategy that the LDIF writer should use for determining whether values need to be base64-encoded.
  - setBase64EncodingStrategy
```
public static void setBase64EncodingStrategy(@NotNull
                             Base64EncodingStrategy base64EncodingStrategy)
```
    Specifies the strategy that the LDIF writer should use for determining whether values need to be base64-encoded.
    
    Parameters:
    base64EncodingStrategy - The strategy that the LDIF writer should use for determining whether values need to be base64-encoded.
  - writeVersionHeader
```
public void writeVersionHeader()
                        throws java.io.IOException
```
    Writes the LDIF version header (i.e.,"version: 1"). If a version header is to be added to the LDIF content, it should be done before any entries or change records have been written.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the version header.
  - writeEntry
```
public void writeEntry(@NotNull
              Entry entry)
                throws java.io.IOException
```
    Writes the provided entry in LDIF form.
    
    Parameters:
    entry - The entry to be written. It must not be null.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - writeEntry
```
public void writeEntry(@NotNull
              Entry entry,
              @Nullable
              java.lang.String comment)
                throws java.io.IOException
```
    Writes the provided entry in LDIF form, preceded by the provided comment.
    
    Parameters:
    entry - The entry to be written in LDIF form. It must not be null.
    comment - The comment to be written before the entry. It may be null if no comment is to be written.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - writeChangeRecord
```
public void writeChangeRecord(@NotNull
                     LDIFChangeRecord changeRecord)
                       throws java.io.IOException
```
    Writes the provided change record in LDIF form.
    
    Parameters:
    changeRecord - The change record to be written. It must not be null.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - writeChangeRecord
```
public void writeChangeRecord(@NotNull
                     LDIFChangeRecord changeRecord,
                     @Nullable
                     java.lang.String comment)
                       throws java.io.IOException
```
    Writes the provided change record in LDIF form, preceded by the provided comment.
    
    Parameters:
    changeRecord - The change record to be written. It must not be null.
    comment - The comment to be written before the entry. It may be null if no comment is to be written.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - writeLDIFRecord
```
public void writeLDIFRecord(@NotNull
                   LDIFRecord record)
                     throws java.io.IOException
```
    Writes the provided record in LDIF form.
    
    Parameters:
    record - The LDIF record to be written. It must not be null.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - writeLDIFRecord
```
public void writeLDIFRecord(@NotNull
                   LDIFRecord record,
                   @Nullable
                   java.lang.String comment)
                     throws java.io.IOException
```
    Writes the provided record in LDIF form, preceded by the provided comment.
    
    Parameters:
    record - The LDIF record to be written. It must not be null.
    comment - The comment to be written before the LDIF record. It may be null if no comment is to be written.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - writeLDIFRecords
```
public void writeLDIFRecords(@NotNull
                    java.util.List<? extends LDIFRecord> ldifRecords)
                      throws java.io.IOException,
                             java.lang.InterruptedException
```
    Writes the provided list of LDIF records (most likely Entries) to the output. If this LDIFWriter was constructed without any parallel output threads, then this behaves identically to calling writeLDIFRecord() sequentially for each item in the list. If this LDIFWriter was constructed to write records in parallel, then the configured number of threads are used to convert the records to raw bytes, which are sequentially written to the input file. This can speed up the total time to write a large set of records. Either way, the output records are guaranteed to be written in the order they appear in the list.
    
    Parameters:
    ldifRecords - The LDIF records (most likely entries) to write to the output.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
    
    java.lang.InterruptedException - If this thread is interrupted while waiting for the records to be written to the output.
  - writeComment
```
public void writeComment(@NotNull
                java.lang.String comment,
                boolean spaceBefore,
                boolean spaceAfter)
                  throws java.io.IOException
```
    Writes the provided comment to the LDIF target, wrapping long lines as necessary.
    
    Parameters:
    comment - The comment to be written to the LDIF target. It must not be null.
    spaceBefore - Indicates whether to insert a blank line before the comment.
    spaceAfter - Indicates whether to insert a blank line after the comment.
    
    Throws:
    
    java.io.IOException - If a problem occurs while writing the LDIF data.
  - wrapLines
```
@NotNull
public static java.util.List<java.lang.String> wrapLines(int wrapColumn,
                                                 @NotNull
                                                 java.lang.String... ldifLines)
```
    Performs any appropriate wrapping for the provided set of LDIF lines.
    
    Parameters:
    wrapColumn - The column at which to wrap long lines. A value that is less than or equal to two indicates that no wrapping should be performed.
    ldifLines - The set of lines that make up the LDIF data to be wrapped.
    
    Returns:
    A new list of lines that have been wrapped as appropriate.
  - wrapLines
```
@NotNull
public static java.util.List<java.lang.String> wrapLines(int wrapColumn,
                                                 @NotNull
                                                 java.util.List<java.lang.String> ldifLines)
```
    Performs any appropriate wrapping for the provided set of LDIF lines.
    
    Parameters:
    wrapColumn - The column at which to wrap long lines. A value that is less than or equal to two indicates that no wrapping should be performed.
    ldifLines - The set of lines that make up the LDIF data to be wrapped.
    
    Returns:
    A new list of lines that have been wrapped as appropriate.
  - encodeNameAndValue
```
@NotNull
public static java.lang.String encodeNameAndValue(@NotNull
                                          java.lang.String name,
                                          @NotNull
                                          ASN1OctetString value)
```
    Creates a string consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
    
    Parameters:
    name - The name for the attribute.
    value - The value for the attribute.
    
    Returns:
    A string consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
  - encodeNameAndValue
```
public static void encodeNameAndValue(@NotNull
                      java.lang.String name,
                      @NotNull
                      ASN1OctetString value,
                      @NotNull
                      java.lang.StringBuilder buffer)
```
    Appends a string to the provided buffer consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
    
    Parameters:
    name - The name for the attribute.
    value - The value for the attribute.
    buffer - The buffer to which the name and value are to be written.
  - encodeNameAndValue
```
public static void encodeNameAndValue(@NotNull
                      java.lang.String name,
                      @NotNull
                      ASN1OctetString value,
                      @NotNull
                      java.lang.StringBuilder buffer,
                      int wrapColumn)
```
    Appends a string to the provided buffer consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value.
    
    Parameters:
    name - The name for the attribute.
    value - The value for the attribute.
    buffer - The buffer to which the name and value are to be written.
    wrapColumn - The column at which to wrap long lines. A value that is less than or equal to two indicates that no wrapping should be performed.
  - encodeNameAndValue
```
public static void encodeNameAndValue(@NotNull
                      java.lang.String name,
                      @NotNull
                      ASN1OctetString value,
                      @NotNull
                      ByteStringBuffer buffer,
                      int wrapColumn)
```
    Appends a string to the provided buffer consisting of the provided attribute name followed by either a single colon and the string representation of the provided value, or two colons and the base64-encoded representation of the provided value. It may optionally be wrapped at the specified column.
    
    Parameters:
    name - The name for the attribute.
    value - The value for the attribute.
    buffer - The buffer to which the name and value are to be written.
    wrapColumn - The column at which to wrap long lines. A value that is less than or equal to two indicates that no wrapping should be performed.

Class LDIFWriter

Example

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LDIFWriter

LDIFWriter

LDIFWriter

LDIFWriter

LDIFWriter

LDIFWriter

Method Detail

flush

close

getWrapColumn

setWrapColumn

commentAboutBase64EncodedValues

setCommentAboutBase64EncodedValues

getBase64EncodingStrategy

setBase64EncodingStrategy

writeVersionHeader

writeEntry

writeEntry

writeChangeRecord

writeChangeRecord

writeLDIFRecord

writeLDIFRecord

writeLDIFRecords

writeComment

wrapLines

wrapLines

encodeNameAndValue

encodeNameAndValue

encodeNameAndValue

encodeNameAndValue