CR-2714 Fix for OPENDJ-1193: Add "best practice" to docs regarding obtainin...

Mark Craig

17.24.2013 ab5337e1351979cb8617bdbe1b76c9a696cc8eaa

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

@@ -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() {

 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>

 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>