CR-7576 OPENDJ-1767 Show an example schema check

Mark Craig

27.52.2015 9ed3693ba51e9b912347ee5422ee9fb96b03a249

CR-7576 OPENDJ-1767 Show an example schema check

This patch documents an example app that checks an entry
against the directory server schema before attempting an LDAP add.

 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>

 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">