From 520cf1450d640ad8b1282c725ea3a7fa849da3a8 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 27 Apr 2012 13:50:10 +0000
Subject: [PATCH] Add content to chapter on LDIF, with excerpts from the existing Modify.java sample code
---
opendj3/src/main/docbkx/dev-guide/chap-ldif.xml | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 files changed, 158 insertions(+), 13 deletions(-)
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml b/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml
index b4a1118..6460d7c 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml
@@ -20,8 +20,8 @@
!
! CCPL HEADER END
!
- ! Copyright 2011 ForgeRock AS
- !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
-->
<chapter xml:id='chap-ldif'
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
@@ -31,25 +31,170 @@
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Working With LDIF</title>
- <para>OpenDJ SDK provides capabilities for working with LDAP Data Interchange
- Format content. This chapter demonstrates how to use those capabilities.</para>
+ <para>OpenDJ LDAP SDK provides capabilities for working with <link
+ xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc2849">LDAP Data
+ Interchange Format</link> (LDIF) content. This chapter demonstrates how to use
+ those capabilities.</para>
<section xml:id="about-ldif">
<title>About LDIF</title>
- <para>LDAP Data Interchange Format provides a mechanism for representing
+
+ <para>LDAP Data Interchange Format provides a mechanism to represent
directory data in text format. LDIF data is typically used to initialize
directory databases, but also may be used to move data between different
directories that cannot replicate directly, or even as an alternative
- backup format.</para>
+ backup format. When you read OpenDJ's external change log, you get changes
+ expressed in LDIF.</para>
+
+ <para>LDIF uses base64 encoding to store values that are not safe for use in
+ a text file, including values that represent binary objects like JPEG photos
+ and X509 certificates, but also values that hold bits of LDIF, and values that
+ end in white space. The description in the following LDIF holds, "Space at
+ the end of the line " for example. Notice that continuation lines shown in
+ the excerpt of the JPEG photo value start with spaces.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description:: U3BhY2UgYXQgdGhlIGVuZCBvZiB0aGUgbGluZSA=
+uid: bjensen
+jpegPhoto:: /9j/4AAQSkZJRgABAQEASABIAAD/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAABt
+ bnRyUkdCIFhZWiAHzgACAAkABgAxAABhY3NwTVNGVAAAAABJRUMgc1JHQgAAAAAAAAAAAAAAAAAA9tY
+ AAQAAAADTLUhQICAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB
+ ...
+ Pxv8A8lh8J/8AXUfzr1qP/WSfWlzPlsZSi3VHqMA/WinUVB0n/9k=
+facsimileTelephoneNumber: +1 408 555 1992
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+givenName: Barbara
+cn: Barbara Jensen
+cn: Babs Jensen
+telephoneNumber: +1 408 555 1862
+sn: Jensen
+roomNumber: 0209
+homeDirectory: /home/bjensen
+ou: Product Development
+ou: People
+l: Cupertino
+mail: bjensen@example.com
+uidNumber: 1076
+gidNumber: 1000
+</programlisting>
+
+ <para>LDIF can serve to describe not only entries with their attributes but
+ also changes to entries. For example, you can express adding a JPEG photo
+ to Babs Jensen's entry as follows.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=people,dc=example,dc=com
+changetype: modify
+add: jpegPhoto
+jpegPhoto:< file:///tmp/opendj-logo.jpg
+</programlisting>
+
+ <para>You can also replace and delete attribute values. Notice the dash,
+ <literal>-</literal>, used to separate changes.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=people,dc=example,dc=com
+changetype: modify
+replace: roomNumber
+roomNumber: 1234
+-
+delete: description
+-
+delete: jpegPhoto
+</programlisting>
+
+ <para>LDIF also allows <literal>changetype</literal>s of
+ <literal>add</literal> to create entries, <literal>delete</literal> to
+ remove entries, and <literal>modrdn</literal> to rename entries.</para>
+
+ <para>For more examples, see the LDIF specification, <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc2849">RFC 2849</link>.</para>
</section>
-
- <section xml:id="writing-ldif">
- <title>Writing LDIF</title>
- <para>TODO</para>
- </section>
-
+
<section xml:id="reading-ldif">
<title>Reading LDIF</title>
- <para>TODO</para>
+
+ <para>OpenDJ LDAP SDK provides <literal>ChangeRecordReader</literal>s to
+ read requests to modify directory data, and <literal>EntryReader</literal>s
+ to read entries from a data source such as a file or other source. Both of
+ these are interfaces.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>ConnectionEntryReader</literal> class offers methods
+ to iterate through entries and references returned by a search.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <literal>LDIFChangeRecordReader</literal> and
+ <literal>LDIFEntryReader</literal> classes offer methods to handle LDIF as
+ strings or from an input stream.</para>
+
+ <para>Both classes give you some methods to filter content. You can also
+ use the <literal>LDIF</literal> static methods to filter content.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following short excerpt shows a reader that takes LDIF change
+ records from standard input.</para>
+
+ <programlisting language="java">InputStream ldif = System.in;
+final LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);</programlisting>
+ </section>
+
+ <section xml:id="writing-ldif">
+ <title>Writing LDIF</title>
+
+ <para><literal>ChangeRecordWriter</literal>s let you write requests to modify
+ directory data, whereas <literal>EntryWriter</literal>s let you write entries
+ to a file or an output stream. Both of these are interfaces.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>ConnectionChangeRecordWriter</literal> and
+ <literal>ConnectionEntryWriter</literal> classes let you write directly
+ to a connection to the directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <literal>LDIFChangeRecordWriter</literal> and
+ <literal>LDIFEntryWriter</literal> classes let you write to a file or other
+ output stream. Both classes offer methods to filter content.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following excerpt shows a writer pushing LDIF changes to a
+ directory server.</para>
+
+ <programlisting language="java"
+ >final LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+
+try {
+ connection = factory.getConnection();
+ connection.bind(userDN, password.toCharArray());
+
+ final ConnectionChangeRecordWriter writer =
+ new ConnectionChangeRecordWriter(connection);
+ while (reader.hasNext()) {
+ ChangeRecord changeRecord = reader.readChangeRecord();
+ writer.writeChangeRecord(changeRecord);
+ }
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} catch (final IOException e) {
+ System.err.println(e.getMessage());
+ System.exit(ResultCode.CLIENT_SIDE_LOCAL_ERROR.intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
</section>
</chapter>
--
Gitblit v1.10.0