From 5942d234364964fc8da089d8867d4c7570b1b02d Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Wed, 23 May 2012 10:05:29 +0000
Subject: [PATCH] Indexing
---
opendj3/src/main/docbkx/dev-guide/chap-ldif.xml | 11 +
opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml | 58 +++++
opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml | 19 +
opendj3/src/main/docbkx/dev-guide/chap-getting-directory-info.xml | 14 +
opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml | 22 +
opendj3/src/main/docbkx/dev-guide/chap-writing.xml | 29 ++
opendj3/src/main/docbkx/dev-guide/chap-extended-ops.xml | 38 +++
opendj3/src/main/docbkx/dev-guide/chap-i18n.xml | 3
opendj3/src/main/docbkx/dev-guide/chap-get-sdk.xml | 39 +++
opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml | 65 ++++++
opendj3/src/main/docbkx/dev-guide/chap-reading.xml | 54 +++++
opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml | 24 ++
opendj3/src/main/docbkx/dev-guide/chap-controls.xml | 183 ++++++++++++++++++
13 files changed, 546 insertions(+), 13 deletions(-)
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml b/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml
index ebe02f2..0200c25 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml
@@ -37,7 +37,11 @@
<section xml:id="simple-auth">
<title>Simple Authentication</title>
-
+ <indexterm>
+ <primary>Authentications</primary>
+ <secondary>Simple</secondary>
+ </indexterm>
+
<para>You perform simple authentication by binding with the distinguished
name of a user's directory entry and the user's password. For this reason
simple authentication over unsecure network connections should be done only
@@ -104,7 +108,15 @@
<section xml:id="simple-auth-with-starttls-or-ssl">
<title>Start TLS & SSL Authentication</title>
-
+ <indexterm>
+ <primary>Authentications</primary>
+ <secondary>StartTLS, SSL</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>StartTLS</secondary>
+ </indexterm>
+
<para>Simple authentication involves sending a user name and password to
the directory server. To avoid sending the user name and password in
the clear, you can use SSL or Start TLS.</para>
@@ -180,7 +192,11 @@
<section xml:id="sasl-auth">
<title>SASL Authentication</title>
-
+ <indexterm>
+ <primary>Authentications</primary>
+ <secondary>SASL</secondary>
+ </indexterm>
+
<para>Simple Authentication and Security Layer (SASL) provides a way to
use other mechanisms for authentication such as Kerberos or Digest
authentication, or even to define your own authentication mechanism. The
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml b/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml
index 932596a..2031be8 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml
@@ -36,6 +36,12 @@
<section xml:id="authenticate-correctly">
<title>Authenticate Correctly</title>
+ <indexterm>
+ <primary>Authentications</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
<para>Unless your application performs only read operations, you should
authenticate to the directory server. Some directory administrators require
@@ -62,6 +68,10 @@
<section xml:id="reuse-connections">
<title>Reuse Connections</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Pooling</secondary>
+ </indexterm>
<para>LDAP is a stateful protocol. You authenticate (bind), you do stuff,
you unbind. The server maintains a context that lets it make authorization
@@ -77,6 +87,10 @@
<section xml:id="health-check-connections">
<title>Health Check Connections</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Health check</secondary>
+ </indexterm>
<para>In a network built for HTTP applications, your long-lived LDAP
connections can get cut by network equipment configured to treat idle and
@@ -87,6 +101,11 @@
make sure nothing on the network quietly decided to drop your connection
without notification. A health check might involve reading an attribute
on a well-known entry in the directory.</para>
+
+ <para>OpenDJ LDAP SDK offers
+ <literal>Connections.newHeartBeatConnectionFactory()</literal> methods to
+ ensure your <literal>ConnectionFactory</literal> serves connections that
+ are periodically checked to detect whether they are still alive.</para>
</section>
<section xml:id="request-what-you-need-all-at-once">
@@ -101,6 +120,9 @@
<section xml:id="use-specific-filters">
<title>Use Specific LDAP Filters</title>
+ <indexterm>
+ <primary>Filters</primary>
+ </indexterm>
<para>The difference between a general filter
<literal>(mail=*@example.com)</literal> and a good, specific filter like
@@ -125,6 +147,9 @@
<section xml:id="make-modifications-specific">
<title>Make Modifications Specific</title>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
<para>When you modify attributes with multiple values, for example when you
modify a list of group members, replace or delete specific values
@@ -135,6 +160,10 @@
<section xml:id="trust-result-codes">
<title>Trust Result Codes</title>
+ <indexterm>
+ <primary>Errors</primary>
+ <secondary>Result codes</secondary>
+ </indexterm>
<para>Trust the LDAP result code that your application gets from the
directory server. For example, if you request a modify application and you
@@ -150,6 +179,9 @@
directory server instance, you could get a result that differs from what
you expect.</para>
+ <indexterm>
+ <primary>Assertions</primary>
+ </indexterm>
<para>The loosely convergent model also means that the entry could have
changed since you read it. If needed, you can use <link xlink:show="new"
xlink:href="http://tools.ietf.org/html/rfc4528">LDAP assertions</link> to set
@@ -158,6 +190,9 @@
<section xml:id="ismemberof-for-membership">
<title>Check Group Membership on the Account, Not the Group</title>
+ <indexterm>
+ <primary>Groups</primary>
+ </indexterm>
<para>If you need to determine which groups an account belongs to, request
<literal>isMemberOf</literal> for example with OpenDJ when you read the
@@ -167,6 +202,10 @@
<section xml:id="ask-directory-what-it-supports">
<title>Ask the Directory Server What It Supports</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
<para>Directory servers expose their capabilities, suffixes they support,
and so forth as attribute values on the root DSE. See the section on
@@ -197,6 +236,9 @@
<section xml:id="storing-large-attributes">
<title>Store Large Attribute Values By Reference</title>
+ <indexterm>
+ <primary>Attributes</primary>
+ </indexterm>
<para>When you use large attribute values such as photos or audio messages,
consider storing the objects themselves elsewhere and keeping only a reference
@@ -212,6 +254,14 @@
<section xml:id="careful-with-persistent-search-and-server-side-sorting">
<title>Take Care With Persistent Search & Server-Side Sorting</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Sorting</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
<para>A persistent search lets your application receive updates from the
server as they happen by keeping the connection open and forcing the server
@@ -236,6 +286,10 @@
<section xml:id="reuse-schemas">
<title>Reuse Schemas Where Possible</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Schema</secondary>
+ </indexterm>
<para>Directory servers like OpenDJ come with schema definitions for a wide
range of standard object classes and attribute types. This is because
@@ -266,6 +320,13 @@
<section xml:id="handle-referrals">
<title>Handle Referrals</title>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
<para>When a directory server returns a search result, the result is not
necessarily an entry. If the result is a referral, then your application
@@ -275,6 +336,10 @@
<section xml:id="check-result-codes">
<title>Troubleshooting: Check Result Codes</title>
+ <indexterm>
+ <primary>Errors</primary>
+ <secondary>Result codes</secondary>
+ </indexterm>
<para>LDAP result codes are standard and clearly defined. When you receive
a <literal>Result</literal>, check the <literal>ResultCode</literal> value to
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-controls.xml b/opendj3/src/main/docbkx/dev-guide/chap-controls.xml
index 9c989cd..7e49e71 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-controls.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-controls.xml
@@ -30,6 +30,13 @@
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Working With Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Controls</secondary>
+ </indexterm>
<para>This chapter demonstrates how to use LDAP controls.</para>
@@ -45,6 +52,14 @@
<section xml:id="get-supported-controls">
<title>Determining Supported Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Supported</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
<para>For OpenDJ, the controls supported are listed in the
<citetitle>Administration Guide</citetitle> appendix, <link
@@ -127,6 +142,13 @@
<section xml:id="use-assertion-request-control">
<title>Assertion Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Assertion</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Assertions</primary>
+ </indexterm>
<para>The <link xlink:href="http://tools.ietf.org/html/rfc4528"
xlink:show="new" >LDAP assertion control</link> lets you specify a condition
@@ -165,6 +187,13 @@
<section xml:id="use-authorization-identity-control">
<title>Authorization Identity Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Authorization ID</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
<para>The <link xlink:href="http://tools.ietf.org/html/rfc3829"
xlink:show="new">LDAP Authorization Identity Controls</link> let you get the
@@ -203,11 +232,22 @@
<section xml:id="use-entry-change-notification-control">
<title>Entry Change Notification Response Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Entry change notification</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Entry change notification</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Change notification</primary>
+ </indexterm>
<para>When performing a persistent search, your application can retrieve
information using this response control about why the directory server
returned the entry. See the Internet-Draft on <link xlink:show="new"
- xlink:href="tools.ietf.org/html/draft-ietf-ldapext-psearch">persistent
+ xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-psearch">persistent
searches</link> for background information.</para>
<programlisting language="java">
@@ -277,6 +317,13 @@
<section xml:id="use-get-effective-rights-control">
<title>GetEffectiveRights Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>GetEffectiveRights</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
<para>Your application can attach the GetEffectiveRights request control to
a search in order to determine what access a user has to perform operations
@@ -380,6 +427,13 @@
<section xml:id="use-managedsait-control">
<title>ManageDsaIT Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>ManageDsaIT</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
<para>The ManageDsaIT control, described in <link xlink:show="new"
xlink:href="http://tools.ietf.org/html/rfc3296">RFC 3296, <citetitle>Named
@@ -432,6 +486,13 @@
<section xml:id="use-matched-values-request-control">
<title>Matched Values Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Matched values</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Groups</primary>
+ </indexterm>
<para>RFC 3876, <link xlink:href="http://tools.ietf.org/html/rfc3876"
xlink:show="new"><citetitle>Returning Matched Values with the
@@ -476,6 +537,14 @@
<section xml:id="use-password-expired-control">
<title>Password Expired Response Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Password expired</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
<para>A directory server can return the Password Expired Response Control,
described in the Internet-Draft <link xlink:show="new"
@@ -518,6 +587,14 @@
<section xml:id="use-password-expiring-control">
<title>Password Expiring Response Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Password expiring</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
<para>The Password Expiring Response Control, described in the Internet-Draft
<link xlink:href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy"
@@ -557,6 +634,14 @@
<section xml:id="use-password-policy-controls">
<title>Password Policy Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
<para>The Behera Internet-Draft, <link xlink:show="new"
xlink:href="http://tools.ietf.org/html/draft-behera-ldap-password-policy"
@@ -621,6 +706,14 @@
<section xml:id="use-permissive-modify-request-control">
<title>Permissive Modify Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Permissive modify</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Modifications</primary>
+ <secondary>Permissive modify</secondary>
+ </indexterm>
<para>Microsoft defined a Permissive Modify Request Control that relaxes
some constraints when your application performs a modify operation and
@@ -651,12 +744,31 @@
<section xml:id="use-persistent-search-request-control">
<title>Persistent Search Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Change notification</primary>
+ </indexterm>
<para>See <xref linkend="use-entry-change-notification-control" />.</para>
</section>
<section xml:id="use-post-read-control">
<title>Post-Read Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Post-read</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
<para>RFC 4527, <link xlink:href="http://tools.ietf.org/html/rfc4527"
xlink:show="new"><citetitle>LDAP Read Entry Controls</citetitle></link>,
@@ -699,6 +811,13 @@
<section xml:id="use-pre-read-control">
<title>Pre-Read Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Pre-read</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Assertions</primary>
+ </indexterm>
<para>RFC 4527, <link xlink:href="http://tools.ietf.org/html/rfc4527"
xlink:show="new"><citetitle>LDAP Read Entry Controls</citetitle></link>,
@@ -741,6 +860,13 @@
<section xml:id="use-proxy-authz-control">
<title>Proxied Authorization Request Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Proxied authorization</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
<para>Proxied authorization provides a standard control as defined in
<link xlink:href="http://tools.ietf.org/html/rfc4370" xlink:show="new">RFC
@@ -784,6 +910,20 @@
<section xml:id="use-server-side-sort-control">
<title>Server-Side Sort Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Server-side sort</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Server-side sort</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Browsing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Sorting</primary>
+ </indexterm>
<para>The server-side sort controls are described in RFC 2891, <link
xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc2891"><citetitle
@@ -889,6 +1029,17 @@
<section xml:id="use-simple-paged-results-control">
<title>Simple Paged Results Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Simple paged results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Simple paged results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Browsing</primary>
+ </indexterm>
<para>RFC 2696, <link xlink:href="http://tools.ietf.org/html/rfc2696"
xlink:show="new"><citetitle>LDAP Control Extension for Simple Paged Results
@@ -964,6 +1115,14 @@
<section xml:id="use-subentry-request-control">
<title>Subentries Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Subentries</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Subentries</secondary>
+ </indexterm>
<para>RFC 3672, <link xlink:href="http://tools.ietf.org/html/rfc3672"
xlink:show="new"><citetitle>Subentries in LDAP</citetitle></link>, describes
@@ -1022,6 +1181,14 @@
<section xml:id="use-subtree-delete-control">
<title>Subtree Delete Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Subtree delete</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Deletes</primary>
+ <secondary>Subtree delete</secondary>
+ </indexterm>
<para>The subtree delete request control, described in the Internet-Draft
<link xlink:href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete"
@@ -1055,6 +1222,20 @@
<section xml:id="use-vlv-control">
<title>Virtual List View Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Virtual list view</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Virtual list view</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Browsing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Sorting</primary>
+ </indexterm>
<para>The virtual list view controls are intended to be used by applications
that let users browse lists of directory entries. The Internet-Draft <link
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-extended-ops.xml b/opendj3/src/main/docbkx/dev-guide/chap-extended-ops.xml
index f5be0c9..ec42f19 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-extended-ops.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-extended-ops.xml
@@ -30,6 +30,13 @@
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Working With Extended Operations</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Extended operations</secondary>
+ </indexterm>
<para>This chapter demonstrates how to use LDAP extended operations.</para>
@@ -41,6 +48,14 @@
<section xml:id="get-supported-extended-operations">
<title>Determining Supported Extended Operations</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Supported</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
<para>For OpenDJ, the extended operations supported are listed in the
<citetitle>Administration Guide</citetitle> appendix, <link
@@ -106,6 +121,14 @@
<section xml:id="use-cancel-extended-operation">
<title>Cancel Extended Operation</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Cancel</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Cancel</secondary>
+ </indexterm>
<para>RFC 3909, <link xlink:href="http://tools.ietf.org/html/rfc3909"
xlink:show="new"><citetitle>LDAP Cancel Operation</citetitle></link>, defines
@@ -215,6 +238,14 @@
<section xml:id="use-password-modify-extended-operation">
<title>Password Modify Extended Operation</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Password modify</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Modifications</primary>
+ <secondary>Password modify</secondary>
+ </indexterm>
<para>RFC 3062, <link xlink:href="http://tools.ietf.org/html/rfc3062"
xlink:show="new"><citetitle>LDAP Password Modify Extended
@@ -262,6 +293,13 @@
<section xml:id="use-who-am-i-extended-operation">
<title>Who am I? Extended Operation</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Who am I?</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
<para>RFC 4532, <link xlink:href="http://tools.ietf.org/html/rfc4532"
xlink:show="new"><citetitle>LDAP "Who am I?" Operation</citetitle></link>,
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-get-sdk.xml b/opendj3/src/main/docbkx/dev-guide/chap-get-sdk.xml
index 375c213..8bdaf26 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-get-sdk.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-get-sdk.xml
@@ -36,6 +36,10 @@
<section xml:id="about-opendj-ldap-sdk">
<title>About OpenDJ LDAP SDK</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>About</secondary>
+ </indexterm>
<para>OpenDJ LDAP SDK provides a set of modern, developer-friendly Java APIs
as part of the OpenDJ product suite. The product suite includes the client
@@ -55,6 +59,14 @@
<section xml:id="prepare-ldap-server">
<title>Preparing an LDAP Server</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Data</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Examples</primary>
+ <secondary>Data</secondary>
+ </indexterm>
<para>Install an LDAP server such as OpenDJ directory server that you can
use to test the applications you develop. Also, load sample data into your
@@ -77,6 +89,10 @@
<procedure xml:id="use-maven">
<title>To Include the SDK as a Maven Dependency</title>
+ <indexterm>
+ <primary>Installing</primary>
+ <secondary>With Maven</secondary>
+ </indexterm>
<para>Let that expensive computer you bought do the work.</para>
@@ -117,6 +133,11 @@
<procedure xml:id="install-stable-sdk">
<title>To Install the Latest Stable SDK</title>
+ <indexterm>
+ <primary>Installing</primary>
+ <secondary>From download</secondary>
+ </indexterm>
+
<step>
<!-- Versions in links shouldn't be hard coded. Waiting for an enhancement
http://code.google.com/p/docbkx-tools/issues/detail?id=49 -->
@@ -174,6 +195,11 @@
<procedure xml:id="proc-roll-your-own-sdk">
<title>To Build Your Own SDK From Source</title>
+ <indexterm>
+ <primary>Installing</primary>
+ <secondary>Build your own</secondary>
+ </indexterm>
+
<step>
<para>Make sure you have Subversion (<command>svn</command>) and
Maven (<command>mvn</command>) installed.</para>
@@ -335,4 +361,17 @@
mail: bjensen@example.com
facsimileTelephoneNumber: +1 408 555 1992</screen>
</section>
+
+ <section xml:id="opendj-ldap-sdk-examples">
+ <title>Accessing Example Java Code</title>
+ <indexterm>
+ <primary>Examples</primary>
+ <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"></link>OpenDJ community site. There you find samples
+ whose excerpts are shown in this guide.</para>
+ </section>
</chapter>
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-getting-directory-info.xml b/opendj3/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
index 404b28f..8613431 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
@@ -38,7 +38,15 @@
<section xml:id="read-root-dse">
<title>Reading Root DSEs</title>
-
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Root DSE</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
+
<para>The directory with distinguished name <literal>""</literal> (empty
string) is called the <firstterm>root DSE</firstterm>. DSE stands for
DSA-Specific Entry. DSA stands for Directory Server Agent, a single
@@ -169,6 +177,10 @@
<section xml:id="get-schema-information">
<title>Getting Schema Information</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Schema</secondary>
+ </indexterm>
<para>The root DSE attribute <literal>subschemaSubentry</literal> shows
the DN of the entry holding LDAP schema definitions. LDAP schema defines the
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-i18n.xml b/opendj3/src/main/docbkx/dev-guide/chap-i18n.xml
index 264cafd..e2a8802 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-i18n.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-i18n.xml
@@ -30,6 +30,9 @@
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Internationalizing Applications</title>
+ <indexterm>
+ <primary>Internationalization</primary>
+ </indexterm>
<para>When you internationalize your application — adapting your
application for use in different languages and regions — how much you
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml b/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml
index 6460d7c..7731c83 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-ldif.xml
@@ -38,6 +38,9 @@
<section xml:id="about-ldif">
<title>About LDIF</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ </indexterm>
<para>LDAP Data Interchange Format provides a mechanism to represent
directory data in text format. LDIF data is typically used to initialize
@@ -115,6 +118,10 @@
<section xml:id="reading-ldif">
<title>Reading LDIF</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Reading</secondary>
+ </indexterm>
<para>OpenDJ LDAP SDK provides <literal>ChangeRecordReader</literal>s to
read requests to modify directory data, and <literal>EntryReader</literal>s
@@ -146,6 +153,10 @@
<section xml:id="writing-ldif">
<title>Writing LDIF</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Writing</secondary>
+ </indexterm>
<para><literal>ChangeRecordWriter</literal>s let you write requests to modify
directory data, whereas <literal>EntryWriter</literal>s let you write entries
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-reading.xml b/opendj3/src/main/docbkx/dev-guide/chap-reading.xml
index 064a4f8..aaea764 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-reading.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-reading.xml
@@ -39,6 +39,10 @@
<section xml:id="about-searching">
<title>About Searching</title>
+ <indexterm>
+ <primary>Searches</primary>
+ </indexterm>
+
<itemizedlist>
<para>An LDAP search looks up entries based on the following
parameters.</para>
@@ -70,7 +74,9 @@
stored on the standard <literal>mail</literal> attribute, and full names are
store on the standard <literal>cn</literal> attribute.</para>
- <para>You figure out how to authenticate from the chapter on authentication,
+ <para>You figure out how to authenticate from the chapter on <link
+ xlink:href="dev-guide#chap-authenticating"
+ xlink:role="http://docbook.org/xlink/role/olink">authentication</link>,
in which you learn you need a bind DN and a password to do simple
authentication. But how do you find the bind DN given the email? How do you
get the full name?</para>
@@ -144,6 +150,14 @@
<section xml:id="basedn-and-scope">
<title>Setting Search Base & Scope</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Base</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Scope</secondary>
+ </indexterm>
<para>Directory servers organize entries somewhat like a file system.
Directory data is often depicted as an upside-down tree.</para>
@@ -214,6 +228,13 @@
<section xml:id="about-filters">
<title>Working With Search Filters</title>
+ <indexterm>
+ <primary>Filters</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Filters</secondary>
+ </indexterm>
<para>When you look someone up in the telephone directory, you use the value
of one attribute of a person's entry (last name), to recover the person's
@@ -364,6 +385,13 @@
<section xml:id="send-search-request">
<title>Sending a Search Request</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Synchronous</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ </indexterm>
<para>As shown in the following excerpt with a synchronous connection, you
get a <literal>Connection</literal> to the directory server from an
@@ -396,6 +424,10 @@
<section xml:id="get-search-results">
<title>Getting Search Results</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
<para>Depending on the method you use to search, you handle results in
different ways.</para>
@@ -459,6 +491,9 @@
<section xml:id="handle-entry-attributes">
<title>Working With Entry Attributes</title>
+ <indexterm>
+ <primary>Attributes</primary>
+ </indexterm>
<para>When you get an entry object, chances are you want to handle attribute
values as objects. The OpenDJ LDAP SDK provides the
@@ -503,6 +538,13 @@
<section xml:id="handle-ldap-urls">
<title>Working With LDAP URLs</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>URLs</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
<para>LDAP URLs express search requests in URL form. In the directory data
you can find them used as <literal>memberURL</literal>
@@ -523,6 +565,13 @@
<section xml:id="sort-search-results">
<title>Sorting Search Results</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Sorting</primary>
+ </indexterm>
<para>If you want to sort search results in your client application, then
make sure you have enough memory in the JVM to hold the results of the search,
@@ -546,6 +595,9 @@
<section xml:id="about-comparisons">
<title>About Comparing</title>
+ <indexterm>
+ <primary>Comparisons</primary>
+ </indexterm>
<para>You use the LDAP compare operation to make an assertion about an
attribute value on an entry. Unlike the search operation, you must know
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml b/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml
index d4ed13f..0752726 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-simple-proxy.xml
@@ -30,6 +30,10 @@
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Writing a Simple LDAP Proxy</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <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"
@@ -37,6 +41,10 @@
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>
+ </indexterm>
<para>The Proxy example sets up connections pools with load balancing to the
directory servers. It passes the connection factories to a
@@ -58,6 +66,10 @@
<section xml:id="connection-pooling">
<title>Connection Pooling</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Pooling</secondary>
+ </indexterm>
<para>As shown in the Proxy example, the
<literal>Connections.newFixedConnectionPool()</literal> returns a connection
@@ -95,6 +107,10 @@
<section xml:id="load-balancing-and-failover">
<title>Load Balancing & Failover</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Load balancing</secondary>
+ </indexterm>
<para>The <literal>Connections.newLoadBalancer()</literal> method returns a
load balancer based on the algorithm you choose. Algorithms include both
@@ -116,6 +132,10 @@
<section xml:id="handling-client-connections">
<title>Listening For & Handling Client Connections</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Listening for</secondary>
+ </indexterm>
<para>You create an <literal>LDAPListener</literal> to handle incoming client
connections. The <literal>LDAPListener</literal> takes a connection handler
@@ -161,6 +181,10 @@
<section xml:id="dn-attr-rewriting">
<title>DN & Attribute Rewriting</title>
+ <indexterm>
+ <primary>Attributes</primary>
+ <secondary>Rewriting</secondary>
+ </indexterm>
<para>Suppose you have a client application that expects a different
attribute name, such as <literal>fullname</literal> for a standard attribute
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml b/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml
index c38632c..608df1e 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml
@@ -30,7 +30,11 @@
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Understanding LDAP</title>
-
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>About</secondary>
+ </indexterm>
+
<para>A directory resembles a dictionary or a phone book. If you know a
word, you can look it up its entry in the dictionary to learn its definition
or its pronunciation. If you know a name, you can look it up its entry in the
@@ -93,6 +97,14 @@
<section xml:id="directory-data">
<title>Data In LDAP Directories</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Data</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Attributes</primary>
+ </indexterm>
+
<para>LDAP directory data is organized into entries, similar to the entries
for words in the dictionary, or for subscriber names in the phone book.
A sample entry follows.</para>
@@ -140,9 +152,9 @@
<para>The entry also has a unique identifier, show at the top of the entry,
<literal>dn: uid=bjensen,ou=People,dc=example,dc=com</literal>. DN stands
for distinguished name. No two entries in the directory have the same
- distinguished name.<footnote><para>Sometimes your distinguished names
- include characters that you must escape. The following example shows an entry
- that includes escaped characters in the DN.</para>
+ distinguished name.<footnote><para>Sometimes your distinguished names include
+ characters that you must escape. The following example shows an entry that
+ includes escaped characters in the DN.</para>
<screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=escape)"
dn: cn=\" # \+ \, \; \< = \> \\ DN Escape Characters,dc=example,dc=com
objectClass: person
@@ -195,6 +207,11 @@
<section xml:id="ldap-client-server-communication">
<title>LDAP Client & Server Communication</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Connected protocol</secondary>
+ </indexterm>
+
<para>You may be used to web service client server communication, where
each time the web client has something to request of the web server, a
connection is set up and then torn down. LDAP has a different model. In
@@ -215,6 +232,9 @@
<itemizedlist xml:id="standard-ldap-operations">
<para>The standard operations are as follows.</para>
<listitem>
+ <indexterm>
+ <primary>Authentications</primary>
+ </indexterm>
<para>Bind (authenticate). The first operation in an LDAP session involves
the client binding to the LDAP server, with the server authenticating the
client. Authentication identifies the client's identity in LDAP terms, the
@@ -222,6 +242,9 @@
to directory data that the client wants to lookup or change.</para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Searches</primary>
+ </indexterm>
<para>Search (lookup). After binding, the client can request that the server
return entries based on an LDAP filter, which is an expression that the
server uses to find entries that match the request, and a base DN under
@@ -232,11 +255,17 @@
<literal>(mail=bjensen@example.com)</literal>.</para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Comparisons</primary>
+ </indexterm>
<para>Compare. After binding, the client can request that the server
compare an attribute value the client specifies with the value stored
on an entry in the directory.</para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
<para>Modify. After binding, the client can request that the server
change one or more attribute values stored on one or more entries. Often
administrators do not allow clients to change directory data, so request
@@ -244,15 +273,24 @@
application if you want to update data.</para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Adds</primary>
+ </indexterm>
<para>Add. After binding, the client can request to add one or more
new LDAP entries to the server. </para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Deletes</primary>
+ </indexterm>
<para>Delete. After binding, the client can request that the server
delete one or more entries. To delete and entry with other entries
underneath, first delete the children, then then parent.</para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Renames</primary>
+ </indexterm>
<para>Modify DN. After binding, the client can request that the server
change the distinguished name of the entry. For example, if Barbara
changes her unique identifier from <literal>bjensen</literal> to something
@@ -284,14 +322,22 @@
operations that directory servers can perform. One mechanism involves using
LDAP controls. The other mechanism involves using LDAP extended
operations.</para>
-
+
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>About</secondary>
+ </indexterm>
<para>LDAP controls are information added to an LDAP message to further
specify how an LDAP operation should be processed. For example, the
Server Side Sort Request Control modifies a search to request that the
directory server return entries to the client in sorted order. The Subtree
Delete Request Control modifies a delete to request that the server
also remove child entries of the entry targeted for deletion.</para>
-
+
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>About</secondary>
+ </indexterm>
<para>LDAP extended operations are additional LDAP operations not included
in the original standard list. For example, the Cancel Extended Operation
works like an abandon operation, but finishes with a response from the
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml b/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
index 566b038..0328b72 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
@@ -38,9 +38,16 @@
connection. You then use the connection to make requests and get responses
from the directory server.</para>
-
<section xml:id="sync-vs-async">
<title>Synchronous & Asynchronous Operations</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Asynchronous</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Synchronous</secondary>
+ </indexterm>
<para>For synchronous operations your application gets a connection from
the <literal>LDAPConnectionFactory</literal> and requests operations on
@@ -118,6 +125,9 @@
<section xml:id="error-handling">
<title>Managing Errors</title>
+ <indexterm>
+ <primary>Errors</primary>
+ </indexterm>
<para>LDAP <link xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A"
xlink:show="new">defines many result codes</link> to deal with conditions
@@ -161,6 +171,13 @@
<section xml:id="referral-handling">
<title>Managing Referrals</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
<para>TODO</para>
</section>
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-writing.xml b/opendj3/src/main/docbkx/dev-guide/chap-writing.xml
index 4736416..5533dae 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-writing.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-writing.xml
@@ -46,6 +46,10 @@
<itemizedlist>
<listitem>
+ <indexterm>
+ <primary>Adds</primary>
+ </indexterm>
+
<para>An add request is used to create a new entry in an LDAP directory.
The entry must have a unique distinguished name that belongs under a base
DN served by the directory. The entry must have a list of attributes that
@@ -60,10 +64,16 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
<para>A modify request is used to add, delete, or replace attribute values
on an entry in an LDAP directory. The resulting entry must be valid
according to the directory schema.</para>
+ <indexterm>
+ <primary>Renames</primary>
+ </indexterm>
<para>A modify DN request is used to rename or move a directory entry.
In both cases the distinguished name changes. Renaming involves changing
the relative distinguished name, for example from
@@ -80,6 +90,10 @@
</listitem>
<listitem>
+ <indexterm>
+ <primary>Deletes</primary>
+ </indexterm>
+
<para>A delete request is used to remove an entry from an LDAP
directory.</para>
@@ -92,6 +106,9 @@
</listitem>
</itemizedlist>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
<para>As a rule, your client application must be authorized to create,
update, and delete directory data. Therefore to prepare to change directory
data, you first get a connection, and then bind on that connection as a
@@ -100,6 +117,9 @@
<section xml:id="adding-entries">
<title>Adding Directory Entries</title>
+ <indexterm>
+ <primary>Adds</primary>
+ </indexterm>
<para>The <literal>Connection.add()</literal> methods let you provide the
entry to add as an <literal>AddRequest</literal>, an <literal>Entry</literal>,
@@ -144,6 +164,9 @@
<section xml:id="modifying-attr-values">
<title>Modifying Directory Entry Attribute Values</title>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
<para>The <literal>Connection.modify()</literal> methods let you add, replace,
and delete attributes values on an entry. Either the modifications are
@@ -182,6 +205,9 @@
<section xml:id="renaming-entries">
<title>Renaming Directory Entries</title>
+ <indexterm>
+ <primary>Renames</primary>
+ </indexterm>
<para>The <literal>Connection.modifyDN()</literal> methods serve to rename
entries and to move them around.</para>
@@ -217,6 +243,9 @@
<section xml:id="deleting-entries">
<title>Deleting Directory Entries</title>
+ <indexterm>
+ <primary>Deletes</primary>
+ </indexterm>
<para>The following excerpt demonstrates how to delete an entry with DN
<literal>cn=Ted,ou=People,dc=example,dc=com</literal>.</para>
--
Gitblit v1.10.0