CR-7085 OPENDJ-2003 Fix SDK dev guide links to sample code

Mark Craig

28.03.2015 f9a9420f3e2bbc965b0c0dd43c0619280bf92089

CR-7085 OPENDJ-2003 Fix SDK dev guide links to sample code

This patch uses a doc tools v3 feature to reference a local copy
of the LDAP SDK examples in the LDAP SDK dev guide
rather than the evolving examples on the community site.

 opendj-ldap-sdk-examples/pom.xml

@@ -21,7 +21,7 @@
  !
  ! CDDL HEADER END
  !
  !      Copyright 2011 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
@@ -73,6 +73,33 @@
      </plugin>
    </plugins>
  </build>
  <profiles>
    <profile>
      <id>docs</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <executions>
              <execution>
                <id>examples</id>
                <phase>package</phase>
                <goals>
                  <goal>single</goal>
                </goals>
                <configuration>
                  <descriptors>
                    <descriptor>src/main/assembly/examples.xml</descriptor>
                  </descriptors>
                </configuration>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>
  <reporting>
    <plugins>
      <plugin>

 opendj-ldap-sdk-examples/src/main/assembly/examples.xml

New file
@@ -0,0 +1,49 @@
<?xml version="1.0"?>
<!--
 ! CDDL HEADER START
 !
 ! The contents of this file are subject to the terms of the
 ! Common Development and Distribution License, Version 1.0 only
 ! (the "License").  You may not use this file except in compliance
 ! with the License.
 !
 ! You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 ! or http://forgerock.org/license/CDDLv1.0.html.
 ! See the License for the specific language governing permissions
 ! and limitations under the License.
 !
 ! When distributing Covered Code, include this CDDL HEADER in each
 ! file and include the License file at legal-notices/CDDLv1_0.txt.
 ! If applicable, add the following below this CDDL HEADER, with the
 ! fields enclosed by brackets "[]" replaced with your own identifying
 ! information:
 !      Portions Copyright [yyyy] [name of copyright owner]
 !
 ! CDDL HEADER END
 !
 !      Copyright 2015 ForgeRock AS.
 !
 -->
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2
                              http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  <id>examples</id>

  <includeBaseDirectory>false</includeBaseDirectory>

  <fileSets>
   <fileSet>
    <outputDirectory>resources</outputDirectory>
    <directory>src/main/java</directory>
   </fileSet>
   <fileSet>
    <outputDirectory>resources</outputDirectory>
    <directory>src/main/javadoc</directory>
   </fileSet>
  </fileSets>

  <formats>
    <format>jar</format>
  </formats>
</assembly>

 pom.xml

@@ -168,7 +168,7 @@
        <inherited>false</inherited>
        <executions>
          <execution>
            <id>unpack-sdk-man-pages</id>
            <id>unpack-sdk-doc-prerequisites</id>
            <phase>pre-site</phase>
            <goals>
              <goal>unpack</goal>
@@ -177,6 +177,13 @@
              <artifactItems>
                <artifactItem>
                  <groupId>org.forgerock.opendj</groupId>
                  <artifactId>opendj-ldap-sdk-examples</artifactId>
                  <version>${project.version}</version>
                  <classifier>examples</classifier>
                  <outputDirectory>${project.build.directory}/docbkx-sources</outputDirectory>
                </artifactItem>
                <artifactItem>
                  <groupId>org.forgerock.opendj</groupId>
                  <artifactId>opendj-ldap-toolkit</artifactId>
                  <version>${project.version}</version>
                  <classifier>man-pages</classifier>
@@ -195,7 +202,7 @@
        <configuration>
         <!-- JCite SDK Example code -->
         <jCiteSourcePaths>
           <jCiteSourcePath>${project.basedir}/opendj-ldap-sdk-examples/src/main/java</jCiteSourcePath>
           <jCiteSourcePath>${project.build.directory}/docbkx-sources/resources</jCiteSourcePath>
         </jCiteSourcePaths>
         <copyResourceFiles>true</copyResourceFiles>
        </configuration>

 src/main/docbkx/dev-guide/chap-authenticating.xml

@@ -9,8 +9,7 @@
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
@@ -20,7 +19,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<chapter xml:id='chap-authenticating'
@@ -78,11 +77,13 @@
  no doubt with fewer rights than the normal user, and surely fewer rights
  than an administrator.</para>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SimpleAuth.html"
  xlink:show="new">SimpleAuth.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/SimpleAuth.java"
    xlink:show="new"
   >SimpleAuth.java</link>.
  </para>
 </section>
 
 <section xml:id="simple-auth-with-starttls-or-ssl">
@@ -130,11 +131,13 @@
  <programlisting language="java"
  >[jcp:org.forgerock.opendj.examples.SimpleAuth:--- JCite secure connect ---]</programlisting>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SimpleAuth.html"
  xlink:show="new">SimpleAuth.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/SimpleAuth.java"
    xlink:show="new"
   >SimpleAuth.java</link>.
  </para>
 </section>
 
 <section xml:id="sasl-auth">
@@ -198,10 +201,12 @@
  <literal>uid</literal> values. If you use another directory server, you might
  have to configure how it maps user IDs to user entries.</para>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SASLAuth.html"
  xlink:show="new">SASLAuth.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/SASLAuth.java"
    xlink:show="new"
   >SASLAuth.java</link>.
  </para>
 </section>
</chapter>

 src/main/docbkx/dev-guide/chap-controls.xml

@@ -9,8 +9,7 @@
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
@@ -40,12 +39,12 @@

 <para>This chapter demonstrates how to use LDAP controls.</para>

 <para>For complete examples corresponding to the excerpts shown below, see
 <link
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Controls.html"
 xlink:show="new">Controls.java</link>, one of the <link
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
 xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
 <para>
  For complete examples corresponding to the excerpts shown below, see
  <link
   xlink:href="../resources/org/forgerock/opendj/examples/Controls.java"
   xlink:show="new">Controls.java</link>.
 </para>

 <section xml:id="about-ldap-controls">
  <title>About LDAP Controls</title>

 src/main/docbkx/dev-guide/chap-extended-ops.xml

@@ -9,8 +9,7 @@
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
@@ -20,7 +19,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2015 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<chapter xml:id='chap-extended-ops'
@@ -40,12 +39,13 @@

 <para>This chapter demonstrates how to use LDAP extended operations.</para>

 <para>For complete examples corresponding to the excerpts shown below, see
 <link
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ExtendedOperations.html"
 xlink:show="new">ExtendedOperations.java</link>, one of the <link
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
 xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
 <para>
  For complete examples corresponding to the excerpts shown below, see
  <link
   xlink:href="../resources/org/forgerock/opendj/examples/ExtendedOperations.java"
   xlink:show="new"
  >ExtendedOperations.java</link>.
 </para>

 <section xml:id="about-ldap-extended-operations">
  <title>About LDAP Extended Operations</title>

 src/main/docbkx/dev-guide/chap-get-sdk.xml

@@ -279,9 +279,10 @@
   <secondary>Java</secondary>
  </indexterm>

  <para>A number of OpenDJ LDAP SDK examples are available online on the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ community site</link>. There you find samples
  whose excerpts are shown in this guide.</para>
  <para>
   To read OpenDJ LDAP SDK samples, browse the examples folder of this guide,
   <link xlink:href="../resources/org/forgerock/opendj/examples/" xlink:show="new" />.
   There you find the samples whose excerpts are shown in this guide.
  </para>
 </section>
</chapter>

 src/main/docbkx/dev-guide/chap-getting-directory-info.xml

@@ -9,8 +9,7 @@
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
@@ -20,7 +19,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<chapter xml:id='chap-getting-directory-info'
@@ -71,11 +70,13 @@
  <programlisting language="java"
  >[jcp:org.forgerock.opendj.examples.GetInfo:--- JCite ---]</programlisting>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/GetInfo.html"
  xlink:show="new">GetInfo.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="..resources/org/forgerock/opendj/examples/GetInfo.java"
    xlink:show="new"
    >GetInfo.java</link>.
  </para>

  <para>Notice that by default you can access the root DSE after authenticating
  anonymously. When you look at the entry in LDIF, you see that supported

 src/main/docbkx/dev-guide/chap-reading.xml

@@ -110,11 +110,12 @@
  <programlisting language="java"
  >[jcp:org.forgerock.opendj.examples.SearchBind:--- JCite ---]</programlisting>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SearchBind.html"
  xlink:show="new">SearchBind.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/SearchBind.java"
    xlink:show="new"
   >SearchBind.java</link>.</para>
 </section>

 <section xml:id="basedn-and-scope">
@@ -307,11 +308,13 @@
  <literal>searchSingleEntry()</literal> methods. If you have the distinguished
  name, you can use <literal>readEntry()</literal> directly.</para>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Search.html"
  xlink:show="new">Search.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/Search.java"
    xlink:show="new"
   >Search.java</link>.
  </para>
 </section>

 <section xml:id="get-search-results">
@@ -332,11 +335,13 @@
    <programlisting language="java"
    >[jcp:org.forgerock.opendj.examples.Search:--- JCite ---]</programlisting>

    <para>For a complete example in context, see <link
    xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Search.html"
    xlink:show="new">Search.java</link>, one of the <link
    xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
    xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
    <para>
     For a complete example in context, see
     <link
      xlink:href="../resources/org/forgerock/opendj/examples/Search.java"
      xlink:show="new"
     >Search.java</link>.
    </para>
   </listitem>

   <listitem>
@@ -376,11 +381,13 @@
  <programlisting language="java"
  >[jcp:org.forgerock.opendj.examples.ParseAttributes:--- JCite ---]</programlisting>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ParseAttributes.html"
  xlink:show="new">ParseAttributes.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/ParseAttributes.java"
    xlink:show="new"
   >ParseAttributes.java</link>.
  </para>
 </section>

 <section xml:id="handle-ldap-urls">

 src/main/docbkx/dev-guide/chap-simple-proxy.xml

@@ -34,12 +34,18 @@
  <secondary>Proxy</secondary>
 </indexterm>

 <para>The OpenDJ LDAP SDK <link xlink:show="new"
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Proxy.html"
 >example Proxy</link> demonstrates a simple LDAP proxy that forwards requests
 to one or more remote directory servers. Although the implementation is
 intended as an example, it does demonstrate use of the asynchronous API,
 load balancing, and connection pooling.</para>
 <para>
  The OpenDJ LDAP SDK
  <link
   xlink:href="../resources/org/forgerock/opendj/examples/Proxy.java"
   xlink:show="new"
  >example Proxy</link> demonstrates a simple LDAP proxy
  that forwards requests to one or more remote directory servers.
  Although the implementation is intended as an example,
  it does demonstrate use of the asynchronous API, load balancing,
  and connection pooling.
 </para>

 <indexterm>
  <primary>Connections</primary>
  <secondary>Asynchronous</secondary>
@@ -176,7 +182,7 @@
  <para>
   For details about the <literal>ProxyBackend</literal> implementation, see
   <link
    xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ProxyBackend.html"
    xlink:href="../resources/org/forgerock/opendj/examples/ProxyBackend.java"
    xlink:show="new"
   >ProxyBackend.java</link>.
  </para>
@@ -212,11 +218,15 @@
fullname: Babs Jensen</computeroutput>
  </screen>

  <para>The OpenDJ LDAP SDK <link xlink:show="new"
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/RewriterProxy.html"
  >RewriterProxy</link> example builds on the Proxy example, rewriting requests
  and search result entries. When you read the example, look for the
  <literal>rewrite()</literal> methods.</para>
  <para>
   The OpenDJ LDAP SDK
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/RewriterProxy.java"
    xlink:show="new"
   >RewriterProxy</link> example builds on the Proxy example,
   rewriting requests and search result entries.
   When you read the example, look for the <literal>rewrite()</literal> methods.
  </para>

  <para>In the above output, the rewriter proxy listens on port 8389,
  connecting to a directory server listening on 1389. The directory server

 src/main/docbkx/dev-guide/chap-using-the-sdk.xml

@@ -9,8 +9,7 @@
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
@@ -20,7 +19,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<chapter xml:id='chap-using-the-sdk'
@@ -57,11 +56,13 @@
[jcp:org.forgerock.opendj.examples.Search:--- JCite ---]
  </programlisting>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Search.html"
  xlink:show="new">Search.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/Search.java"
    xlink:show="new"
   >Search.java</link>.
  </para>

  <para>
   For asynchronous operations,
@@ -96,11 +97,13 @@
   when you use asynchronous operations.
  </para>

  <para>For a complete example in context, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SearchAsync.html"
  xlink:show="new">SearchAsync.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   For a complete example in context, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/SearchAsync.java"
    xlink:show="new"
   >SearchAsync.java</link>.
  </para>
 </section>

 <section xml:id="error-handling">

 src/main/docbkx/dev-guide/chap-writing.xml

@@ -33,12 +33,13 @@
 <para>Modern directory servers like OpenDJ can handle a high load of write
 requests, replicating changes quickly both on the LAN and over the WAN.</para>

 <para>For a complete example corresponding to the excerpts shown below, see
 <link
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ShortLife.html"
 xlink:show="new">ShortLife.java</link>, one of the <link
 xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
 xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
 <para>
  For a complete example corresponding to the excerpts shown below, see
  <link
   xlink:href="../resources/org/forgerock/opendj/examples/ShortLife.java"
   xlink:show="new"
  >ShortLife.java</link>.
 </para>

 <section xml:id="about-writes">
  <title>About Add, Modify, Rename, &amp; Delete</title>
@@ -245,12 +246,14 @@
[../resources/big-group.ldif:group-bottom]
  </programlisting>

  <para>To update a static group, you either add members or remove members.
  For sample code, see <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/UpdateGroup.html"
  xlink:show="new">UpdateGroup.java</link>, one of the <link
  xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
  xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
  <para>
   To update a static group, you either add members or remove members.
   For sample code, see
   <link
    xlink:href="../resources/org/forgerock/opendj/examples/UpdateGroup.java"
    xlink:show="new"
   >UpdateGroup.java</link>.
  </para>

  <para>The <literal>UpdateGroup</literal> example checks that the directory
  server supports the Permissive Modify control. With directory servers such