From ab5337e1351979cb8617bdbe1b76c9a696cc8eaa Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 17 Dec 2013 09:24:26 +0000
Subject: [PATCH] CR-2714 Fix for OPENDJ-1193: Add "best practice" to docs regarding obtaining the server schema
---
opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ReadSchema.java | 4 +
src/main/docbkx/dev-guide/chap-best-practices.xml | 43 +++++++++++++++++++--
src/main/docbkx/dev-guide/chap-getting-directory-info.xml | 19 +++++++--
3 files changed, 56 insertions(+), 10 deletions(-)
diff --git a/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ReadSchema.java b/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ReadSchema.java
index a14c72b..73d3d58 100644
--- a/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ReadSchema.java
+++ b/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ReadSchema.java
@@ -22,7 +22,7 @@
*
*
* Copyright 2009-2010 Sun Microsystems, Inc.
- * Portions copyright 2011-2012 ForgeRock AS
+ * Portions copyright 2011-2013 ForgeRock AS
*/
package org.forgerock.opendj.examples;
@@ -66,6 +66,7 @@
final String userName = args[2];
final String password = args[3];
+ // --- JCite ---
// Connect and bind to the server.
final LDAPConnectionFactory factory = new LDAPConnectionFactory(hostName, port);
Connection connection = null;
@@ -117,6 +118,7 @@
connection.close();
}
}
+ // --- JCite ---
}
private ReadSchema() {
diff --git a/src/main/docbkx/dev-guide/chap-best-practices.xml b/src/main/docbkx/dev-guide/chap-best-practices.xml
index 2031be8..c4bfe5b 100644
--- a/src/main/docbkx/dev-guide/chap-best-practices.xml
+++ b/src/main/docbkx/dev-guide/chap-best-practices.xml
@@ -20,15 +20,15 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<chapter xml:id='chap-best-practices'
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
- xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
- xmlns:xlink='http://www.w3.org/1999/xlink'
- xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
<title>Best Practices For LDAP Application Developers</title>
<para>Follow the advice in this chapter to write effective, maintainable,
@@ -318,6 +318,41 @@
it easier for the directory administrator to grant your request.</para>
</section>
+ <section xml:id="initialize-with-server-schemas">
+ <title>Read Directory Server Schemas During Initialization</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Schema</secondary>
+ </indexterm>
+
+ <para>
+ By default OpenDJ LDAP SDK uses a very minimal, built-in core schema.
+ The SDK does not read the schema from the directory server by default
+ when setting up a connection, because doing so would have
+ a significant performance cost, and generally needs to be done only once.
+ </para>
+
+ <para>
+ When you start your application, read directory server schemas
+ as a one-off initialization step, using a method such as
+ <literal>Schema.readSchema()</literal>. For sample code see the section,
+ <link xlink:href="get-schema-information" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle
+ >Getting Schema Information</citetitle></link>.
+ </para>
+
+ <para>
+ Once you have the directory server schema definitions,
+ you can validate entries with <literal>Schema.validateEntry()</literal>.
+ You can also set the schema to use for decoding LDAP search results with
+ <literal>DecodeOptions.setSchema()</literal>
+ or <literal>DecodeOptions.setSchemaResolver()</literal>,
+ and specify the <literal>DecodeOptions</literal>
+ as part of <literal>LDAPOptions</literal> when creating
+ an <literal>LDAPConnectionFactory</literal>.
+ </para>
+ </section>
+
<section xml:id="handle-referrals">
<title>Handle Referrals</title>
<indexterm>
diff --git a/src/main/docbkx/dev-guide/chap-getting-directory-info.xml b/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
index 2edda77..3d64a38 100644
--- a/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
+++ b/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
@@ -26,9 +26,9 @@
<chapter xml:id='chap-getting-directory-info'
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
- xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
- xmlns:xlink='http://www.w3.org/1999/xlink'
- xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
<title>Getting Information About the Directory Service</title>
<para>LDAP directories expose what their capabilities through the root
@@ -216,10 +216,19 @@
<para>The <literal>org.forgerock.opendj.ldap.schema</literal> package
is devoted to constructing and querying LDAP schemas. The
- <literal>Schema</literal> class for example lets you
- <literal>readSchemaForEntry()</literal> to get the relevant schema from the
+ <literal>Schema</literal> class provides <literal>readSchema()</literal>,
+ and <literal>readSchemaForEntry()</literal> to get the relevant schema from the
subschema subentry, and then <literal>validateEntry()</literal> to check
an entry your application has constructed before sending the entry to the
server.</para>
+
+ <para>
+ The following example reads schemas from the directory server,
+ and then lists the attribute types, object classes, matching rules,
+ and syntaxes obtained.
+ </para>
+
+ <programlisting language="java"
+ >[jcp:org.forgerock.opendj.examples.ReadSchema:--- JCite ---]</programlisting>
</section>
</chapter>
\ No newline at end of file
--
Gitblit v1.10.0