Indexing

Mark Craig

23.05.2012 5942d234364964fc8da089d8867d4c7570b1b02d

Indexing

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

@@ -37,6 +37,10 @@

 <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
@@ -104,6 +108,14 @@
 
 <section xml:id="simple-auth-with-starttls-or-ssl">
  <title>Start TLS &amp; 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
@@ -180,6 +192,10 @@
 
 <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

 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 &amp; 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

 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

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

 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>

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

@@ -38,6 +38,14 @@

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

 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 &#8212; adapting your
 application for use in different languages and regions &#8212; how much you

 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

 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 &amp; 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

 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 &amp; 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 &amp; 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 &amp; 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

 opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml

@@ -30,6 +30,10 @@
 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
@@ -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=\" # \+ \, \; \&lt; = \&gt; \\ DN Escape Characters,dc=example,dc=com
objectClass: person
@@ -195,6 +207,11 @@
 
 <section xml:id="ldap-client-server-communication">
  <title>LDAP Client &amp; 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
@@ -285,6 +323,10 @@
  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
@@ -292,6 +334,10 @@
  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

 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 &amp; 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>

 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>