The LDIF format is used to convey directory information, or a description of a set of changes made to directory entries. An LDIF file consists of a series of records separated by line separators. A record consists of a sequence of lines describing a directory entry, or a sequence of lines describing a set of changes to a directory entry. An LDIF file specifies a set of directory entries, or a set of changes to be applied to directory entries, but not both.
There is a one-to-one correlation between LDAP operations that modify the directory (add, delete, modify, moddn and modrdn), and the types of changerecords described in the LDIF format ("add", "delete", "modify", "modrdn" or "moddn"). This correspondence is intentional, and permits a straightforward translation from LDIF changerecords to protocol operations.
The LDIF Parser reads and writes LDIF style data. The LDIF Parser is usually used to do file exchange with an LDAP directory.
The LDIF Parser correctly parses and writes MIME BASE64 encoded strings: it tries to perform BASE64 encoding if necessary. One such situation is where there are trailing spaces after attribute values: to make sure another LDIF Parser gets the space, it encodes the attribute as BASE64.
A conforming LDIF file must always have Character Encoding set to UTF-8. The Character Encoding parameter is also applied when encoding or decoding BASE64 encoded strings.
BASE64 encoding looks like garbled text if you do not know how to decode it.
This Parser handles/provides tags compatible with Delta Tagging at the Entry level, the Attribute level and the Attribute Value level. Delta tagging at the Attribute level is handled as in the DSMLv2 Parser, see Multiple Attribute modifications.
The LDIF Parser detects in its writeEntry method if the "newrdn" attribute exists and if yes, it sets the changetype to "modrdn" instead of "modify". Also see Detect and handle modrdn operation for information how certain Connectors handle "modrdn" operations.
While reading, the lines of the input are read one by one and the following checks are made for each:
The Entry is Delta tagged correspondingly if a key "changetype" is found and its value equals to "modify", "moddn" or "modrdn".
While writing first it is checked whether the Version Number parameter is selected, and if yes the text "version: 1" is written on the first line. This means that the output is according to the RFC 2489 LDIF specification. After that the "dn" key is added with the value in the "dnAttributeName" attribute (if such exists).
If the entry is Delta tagged then the corresponding changetype key is added with the value "add", "modify", "modrdn" or "delete", depending on the Entry's operation and attributes. If the parameter Only Descriptive Records is set, however, a changerecord is not written, even if the Entry is Delta tagged.
The Parser has the following parameters:
LDIF parser can suppress the LDIF version number by using the Version Number parameter.
An LDIF file may contain "change records" or "descriptive records". A change record describes some change that is needed for an entry. A descriptive record just describes an entry.
An easy way to see if a record is a change record, is that it will contain a "changetype" line as the second line, immediately after the "dn" line.
A correct LDIF File will either contain only change records, or only descriptive records.
The LDIF Parser uses the operation code of the work entry to decide if it should write a change record or just a descriptive record. That is, if the work Entry has any operation that is not generic, it assumes that it should write a change record. This is quite convenient, but it may not be what is wanted in all cases.
Even if the work Entry comes from a connector with Delta Enabled, it may be that the LDIF File should contain only descriptive records, for example because that is what can be read by the system that will use the LDIF File.
If this flag is set, only descriptive records will be generated, no matter what the operation of the Entry might be. If the operation is Delete, nothing will be written about that Entry, but otherwise the attribute values the Entry contains will be written as a descriptive record.