169 lines
7.3 KiB
XML
169 lines
7.3 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="ldif-parsing">
|
|
<title>LDIF Parsing</title>
|
|
|
|
<section id="ldif-parsing-intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>LDAP Directory Interchange Format (LDIF) files are the standard
|
|
medium for describing directory data in a flat file format. The most common
|
|
uses of this format include information transfer and archival. However,
|
|
the standard also defines a way to describe modifications to stored data
|
|
in a flat file format. LDIFs of this later type are typically referred to
|
|
as <emphasis>changetype</emphasis> or <emphasis>modify</emphasis> LDIFs.
|
|
</para>
|
|
|
|
<para>The <token>org.springframework.ldap.ldif</token> package provides
|
|
classes needed to parse LDIF files and deserialize them into tangible
|
|
objects. The <token>LdifParser</token> is the main class of the
|
|
<token>org.springframework.ldap.ldif</token> package and is capable of
|
|
parsing files that are RFC 2849 compliant. This class reads lines from a
|
|
resource and assembles them into an <token>LdapAttributes</token> object.
|
|
The <token>LdifParser</token> currently ignores
|
|
<emphasis>changetype</emphasis> LDIF entries as their usefulness in the
|
|
context of an application has yet to be determined.</para>
|
|
</section>
|
|
|
|
<section id="ldif-parsing-obj-repr">
|
|
<title>Object Representation</title>
|
|
|
|
<para>Two classes in the <token>org.springframework.ldap.core</token>
|
|
package provide the means to represent an LDIF in code:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><token>LdapAttribute</token> - Extends
|
|
<token>javax.naming.directory.BasicAttribute</token> adding support
|
|
for LDIF options as defined in RFC2849.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><token>LdapAttributes</token> - Extends
|
|
<token>javax.naming.directory.BasicAttributes</token> adding
|
|
specialized support for DNs.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para><token>LdapAttribute</token> objects represent options as a
|
|
<token>Set<String></token>. The DN support added to the
|
|
<token>LdapAttributes</token> object employs the
|
|
<token>org.springframework.ldap.core.DistinguishedName</token> class. </para>
|
|
</section>
|
|
|
|
<section id="ldif-parsing-parser">
|
|
<title>The Parser</title>
|
|
|
|
<para>The <token>Parser</token> interface provides the foundation for
|
|
operation and employs three supporting policy definitions:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><token>SeparatorPolicy</token> - establishes the mechanism by
|
|
which lines are assembled into attributes. </para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><token>AttributeValidationPolicy</token> - ensures that
|
|
attributes are correctly structured prior to parsing.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><token>Specification</token> - provides a mechanism by which
|
|
object structure can be validated after assembly. </para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<simpara>The default implementations of these interfaces are the
|
|
<token>org.springframework.ldap.ldif.parser.LdifParser</token>, the
|
|
<token>org.springframework.ldap.ldif.support.SeparatorPolicy</token>, and
|
|
the
|
|
<token>org.springframework.ldap.ldif.support.DefaultAttributeValidationPolicy</token>,
|
|
and the
|
|
<token>org.springframework.ldap.schema.DefaultSchemaSpecification</token>
|
|
respectively. Together, these 4 classes parse a resource line by line and
|
|
translate the data into <token>LdapAttributes</token> objects. </simpara>
|
|
|
|
<simpara>The <token>SeparatorPolicy</token> determines how individual
|
|
lines read from the source file should be interpreted as the LDIF
|
|
specification allows attributes to span multiple lines. The default policy
|
|
assess lines in the context of the order in which they were read to
|
|
determine the nature of the line in consideration.
|
|
<emphasis>control</emphasis> attributes and
|
|
<emphasis>changetype</emphasis> records are ignored.</simpara>
|
|
|
|
<simpara>The <token>DefaultAttributeValidationPolicy</token> uses REGEX
|
|
expressions to ensure each attribute conforms to a valid attribute format
|
|
according to RFC 2849 once parsed. If an attribute fails validation, an
|
|
<token>InvalidAttributeFormatException</token> is logged and the record is
|
|
skipped (the parser returns null).</simpara>
|
|
</section>
|
|
|
|
<section id="ldif-parsing-schema">
|
|
<title>Schema Validation</title>
|
|
|
|
<para>A mechanism for validating parsed objects against a schema and is
|
|
available via the <token>Specification</token> interface in the
|
|
<token>org.springframework.ldap.schema</token> package. The
|
|
<token>DefaultSchemaSpecification</token> does not do any validation and
|
|
is available for instances where records are known to be valid and not
|
|
required to be checked. This option saves the performance penalty that
|
|
validation imposes. The <token>BasicSchemaSpecification</token> applies
|
|
basic checks such as ensuring DN and object class declarations have been
|
|
provided. Currently, validation against an actual schema requires
|
|
implementation of the <token>Specification</token> interface. </para>
|
|
</section>
|
|
|
|
<section id="ldif-parsing-batch">
|
|
<title>Spring Batch Integration</title>
|
|
|
|
<para>While the <token>LdifParser</token> can be employed by any
|
|
application that requires parsing of LDIF files, Spring offers a batch
|
|
processing framework that offers many file processing utilities for
|
|
parsing delimited files such as CSV. The
|
|
<token>org.springframework.ldap.ldif.batch</token> package offers the
|
|
classes necessary for using the <token>LdifParser</token> as a valid
|
|
configuration option in the Spring Batch framework.</para>
|
|
|
|
<para>There are 5 classes in this package which offer three basic use
|
|
cases:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Use Case 1: Read LDIF records from a file and return an
|
|
<token>LdapAttributes</token> object.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Use Case 2: Read LDIF records from a file and map records to
|
|
Java objects (POJOs).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Use Case 3: Write LDIF records to a file.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The first use case is accomplished with the LdifReader. This class
|
|
extends Spring Batch's
|
|
<token>AbstractItemCountingItemSteamItemReader</token> and implements its
|
|
<token>ResourceAwareItemReaderItemStream</token>. It fits naturally into
|
|
the framework and can be used to read <token>LdapAttributes</token>
|
|
objects from a file.</para>
|
|
|
|
<para>The <token>MappingLdifReader</token> can be used to map LDIF objects
|
|
directly to any POJO. This class requires an implementation of the
|
|
<token>RecordMapper</token> interface be provided. This implementation
|
|
should implement the logic for mapping objects to POJOs.</para>
|
|
|
|
<para>The <token>RecordCallbackHandler</token> can be implemented and
|
|
provided to either reader. This handler can be used to operate on skipped
|
|
records. Consult the Spring Batch documentation for more
|
|
information.</para>
|
|
|
|
<para>The last member of this package, the <token>LdifAggregator</token>,
|
|
can be used to write LDIF records to a file. This class simply invokes the
|
|
<token>toString()</token> method of the <token>LdapAttributes</token>
|
|
object.</para>
|
|
</section>
|
|
</chapter>
|