Spring/spring-ldap
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added Keith's documentation for the LDIF parser. Updated package dependencies doc.

Browse Source
This commit is contained in:
Ulrik Sandberg
2010-10-10 21:41:37 +00:00
parent 06ce5a9bf6
commit 26a523a58b
5 changed files with 236 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
src/docbkx/index.xml
View File

@@ -19,6 +19,10 @@
<firstname>Eric</firstname>
<surname>Dalquist</surname>
</author>
<author>
<firstname>Keith</firstname>
<surname>Barlow</surname>
</author>
</authorgroup>
<legalnotice>
@@ -44,4 +48,5 @@
<xi:include href="configuration.xml" />
<xi:include href="pooling.xml" />
<xi:include href="user-authentication.xml" />
<xi:include href="ldif-parsing.xml" />
</book>

166
src/docbkx/ldif-parsing.xml Normal file
View File

@@ -0,0 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="ldif-parsing">
<title>LDIF Parsing</title>
<section id="ldif-parsing-intro">
<title>Introduction</title>
<para>LDIF files are the standard medium for serializing directoy data to
a flat file for archival, transferrence, or altercation. The
<token>org.springframework.ldap.ldif</token> package provides classes
needed to read ldap objects from flat files and deserialize them into
tangible objects.</para>
<para>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&lt;String&gt;</token>. The DN support added to the
<token>LdapAttributes</token> object employs the
<token>org.springframework.ldap.core.DistuishedName</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>

70
src/docbkx/overview.xml
View File

@@ -209,6 +209,9 @@ public class PersonDaoImpl implements PersonDao {
<listitem>
<para><emphasis>commons-pool</emphasis> (If you are planning to use the pooling functionality)</para>
</listitem>
<listitem>
<para><emphasis>spring-batch</emphasis> (If you are planning to use the LDIF parsing functionality together with Spring Batch)</para>
</listitem>
</itemizedlist>
</sect1>
@@ -335,8 +338,8 @@ public class PersonDaoImpl implements PersonDao {
<itemizedlist spacing="compact">
<listitem>
<para>Dependencies: ldap, ldap.core, ldap.pool, spring-beans, spring-tx
commons-lang, commons-logging, commons-pool</para>
<para>Dependencies: ldap, ldap.core, ldap.pool, ldap.pool.validation,
spring-beans, spring-tx, commons-lang, commons-logging, commons-pool</para>
</listitem>
</itemizedlist>
</sect2>
@@ -362,7 +365,7 @@ public class PersonDaoImpl implements PersonDao {
<itemizedlist spacing="compact">
<listitem>
<para>Dependencies: ldap, spring-core, commons-logging</para>
<para>Dependencies: ldap, spring-core, commons-lang, commons-logging</para>
</listitem>
</itemizedlist>
</sect2>
@@ -422,7 +425,7 @@ public class PersonDaoImpl implements PersonDao {
<itemizedlist spacing="compact">
<listitem>
<para>Dependencies: ldap.core, transaction.compensating,
<para>Dependencies: ldap.core, ldap.core.support, transaction.compensating,
spring-core, commons-lang, commons-logging</para>
</listitem>
</itemizedlist>
@@ -437,7 +440,8 @@ public class PersonDaoImpl implements PersonDao {
<itemizedlist spacing="compact">
<listitem>
<para>Dependencies: ldap, ldap.core, ldap.support, ldap.transaction.compensating,
transaction.compensating, spring-tx, spring-jdbc, spring-orm, commons-logging</para>
ldap.transaction.compensating.support, transaction.compensating,
spring-tx, spring-jdbc, spring-orm, commons-logging</para>
</listitem>
</itemizedlist>
</sect2>
@@ -455,10 +459,64 @@ public class PersonDaoImpl implements PersonDao {
</itemizedlist>
</sect2>
<sect2 id="ldap.ldif">
<title>org.springframework.ldap.ldif</title>
<para>The ldap.ldif package provides support for parsing LDIF
files.</para>
<itemizedlist>
<listitem>
<para>Dependencies: ldap.core</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="ldap.ldif.batch">
<title>org.springframework.ldap.ldif.batch</title>
<para>The ldap.ldif.batch package provides the classes necessary to
use the LDIF parser in the Spring Batch framework.</para>
<itemizedlist>
<listitem>
<para>Dependencies: ldap.core, ldap.ldif.parser, spring-batch,
spring-core, spring-beans, commons-logging</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="ldap.ldif.parser">
<title>org.springframework.ldap.ldif.parser</title>
<para>The ldap.ldif.parser package provides the parser classes
and interfaces.</para>
<itemizedlist>
<listitem>
<para>Dependencies: ldap.core, ldap.schema, ldap.ldif, ldap.ldif.support,
spring-core, spring-beans, commons-lang, commons-logging</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="ldap.ldif.support">
<title>org.springframework.ldap.ldif.support</title>
<para>The ldap.ldif.support package provides the necessary auxiliary
classes utilized by the LDIF Parser.</para>
<itemizedlist>
<listitem>
<para>Dependencies: ldap.core, ldap.ldif, commons-lang, commons-logging</para>
</listitem>
</itemizedlist>
</sect2>
<para>For the exact list of jar dependencies, see the Spring LDAP Maven2
Project Object Model (POM) files in the source tree.</para>
</sect1>
<sect1 id="introduction-support">
<title>Support</title>

BIN
src/docbkx/resources/images/package-dependencies.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 25 KiB

2
src/docbkx/resources/xsl/fopdf.xsl
View File

@@ -49,7 +49,7 @@
<fo:table-row>
<fo:table-cell text-align="center">
<fo:block font-family="Helvetica" font-size="12pt" padding="10mm">
<xsl:text>Copyright &#xA9; 2005-2009 </xsl:text>
<xsl:text>Copyright &#xA9; 2005-2010 </xsl:text>
<xsl:for-each select="bookinfo/authorgroup/author">
<xsl:if test="position() > 1">
<xsl:text>, </xsl:text>