From 9ed3693ba51e9b912347ee5422ee9fb96b03a249 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Mon, 27 Jul 2015 07:52:55 +0000
Subject: [PATCH] CR-7576 OPENDJ-1767 Show an example schema check

---
 docs/src/main/docbkx/dev-guide/chap-writing.xml        |   53 ++++++++++++++++++++++++++
 docs/src/main/docbkx/dev-guide/chap-best-practices.xml |   19 ++++++---
 2 files changed, 66 insertions(+), 6 deletions(-)

diff --git a/docs/src/main/docbkx/dev-guide/chap-best-practices.xml b/docs/src/main/docbkx/dev-guide/chap-best-practices.xml
index 194e9e7..03487a5 100644
--- a/docs/src/main/docbkx/dev-guide/chap-best-practices.xml
+++ b/docs/src/main/docbkx/dev-guide/chap-best-practices.xml
@@ -348,19 +348,26 @@
   <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="dev-guide#get-schema-information" xlink:show="new"
-   xlink:role="http://docbook.org/xlink/role/olink"><citetitle
-   >Getting Schema Information</citetitle></link>.
+   <literal>Schema.readSchema()</literal>.
   </para>
 
   <para>
    Once you have the directory server schema definitions,
    you can validate entries with <literal>Schema.validateEntry()</literal>.
+   For sample code see the section on
+   <link
+    xlink:href="dev-guide#adding-entries"
+    xlink:role="http://docbook.org/xlink/role/olink"
+    xlink:show="new"
+   ><citetitle>Adding Directory Entries</citetitle></link>.
+  </para>
+
+  <para>
    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>
+   or <literal>DecodeOptions.setSchemaResolver()</literal>.
+   If you use only the default schema from the LDAP SDK,
+   you can specify the <literal>DecodeOptions</literal>
    as part of <literal>LDAPOptions</literal> when creating
    an <literal>LDAPConnectionFactory</literal>.
   </para>
diff --git a/docs/src/main/docbkx/dev-guide/chap-writing.xml b/docs/src/main/docbkx/dev-guide/chap-writing.xml
index 5ee8c5f..6b44682 100644
--- a/docs/src/main/docbkx/dev-guide/chap-writing.xml
+++ b/docs/src/main/docbkx/dev-guide/chap-writing.xml
@@ -138,6 +138,59 @@
 
   <programlisting language="java"
   >[jcp:org.forgerock.opendj.examples.ShortLife:--- JCite add ---]</programlisting>
+
+  <para>
+   Directory servers generally reject entries that violate the server's LDAP schema.
+   To make sure an entry conforms to the directory server LDAP schema
+   before attempting to add it to the directory,
+   use the schema's <literal>validateEntry()</literal> method
+   to check the entry for errors.
+   The following example reads an entry to add from <literal>System.in</literal>.
+   If the entry is valid according to the directory schema,
+   it tries to add the entry to the directory.
+  </para>
+
+  <programlisting language="java">
+[jcp:org.forgerock.opendj.examples.UseSchema:--- JCite ---]
+  </programlisting>
+
+  <para>
+   The following example shows a successful add operation
+   for an entry that conforms to the directory server LDAP schema.
+  </para>
+
+  <screen>
+<userinput>dn: cn=New User,ou=People,dc=example,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+ou: People
+cn: New User
+sn: User
+</userinput>
+<computeroutput>Processing ADD request for cn=New User,ou=People,dc=example,dc=com
+ADD operation successful for DN cn=New User,ou=People,dc=example,dc=com</computeroutput>
+  </screen>
+
+  <para>
+   The following example shows an error message
+   for an entry that violates the directory server LDAP schema.
+  </para>
+
+  <screen>
+<userinput>dn: cn=Broken,ou=People,dc=example,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+ou: People
+cn: Broken
+sn: User
+unknown: attribute
+</userinput>
+<computeroutput>Entry "cn=Broken,ou=People,dc=example,dc=com" violates the schema
+ because it contains attribute "unknown"
+ which is not allowed by any of the object classes in the entry</computeroutput>
+  </screen>
  </section>
 
  <section xml:id="modifying-attr-values">

--
Gitblit v1.10.0