1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<?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>
|
