From 1e74b0f8f046cc9e69ba9eddbc180bf10ab83e06 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Thu, 20 Sep 2012 16:58:20 +0000
Subject: [PATCH] CR-701 Fix for OPENDJ-596: Include more examples in LDAP SDK Javadoc
---
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyResponseControl.java | 37 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadRequestControl.java | 19 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortResponseControl.java | 21 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordWriter.java | 18
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityRequestControl.java | 20 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ModifyRequest.java | 12
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SimpleBindRequest.java | 20 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/WhoAmIExtendedResult.java | 18
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadResponseControl.java | 19 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/GetEffectiveRightsRequestControl.java | 25 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ManageDsaITRequestControl.java | 24 +
opendj3/src/main/docbkx/dev-guide/chap-writing.xml | 5
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/IntermediateResponse.java | 3
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/EntryChangeNotificationResponseControl.java | 34 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/WhoAmIExtendedRequest.java | 18
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiredResponseControl.java | 22 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/TreeMapEntry.java | 15
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewResponseControl.java | 64 +++
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AssertionRequestControl.java | 19 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/FailoverLoadBalancingAlgorithm.java | 2
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/MatchedValuesRequestControl.java | 14
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadResponseControl.java | 20 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PlainSASLBindRequest.java | 14
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordReader.java | 19 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/AttributeUsage.java | 3
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/DeleteRequest.java | 10
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LinkedHashMapEntry.java | 15
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewRequestControl.java | 64 +++
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PermissiveModifyRequestControl.java | 13
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiringResponseControl.java | 18
opendj3/opendj-ldap-sdk/src/main/javadoc/overview.html | 29
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubentriesRequestControl.java | 34 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/CompareResult.java | 16
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortRequestControl.java | 25 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/SSLContextBuilder.java | 19 +
opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml | 6
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SimplePagedResultsControl.java | 66 +++
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/StartTLSExtendedRequest.java | 19 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/CompareRequest.java | 16
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityResponseControl.java | 20 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/ObjectClassType.java | 3
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ExtendedRequest.java | 17
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/Entry.java | 8
opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/SASLAuth.java | 6
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadRequestControl.java | 20 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PasswordModifyExtendedRequest.java | 20 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/Control.java | 16
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ProxiedAuthV2RequestControl.java | 21 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SASLBindRequest.java | 3
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyRequestControl.java | 35 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LDAPOptions.java | 16
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubtreeDeleteRequestControl.java | 10
opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ShortLife.java | 13
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SearchRequest.java | 19 +
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PersistentSearchRequestControl.java | 37 +
55 files changed, 1,062 insertions(+), 37 deletions(-)
diff --git a/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/SASLAuth.java b/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/SASLAuth.java
index 110174e..5189be6 100644
--- a/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/SASLAuth.java
+++ b/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/SASLAuth.java
@@ -90,10 +90,8 @@
new LDAPConnectionFactory(host, port, getTrustAllOptions());
connection = factory.getConnection();
PlainSASLBindRequest request =
- Requests.newPlainSASLBindRequest(authcid, passwd.toCharArray());
- if (authzid != null) {
- request.setAuthorizationID(authzid);
- }
+ Requests.newPlainSASLBindRequest(authcid, passwd.toCharArray())
+ .setAuthorizationID(authzid);
connection.bind(request);
System.out.println("Authenticated as " + authcid + ".");
} catch (final ErrorResultException e) {
diff --git a/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ShortLife.java b/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ShortLife.java
index adb15d1..0f15df9 100644
--- a/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ShortLife.java
+++ b/opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/ShortLife.java
@@ -29,7 +29,6 @@
import java.io.IOException;
import org.forgerock.opendj.ldap.Connection;
-import org.forgerock.opendj.ldap.DN;
import org.forgerock.opendj.ldap.Entries;
import org.forgerock.opendj.ldap.Entry;
import org.forgerock.opendj.ldap.ErrorResultException;
@@ -83,8 +82,8 @@
char[] adminPwd = "bribery".toCharArray();
// An entry to add to the directory
- DN entryDN = DN.valueOf("cn=Bob,ou=People,dc=example,dc=com");
- Entry entry = new LinkedHashMapEntry(entryDN.toString())
+ String entryDN = "cn=Bob,ou=People,dc=example,dc=com";
+ Entry entry = new LinkedHashMapEntry(entryDN)
.addAttribute("cn", "Bob")
.addAttribute("objectclass", "top")
.addAttribute("objectclass", "person")
@@ -116,15 +115,15 @@
System.out.println("...done.");
System.out.println("Renaming the entry...");
- DN newDN = DN.valueOf("cn=Ted,ou=People,dc=example,dc=com");
- entry = entry.setName(newDN);
+ String newDN = "cn=Ted,ou=People,dc=example,dc=com";
+ entry =entry.setName(newDN);
writeToConsole(writer, entry);
- connection.modifyDN(entryDN.toString(), "cn=Ted");
+ connection.modifyDN(entryDN, "cn=Ted");
System.out.println("...done.");
System.out.println("Deleting the entry...");
writeToConsole(writer, entry);
- connection.delete(newDN.toString());
+ connection.delete(newDN);
System.out.println("...done.");
} catch (final ErrorResultException e) {
System.err.println(e.getMessage());
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/Entry.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/Entry.java
index 0688857..6a5aabf 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/Entry.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/Entry.java
@@ -435,7 +435,9 @@
* {@code attribute} is empty then the entire attribute will be removed if
* it is present.
* <p>
- * <b>NOTE:</b> This method implements LDAP Modify replace semantics.
+ * <b>NOTE:</b> This method implements LDAP Modify replace semantics as
+ * described in <a href="http://tools.ietf.org/html/rfc4511#section-4.6"
+ * >RFC 4511 - Section 4.6. Modify Operation</a>.
*
* @param attribute
* The attribute values to be added to this entry, replacing any
@@ -462,7 +464,9 @@
* Any attribute values which are not instances of {@code ByteString} will
* be converted using the {@link ByteString#valueOf(Object)} method.
* <p>
- * <b>NOTE:</b> This method implements LDAP Modify replace semantics.
+ * <b>NOTE:</b> This method implements LDAP Modify replace semantics as
+ * described in <a href="http://tools.ietf.org/html/rfc4511#section-4.6"
+ * >RFC 4511 - Section 4.6. Modify Operation</a>.
*
* @param attributeDescription
* The name of the attribute whose values are to be replaced.
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/FailoverLoadBalancingAlgorithm.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/FailoverLoadBalancingAlgorithm.java
index 52b01e9..44c1ed1 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/FailoverLoadBalancingAlgorithm.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/FailoverLoadBalancingAlgorithm.java
@@ -35,7 +35,7 @@
* underlying connection factories.
* <p>
* This algorithm is typically used for load-balancing <i>between</i> data
- * centers, where there is preference to always always forward connection
+ * centers, where there is preference to always forward connection
* requests to the <i>closest available</i> data center. This algorithm
* contrasts with the {@link RoundRobinLoadBalancingAlgorithm} which is used for
* load-balancing <i>within</i> a data center.
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LDAPOptions.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LDAPOptions.java
index f7efb6f..4a8e8fc 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LDAPOptions.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LDAPOptions.java
@@ -39,6 +39,22 @@
/**
* Common options for LDAP client connections.
+ * <p>
+ * For example you set LDAP options when you want to use StartTLS.
+ *
+ * <pre>
+ * LDAPOptions options = new LDAPOptions();
+ * SSLContext sslContext =
+ * new SSLContextBuilder().setTrustManager(...).getSSLContext();
+ * options.setSSLContext(sslContext);
+ * options.setUseStartTLS(true);
+ *
+ * String host = ...;
+ * int port = ...;
+ * LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port, options);
+ * Connection connection = factory.getConnection();
+ * // Connection uses StartTLS...
+ * </pre>
*/
public final class LDAPOptions {
private SSLContext sslContext;
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LinkedHashMapEntry.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LinkedHashMapEntry.java
index 2f9b7a2..d4fd25c 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LinkedHashMapEntry.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LinkedHashMapEntry.java
@@ -38,8 +38,19 @@
* An implementation of the {@code Entry} interface which uses a
* {@code LinkedHashMap} for storing attributes. Attributes are returned in the
* same order that they were added to the entry. All operations are supported by
- * this implementation.
- * <p>
+ * this implementation. For example, you can build an entry like this:
+ *
+ * <pre>
+ * Entry entry = new LinkedHashMapEntry("cn=Bob,ou=People,dc=example,dc=com")
+ * .addAttribute("cn", "Bob")
+ * .addAttribute("objectclass", "top")
+ * .addAttribute("objectclass", "person")
+ * .addAttribute("objectclass", "organizationalPerson")
+ * .addAttribute("objectclass", "inetOrgPerson")
+ * .addAttribute("mail", "subgenius@example.com")
+ * .addAttribute("sn", "Dobbs");
+ * </pre>
+ *
* A {@code LinkedHashMapEntry} stores references to attributes which have been
* added using the {@link #addAttribute} methods. Attributes sharing the same
* attribute description are merged by adding the values of the new attribute to
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/SSLContextBuilder.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/SSLContextBuilder.java
index f6f8c9b..2a32f13 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/SSLContextBuilder.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/SSLContextBuilder.java
@@ -39,6 +39,25 @@
* {@link SSLContext} instances for use when securing connections with SSL or
* the StartTLS extended operation. The {@link #getSSLContext()} should be
* called in order to obtain the {@code SSLContext}.
+ * <p>
+ * For example, use the SSL context builder when setting up LDAP options needed
+ * to use StartTLS. {@link org.forgerock.opendj.ldap.TrustManagers
+ * TrustManagers} has methods you can use to set the trust manager for the SSL
+ * context builder.
+ *
+ * <pre>
+ * LDAPOptions options = new LDAPOptions();
+ * SSLContext sslContext =
+ * new SSLContextBuilder().setTrustManager(...).getSSLContext();
+ * options.setSSLContext(sslContext);
+ * options.setUseStartTLS(true);
+ *
+ * String host = ...;
+ * int port = ...;
+ * LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port, options);
+ * Connection connection = factory.getConnection();
+ * // Connection uses StartTLS...
+ * </pre>
*/
public final class SSLContextBuilder {
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/TreeMapEntry.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/TreeMapEntry.java
index f0779f7..515a731 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/TreeMapEntry.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/TreeMapEntry.java
@@ -39,7 +39,20 @@
* for storing attributes. Attributes are returned in ascending order of
* attribute description, with {@code objectClass} first, then all user
* attributes, and finally any operational attributes. All operations are
- * supported by this implementation.
+ * supported by this implementation. For example, you can build an entry like
+ * this:
+ *
+ * <pre>
+ * Entry entry = new TreeMapEntry("cn=Bob,ou=People,dc=example,dc=com")
+ * .addAttribute("cn", "Bob")
+ * .addAttribute("objectclass", "top")
+ * .addAttribute("objectclass", "person")
+ * .addAttribute("objectclass", "organizationalPerson")
+ * .addAttribute("objectclass", "inetOrgPerson")
+ * .addAttribute("mail", "subgenius@example.com")
+ * .addAttribute("sn", "Dobbs");
+ * </pre>
+ *
* <p>
* A {@code TreeMapEntry} stores references to attributes which have been added
* using the {@link #addAttribute} methods. Attributes sharing the same
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AssertionRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AssertionRequestControl.java
index c0a835c..5e78e8f 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AssertionRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AssertionRequestControl.java
@@ -53,6 +53,25 @@
* processed if an assertion applied to the target entry of the operation is
* true. It can be used to construct "test and set", "test and clear", and other
* conditional operations.
+ * <p>
+ * The following excerpt shows how to check that no description exists on an
+ * entry before adding a description.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * connection.bind(...);
+ *
+ * String entryDN = ...;
+ * ModifyRequest request =
+ * Requests.newModifyRequest(entryDN)
+ * .addControl(AssertionRequestControl.newControl(
+ * true, Filter.valueOf("!(description=*)")))
+ * .addModification(ModificationType.ADD, "description",
+ * "Created using LDAP assertion control");
+ *
+ * connection.modify(request);
+ * ...
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc4528">RFC 4528 - Lightweight
* Directory Access Protocol (LDAP) Assertion Control </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityRequestControl.java
index 143e468..3e9e0fd 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityRequestControl.java
@@ -40,6 +40,26 @@
* identity control extends the Lightweight Directory Access Protocol (LDAP)
* bind operation with a mechanism for requesting and returning the
* authorization identity it establishes.
+ * <p>
+ * The following excerpt shows how to get the authorization identity established
+ * when binding to the directory server.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String bindDN = ...;
+ * String bindPassword = ...;
+ *
+ * BindRequest request =
+ * Requests.newSimpleBindRequest(bindDN, bindPassword.toCharArray())
+ * .addControl(AuthorizationIdentityRequestControl
+ * .newControl(true));
+ *
+ * BindResult result = connection.bind(request);
+ * AuthorizationIdentityResponseControl control =
+ * result.getControl(AuthorizationIdentityResponseControl.DECODER,
+ * new DecodeOptions());
+ * // Authorization ID returned: control.getAuthorizationID()
+ * </pre>
*
* @see AuthorizationIdentityResponseControl
* @see org.forgerock.opendj.ldap.requests.WhoAmIExtendedRequest
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityResponseControl.java
index 9910b21..8e594b1 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/AuthorizationIdentityResponseControl.java
@@ -44,6 +44,26 @@
* <p>
* The authorization identity is specified using an authorization ID, or
* {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
+ * <p>
+ * The following excerpt shows how to get the authorization identity established
+ * when binding to the directory server.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String bindDN = ...;
+ * String bindPassword = ...;
+ *
+ * BindRequest request =
+ * Requests.newSimpleBindRequest(bindDN, bindPassword.toCharArray())
+ * .addControl(AuthorizationIdentityRequestControl
+ * .newControl(true));
+ *
+ * BindResult result = connection.bind(request);
+ * AuthorizationIdentityResponseControl control =
+ * result.getControl(AuthorizationIdentityResponseControl.DECODER,
+ * new DecodeOptions());
+ * // Authorization ID returned: control.getAuthorizationID()
+ * </pre>
*
* @see AuthorizationIdentityRequestControl
* @see org.forgerock.opendj.ldap.requests.WhoAmIExtendedRequest
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/Control.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/Control.java
index 4a021ef..ea035f3 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/Control.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/Control.java
@@ -33,6 +33,22 @@
* single LDAP message. A control only affects the semantics of the message it
* is attached to. Controls sent by clients are termed 'request controls', and
* those sent by servers are termed 'response controls'.
+ * <p>
+ * To determine whether a directory server supports a given control, read the
+ * list of supported controls from the root DSE to get a collection of control
+ * OIDs, and then check for a match:
+ *
+ * <pre>
+ * Connection connection = ...;
+ * Collection<String> supported =
+ * RootDSE.readRootDSE(connection).getSupportedControls();
+ *
+ * Control control = ...;
+ * String OID = control.getOID();
+ * if (supported != null && !supported.isEmpty() && supported.contains(OID)) {
+ * // The control is supported. Use it here...
+ * }
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 - Lightweight
* Directory Access Protocol (LDAP): The Protocol </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/EntryChangeNotificationResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/EntryChangeNotificationResponseControl.java
index a3b7011..5f2c150 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/EntryChangeNotificationResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/EntryChangeNotificationResponseControl.java
@@ -52,6 +52,40 @@
* about the change the caused a particular entry to be returned as the result
* of a persistent search.
*
+ * <pre>
+ * Connection connection = ...;
+ *
+ * SearchRequest request =
+ * Requests.newSearchRequest(
+ * "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
+ * "(objectclass=inetOrgPerson)", "cn")
+ * .addControl(PersistentSearchRequestControl.newControl(
+ * true, true, true, // critical,changesOnly,returnECs
+ * PersistentSearchChangeType.ADD,
+ * PersistentSearchChangeType.DELETE,
+ * PersistentSearchChangeType.MODIFY,
+ * PersistentSearchChangeType.MODIFY_DN));
+ *
+ * ConnectionEntryReader reader = connection.search(request);
+ *
+ * while (reader.hasNext()) {
+ * if (!reader.isReference()) {
+ * SearchResultEntry entry = reader.readEntry(); // Entry that changed
+ *
+ * EntryChangeNotificationResponseControl control = entry.getControl(
+ * EntryChangeNotificationResponseControl.DECODER,
+ * new DecodeOptions());
+ *
+ * PersistentSearchChangeType type = control.getChangeType();
+ * if (type.equals(PersistentSearchChangeType.MODIFY_DN)) {
+ * // Previous DN: control.getPreviousName()
+ * }
+ * // Change number: control.getChangeNumber());
+ * }
+ * }
+ *
+ * </pre>
+ *
* @see PersistentSearchRequestControl
* @see PersistentSearchChangeType
* @see <a
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/GetEffectiveRightsRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/GetEffectiveRightsRequestControl.java
index 1a47e21..2a1ba67 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/GetEffectiveRightsRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/GetEffectiveRightsRequestControl.java
@@ -73,6 +73,31 @@
* }
* </pre>
*
+ * You can use the control to retrieve effective rights during a search:
+ *
+ * <pre>
+ * String authDN = ...;
+ *
+ * SearchRequest request =
+ * Requests.newSearchRequest(
+ * "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
+ * "(uid=bjensen)", "cn", "aclRights", "aclRightsInfo")
+ * .addControl(GetEffectiveRightsRequestControl.newControl(
+ * true, authDN, "cn"));
+ *
+ * ConnectionEntryReader reader = connection.search(request);
+ * while (reader.hasNext()) {
+ * if (!reader.isReference()) {
+ * SearchResultEntry entry = reader.readEntry();
+ * // Interpret aclRights and aclRightsInfo
+ * }
+ * }
+ * </pre>
+ *
+ * The entries returned by the search hold the {@code aclRights} and
+ * {@code aclRightsInfo} attributes with the effective rights information. You
+ * must parse the attribute options and values to interpret the information.
+ *
* @see <a
* href="http://tools.ietf.org/html/draft-ietf-ldapext-acl-model">draft-ietf-ldapext-acl-model
* - Access Control Model for LDAPv3 </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ManageDsaITRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ManageDsaITRequestControl.java
index 96c921d..4163b61 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ManageDsaITRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ManageDsaITRequestControl.java
@@ -44,6 +44,30 @@
* objects and instead will treat the referral object as a normal entry. The
* server, however, is still free to return referrals for other reasons.
*
+ * <pre>
+ * // "dc=ref,dc=com" holds a referral to something else.
+ *
+ * // Referral without the ManageDsaIT control:
+ * SearchRequest request = Requests.newSearchRequest(
+ * "dc=ref,dc=com",
+ * SearchScope.SUBORDINATES,
+ * "(objectclass=*)",
+ * "");
+ *
+ * ConnectionEntryReader reader = connection.search(request);
+ * while (reader.hasNext()) {
+ * if (reader.isReference()) {
+ * SearchResultReference ref = reader.readReference();
+ * // References: ref.getURIs()
+ * }
+ * }
+ *
+ * // Referral with the ManageDsaIT control:
+ * request.addControl(ManageDsaITRequestControl.newControl(true));
+ * SearchResultEntry entry = connection.searchSingleEntry(request);
+ * // ...
+ * </pre>
+ *
* @see <a href="http://tools.ietf.org/html/rfc3296">RFC 3296 - Named
* Subordinate References in Lightweight Directory Access Protocol (LDAP)
* Directories </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/MatchedValuesRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/MatchedValuesRequestControl.java
index b488e53..a46f70a 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/MatchedValuesRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/MatchedValuesRequestControl.java
@@ -81,6 +81,20 @@
* matchValue [3] AssertionValue}
* </pre>
*
+ * For example Barbara Jensen's entry contains two common name values, Barbara
+ * Jensen and Babs Jensen. The following code retrieves only the latter.
+ *
+ * <pre>
+ * String DN = "uid=bjensen,ou=People,dc=example,dc=com";
+ * SearchRequest request = Requests.newSearchRequest(DN,
+ * SearchScope.BASE_OBJECT, "(objectclass=*)", "cn")
+ * .addControl(MatchedValuesRequestControl
+ * .newControl(true, "(cn=Babs Jensen)"));
+ *
+ * // Get the entry, retrieving cn: Babs Jensen, not cn: Barbara Jensen
+ * SearchResultEntry entry = connection.searchSingleEntry(request);
+ * </pre>
+ *
* @see <a href="http://tools.ietf.org/html/rfc3876">RFC 3876 - Returning
* Matched Values with the Lightweight Directory Access Protocol version 3
* (LDAPv3) </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiredResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiredResponseControl.java
index 53a0a86..03a2004 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiredResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiredResponseControl.java
@@ -41,6 +41,28 @@
* password has expired and must be changed. This control always has a value
* which is the string {@code "0"}.
*
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ * char[] password = ...;
+ *
+ * try {
+ * connection.bind(DN, password);
+ * } catch (ErrorResultException e) {
+ * Result result = e.getResult();
+ * try {
+ * PasswordExpiredResponseControl control =
+ * result.getControl(PasswordExpiredResponseControl.DECODER,
+ * new DecodeOptions());
+ * if (!(control == null) && control.hasValue()) {
+ * // Password expired
+ * }
+ * } catch (DecodeException de) {
+ * // Failed to decode the response control.
+ * }
+ * }
+ * </pre>
+ *
* @see <a
* href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy">draft-vchu-ldap-pwd-policy
* - Password Policy for LDAP Directories </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiringResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiringResponseControl.java
index 0efaebf..8a8132f 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiringResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordExpiringResponseControl.java
@@ -45,6 +45,24 @@
* control value is a string representation of the number of seconds until
* expiration.
*
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ * char[] password = ...;
+ *
+ * BindResult result = connection.bind(DN, password);
+ * try {
+ * PasswordExpiringResponseControl control =
+ * result.getControl(PasswordExpiringResponseControl.DECODER,
+ * new DecodeOptions());
+ * if (!(control == null) && control.hasValue()) {
+ * // Password expires in control.getSecondsUntilExpiration() seconds
+ * }
+ * } catch (DecodeException de) {
+ * // Failed to decode the response control.
+ * }
+ * </pre>
+ *
* @see <a
* href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy">draft-vchu-ldap-pwd-policy
* - Password Policy for LDAP Directories </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyRequestControl.java
index 19655de..4ea9143 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyRequestControl.java
@@ -44,6 +44,41 @@
* control. When a server receives this control, it will return the password
* policy response control when appropriate and with the proper data.
*
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ * char[] password = ...;
+ *
+ * try {
+ * BindRequest request = Requests.newSimpleBindRequest(DN, password)
+ * .addControl(PasswordPolicyRequestControl.newControl(true));
+ *
+ * BindResult result = connection.bind(request);
+ *
+ * PasswordPolicyResponseControl control =
+ * result.getControl(PasswordPolicyResponseControl.DECODER,
+ * new DecodeOptions());
+ * if (!(control == null) && !(control.getWarningType() == null)) {
+ * // Password policy warning, use control.getWarningType(),
+ * // and control.getWarningValue().
+ * }
+ * } catch (ErrorResultException e) {
+ * Result result = e.getResult();
+ * try {
+ * PasswordPolicyResponseControl control =
+ * result.getControl(PasswordPolicyResponseControl.DECODER,
+ * new DecodeOptions());
+ * if (!(control == null)) {
+ * // Password policy error, use control.getErrorType().
+ * }
+ * } catch (DecodeException de) {
+ * // Failed to decode the response control.
+ * }
+ * } catch (DecodeException e) {
+ * // Failed to decode the response control.
+ * }
+ * </pre>
+ *
* @see PasswordPolicyResponseControl
* @see <a href="http://tools.ietf.org/html/draft-behera-ldap-password-policy">
* draft-behera-ldap-password-policy - Password Policy for LDAP Directories
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyResponseControl.java
index 5e6baec..b8c7a1f 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PasswordPolicyResponseControl.java
@@ -47,7 +47,42 @@
/**
* The password policy response control as defined in
* draft-behera-ldap-password-policy.
- * <p>
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ * char[] password = ...;
+ *
+ * try {
+ * BindRequest request = Requests.newSimpleBindRequest(DN, password)
+ * .addControl(PasswordPolicyRequestControl.newControl(true));
+ *
+ * BindResult result = connection.bind(request);
+ *
+ * PasswordPolicyResponseControl control =
+ * result.getControl(PasswordPolicyResponseControl.DECODER,
+ * new DecodeOptions());
+ * if (!(control == null) && !(control.getWarningType() == null)) {
+ * // Password policy warning, use control.getWarningType(),
+ * // and control.getWarningValue().
+ * }
+ * } catch (ErrorResultException e) {
+ * Result result = e.getResult();
+ * try {
+ * PasswordPolicyResponseControl control =
+ * result.getControl(PasswordPolicyResponseControl.DECODER,
+ * new DecodeOptions());
+ * if (!(control == null)) {
+ * // Password policy error, use control.getErrorType().
+ * }
+ * } catch (DecodeException de) {
+ * // Failed to decode the response control.
+ * }
+ * } catch (DecodeException e) {
+ * // Failed to decode the response control.
+ * }
+ * </pre>
+ *
* If the client has sent a passwordPolicyRequest control, the server (when
* solicited by the inclusion of the request control) sends this control with
* the following operation responses: bindResponse, modifyResponse, addResponse,
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PermissiveModifyRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PermissiveModifyRequestControl.java
index 777cca6..89057d5 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PermissiveModifyRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PermissiveModifyRequestControl.java
@@ -55,6 +55,19 @@
* the attribute contains the specified attribute value, and a {@code delete}
* modification <i>ensures</i> that the attribute does not contain the specified
* attribute value.
+ *
+ * <pre>
+ * String groupDN = ...;
+ * String memberDN = ...;
+ * Connection connection = ...;
+ *
+ * // Add a member to a static group, telling the directory server not to
+ * // complain if the member already belongs to the group.
+ * ModifyRequest request = Requests.newModifyRequest(groupDN)
+ * .addControl(PermissiveModifyRequestControl.newControl(true))
+ * .addModification(ModificationType.ADD, "member", memberDN);
+ * connection.modify(request);
+ * </pre>
*/
public final class PermissiveModifyRequestControl implements Control {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PersistentSearchRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PersistentSearchRequestControl.java
index 4ce9171..396d971 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PersistentSearchRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PersistentSearchRequestControl.java
@@ -55,6 +55,43 @@
* The persistent search request control as defined in
* draft-ietf-ldapext-psearch. This control allows a client to receive
* notification of changes that occur in an LDAP server.
+ * <p>
+ * You can examine the entry change notification response control to get more
+ * information about a change returned by the persistent search.
+ *
+ * <pre>
+ * Connection connection = ...;
+ *
+ * SearchRequest request =
+ * Requests.newSearchRequest(
+ * "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
+ * "(objectclass=inetOrgPerson)", "cn")
+ * .addControl(PersistentSearchRequestControl.newControl(
+ * true, true, true, // critical,changesOnly,returnECs
+ * PersistentSearchChangeType.ADD,
+ * PersistentSearchChangeType.DELETE,
+ * PersistentSearchChangeType.MODIFY,
+ * PersistentSearchChangeType.MODIFY_DN));
+ *
+ * ConnectionEntryReader reader = connection.search(request);
+ *
+ * while (reader.hasNext()) {
+ * if (!reader.isReference()) {
+ * SearchResultEntry entry = reader.readEntry(); // Entry that changed
+ *
+ * EntryChangeNotificationResponseControl control = entry.getControl(
+ * EntryChangeNotificationResponseControl.DECODER,
+ * new DecodeOptions());
+ *
+ * PersistentSearchChangeType type = control.getChangeType();
+ * if (type.equals(PersistentSearchChangeType.MODIFY_DN)) {
+ * // Previous DN: control.getPreviousName()
+ * }
+ * // Change number: control.getChangeNumber());
+ * }
+ * }
+ *
+ * </pre>
*
* @see EntryChangeNotificationResponseControl
* @see PersistentSearchChangeType
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadRequestControl.java
index 254faa3..23f6edd 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadRequestControl.java
@@ -55,6 +55,26 @@
* client to read the target entry of an update operation immediately after the
* modifications are applied. These reads are done as an atomic part of the
* update operation.
+ * <p>
+ * The following example gets a modified entry from the result of a modify
+ * operation.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ *
+ * ModifyRequest request =
+ * Requests.newModifyRequest(DN)
+ * .addControl(PostReadRequestControl.newControl(true, "description"))
+ * .addModification(ModificationType.REPLACE,
+ * "description", "Using the PostReadRequestControl");
+ *
+ * Result result = connection.modify(request);
+ * PostReadResponseControl control =
+ * result.getControl(PostReadResponseControl.DECODER,
+ * new DecodeOptions());
+ * Entry modifiedEntry = control.getEntry();
+ * </pre>
*
* @see PostReadResponseControl
* @see <a href="http://tools.ietf.org/html/rfc4527">RFC 4527 - Lightweight
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadResponseControl.java
index ce2f435..edebe12 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PostReadResponseControl.java
@@ -56,6 +56,26 @@
* included a post-read request control. The control contains a Search Result
* Entry containing, subject to access controls and other constraints, values of
* the requested attributes.
+ * <p>
+ * The following example gets a modified entry from the result of a modify
+ * operation.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ *
+ * ModifyRequest request =
+ * Requests.newModifyRequest(DN)
+ * .addControl(PostReadRequestControl.newControl(true, "description"))
+ * .addModification(ModificationType.REPLACE,
+ * "description", "Using the PostReadRequestControl");
+ *
+ * Result result = connection.modify(request);
+ * PostReadResponseControl control =
+ * result.getControl(PostReadResponseControl.DECODER,
+ * new DecodeOptions());
+ * Entry modifiedEntry = control.getEntry();
+ * </pre>
*
* @see PostReadRequestControl
* @see <a href="http://tools.ietf.org/html/rfc4527">RFC 4527 - Lightweight
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadRequestControl.java
index 51653cc..bc00844 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadRequestControl.java
@@ -55,6 +55,25 @@
* client to read the target entry of an update operation immediately before the
* modifications are applied. These reads are done as an atomic part of the
* update operation.
+ * <p>
+ * The following example gets the entry as it was before the modify operation.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ *
+ * ModifyRequest request =
+ * Requests.newModifyRequest(DN)
+ * .addControl(PreReadRequestControl.newControl(true, "mail"))
+ * .addModification(ModificationType.REPLACE,
+ * "mail", "modified@example.com");
+ *
+ * Result result = connection.modify(request);
+ * PreReadResponseControl control =
+ * result.getControl(PreReadResponseControl.DECODER,
+ * new DecodeOptions());
+ * Entry unmodifiedEntry = control.getEntry();
+ * </pre>
*
* @see PreReadResponseControl
* @see <a href="http://tools.ietf.org/html/rfc4527">RFC 4527 - Lightweight
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadResponseControl.java
index 7275bae..e38c545 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/PreReadResponseControl.java
@@ -56,6 +56,25 @@
* included a pre-read request control. The control contains a Search Result
* Entry containing, subject to access controls and other constraints, values of
* the requested attributes.
+ * <p>
+ * The following example gets the entry as it was before the modify operation.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String DN = ...;
+ *
+ * ModifyRequest request =
+ * Requests.newModifyRequest(DN)
+ * .addControl(PreReadRequestControl.newControl(true, "mail"))
+ * .addModification(ModificationType.REPLACE,
+ * "mail", "modified@example.com");
+ *
+ * Result result = connection.modify(request);
+ * PreReadResponseControl control =
+ * result.getControl(PreReadResponseControl.DECODER,
+ * new DecodeOptions());
+ * Entry unmodifiedEntry = control.getEntry();
+ * </pre>
*
* @see PreReadRequestControl
* @see <a href="http://tools.ietf.org/html/rfc4527">RFC 4527 - Lightweight
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ProxiedAuthV2RequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ProxiedAuthV2RequestControl.java
index 9817746..3fcf854 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ProxiedAuthV2RequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ProxiedAuthV2RequestControl.java
@@ -49,6 +49,27 @@
* <p>
* The target user is specified using an authorization ID, or {@code authzId},
* as defined in RFC 4513 section 5.2.1.8.
+ * <p>
+ * This example shows an application replacing a description on a user entry on
+ * behalf of a directory administrator.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String bindDN = "cn=My App,ou=Apps,dc=example,dc=com"; // Client app
+ * char[] password = ...;
+ * String targetDn = "uid=bjensen,ou=People,dc=example,dc=com"; // Regular user
+ * String authzId = "dn:uid=kvaughan,ou=People,dc=example,dc=com"; // Admin user
+ *
+ * ModifyRequest request =
+ * Requests.newModifyRequest(targetDn)
+ * .addControl(ProxiedAuthV2RequestControl.newControl(authzId))
+ * .addModification(ModificationType.REPLACE, "description",
+ * "Done with proxied authz");
+ *
+ * connection.bind(bindDN, password);
+ * connection.modify(request);
+ * Entry entry = connection.readEntry(targetDn, "description");
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc4370">RFC 4370 - Lightweight
* Directory Access Protocol (LDAP) Proxied Authorization Control </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortRequestControl.java
index f88b988..231491d 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortRequestControl.java
@@ -59,8 +59,29 @@
* This controls may be useful when the client has limited functionality or for
* some other reason cannot sort the results but still needs them sorted. In
* cases where the client can sort the results client-side sorting is
- * recommended in order to reduce load on the server. See {@link SortKey} for
- * an example of client-side sorting.
+ * recommended in order to reduce load on the server. See {@link SortKey} for an
+ * example of client-side sorting.
+ * <p>
+ * The following example demonstrates how to work with a server-side sort.
+ *
+ * <pre>
+ * Connection connection = ...;
+ *
+ * SearchRequest request = Requests.newSearchRequest(
+ * "ou=People,dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
+ * .addControl(ServerSideSortRequestControl.newControl(true, new SortKey("cn")));
+ *
+ * SearchResultHandler resultHandler = new MySearchResultHandler();
+ * Result result = connection.search(request, resultHandler);
+ *
+ * ServerSideSortResponseControl control = result.getControl(
+ * ServerSideSortResponseControl.DECODER, new DecodeOptions());
+ * if (control != null && control.getResult() == ResultCode.SUCCESS) {
+ * // Entries are sorted.
+ * } else {
+ * // Entries not sorted.
+ * }
+ * </pre>
*
* @see ServerSideSortResponseControl
* @see SortKey
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortResponseControl.java
index 865e85e..d6043bd 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/ServerSideSortResponseControl.java
@@ -56,6 +56,27 @@
* result code in this control is success. If the server omits this control from
* the search result, the client SHOULD assume that the sort control was ignored
* by the server.
+ * <p>
+ * The following example demonstrates how to work with a server-side sort.
+ *
+ * <pre>
+ * Connection connection = ...;
+ *
+ * SearchRequest request = Requests.newSearchRequest(
+ * "ou=People,dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
+ * .addControl(ServerSideSortRequestControl.newControl(true, new SortKey("cn")));
+ *
+ * SearchResultHandler resultHandler = new MySearchResultHandler();
+ * Result result = connection.search(request, resultHandler);
+ *
+ * ServerSideSortResponseControl control = result.getControl(
+ * ServerSideSortResponseControl.DECODER, new DecodeOptions());
+ * if (control != null && control.getResult() == ResultCode.SUCCESS) {
+ * // Entries are sorted.
+ * } else {
+ * // Entries not sorted.
+ * }
+ * </pre>
*
* @see ServerSideSortRequestControl
* @see <a href="http://tools.ietf.org/html/rfc2891">RFC 2891 - LDAP Control
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SimplePagedResultsControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SimplePagedResultsControl.java
index 26fdad1..7c3a5e0 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SimplePagedResultsControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SimplePagedResultsControl.java
@@ -61,6 +61,72 @@
* cookie OCTET STRING
* }
* </pre>
+ * <p>
+ * The following example demonstrates use of simple paged results to handle
+ * three entries at a time.
+ *
+ * <pre>
+ * ByteString cookie = ByteString.empty();
+ * SearchRequest request;
+ * SearchResultHandler resultHandler = new MySearchResultHandler();
+ * Result result;
+ *
+ * int page = 1;
+ * do {
+ System.out.println("# Simple paged results: Page " + page);
+ *
+ * request = Requests.newSearchRequest(
+ "dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
+ .addControl(SimplePagedResultsControl.newControl(true, 3, cookie));
+ *
+ * result = connection.search(request, resultHandler);
+ * try {
+ * SimplePagedResultsControl control = result.getControl(
+ SimplePagedResultsControl.DECODER, new DecodeOptions());
+ cookie = control.getCookie();
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ }
+ *
+ * ++page;
+ * } while (cookie.length() != 0);
+ * </pre>
+ *
+ * The search result handler in this case displays pages of results as LDIF on
+ * standard out.
+ *
+ * <pre>
+ * private static class MySearchResultHandler implements SearchResultHandler {
+ *
+ * {@literal @}Override
+ * public void handleErrorResult(ErrorResultException error) {
+ * // Ignore.
+ * }
+ *
+ * {@literal @}Override
+ * public void handleResult(Result result) {
+ * // Ignore.
+ * }
+ *
+ * {@literal @}Override
+ * public boolean handleEntry(SearchResultEntry entry) {
+ * final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ * try {
+ * writer.writeEntry(entry);
+ * writer.flush();
+ * } catch (final IOException e) {
+ * // The writer could not write to System.out.
+ * }
+ * return true;
+ * }
+ *
+ * {@literal @}Override
+ * public boolean handleReference(SearchResultReference reference) {
+ * System.out.println("Got a reference: " + reference.toString());
+ * return false;
+ * }
+ * }
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc2696">RFC 2696 - LDAP Control
* Extension for Simple Paged Results Manipulation </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubentriesRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubentriesRequestControl.java
index d0b9c7d..0fdf91a 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubentriesRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubentriesRequestControl.java
@@ -54,6 +54,40 @@
* visible to search operations unless the target/base of the operation is a
* sub-entry. In the presence of the sub-entry request control, sub-entries are
* visible if and only if the control's value is {@code TRUE}.
+ * <p>
+ * Consider "Class of Service" sub-entries such as the following:
+ *
+ * <pre>
+ * dn: cn=Gold Class of Service,dc=example,dc=com
+ * objectClass: collectiveAttributeSubentry
+ * objectClass: extensibleObject
+ * objectClass: subentry
+ * objectClass: top
+ * cn: Gold Class of Service
+ * diskQuota;collective: 100 GB
+ * mailQuota;collective: 10 GB
+ * subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ * gold)" }
+ * </pre>
+ *
+ * To access the sub-entries in your search, use the control with value
+ * {@code TRUE}.
+ *
+ * <pre>
+ * Connection connection = ...;
+ *
+ * SearchRequest request = Requests.newSearchRequest("dc=example,dc=com",
+ * SearchScope.WHOLE_SUBTREE, "cn=*Class of Service", "cn", "subtreeSpecification")
+ * .addControl(SubentriesRequestControl.newControl(true, true));
+ *
+ * ConnectionEntryReader reader = connection.search(request);
+ * while (reader.hasNext()) {
+ * if (reader.isEntry()) {
+ * SearchResultEntry entry = reader.readEntry();
+ * // ...
+ * }
+ * }
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc3672">RFC 3672 - Subentries in
* the Lightweight Directory Access Protocol </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubtreeDeleteRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubtreeDeleteRequestControl.java
index b2e23da..bf9a83b 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubtreeDeleteRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/SubtreeDeleteRequestControl.java
@@ -40,6 +40,16 @@
* This control allows a client to delete an entire subtree of a container entry
* in a single delete operation.
*
+ * <pre>
+ * Connection connection = ...;
+ * String baseDN = ...;
+ *
+ * DeleteRequest request =
+ * Requests.newDeleteRequest(baseDN)
+ * .addControl(SubtreeDeleteRequestControl.newControl(true));
+ * connection.delete(request);
+ * </pre>
+ *
* @see <a
* href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete">draft-armijo-ldap-treedelete
* - Tree Delete Control </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewRequestControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewRequestControl.java
index ade0038..c3f98c8 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewRequestControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewRequestControl.java
@@ -59,6 +59,70 @@
* <p>
* This control is similar to the simple paged results request control, except
* that it allows the client to move backwards and forwards in the result set.
+ * <p>
+ * The following example demonstrates use of the virtual list view controls.
+ *
+ * <pre>
+ * ByteString contextID = ByteString.empty();
+ *
+ * // Add a window of 2 entries on either side of the first sn=Jensen entry.
+ * SearchRequest request = Requests.newSearchRequest("ou=People,dc=example,dc=com",
+ * SearchScope.WHOLE_SUBTREE, "(sn=*)", "sn", "givenName")
+ * .addControl(ServerSideSortRequestControl.newControl(true, new SortKey("sn")))
+ * .addControl(VirtualListViewRequestControl.newAssertionControl(
+ * true, ByteString.valueOf("Jensen"), 2, 2, contextID));
+ *
+ * SearchResultHandler resultHandler = new MySearchResultHandler();
+ * Result result = connection.search(request, resultHandler);
+ *
+ * ServerSideSortResponseControl sssControl =
+ * result.getControl(ServerSideSortResponseControl.DECODER, new DecodeOptions());
+ * if (sssControl != null && sssControl.getResult() == ResultCode.SUCCESS) {
+ * // Entries are sorted.
+ * } else {
+ * // Entries not necessarily sorted
+ * }
+ *
+ * VirtualListViewResponseControl vlvControl =
+ * result.getControl(VirtualListViewResponseControl.DECODER, new DecodeOptions());
+ * // Position in list: vlvControl.getTargetPosition()/vlvControl.getContentCount()
+ * </pre>
+ *
+ * The search result handler in this case displays pages of results as LDIF on
+ * standard out.
+ *
+ * <pre>
+ * private static class MySearchResultHandler implements SearchResultHandler {
+ *
+ * {@literal @}Override
+ * public void handleErrorResult(ErrorResultException error) {
+ * // Ignore.
+ * }
+ *
+ * {@literal @}Override
+ * public void handleResult(Result result) {
+ * // Ignore.
+ * }
+ *
+ * {@literal @}Override
+ * public boolean handleEntry(SearchResultEntry entry) {
+ * final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ * try {
+ * writer.writeEntry(entry);
+ * writer.flush();
+ * } catch (final IOException e) {
+ * // The writer could not write to System.out.
+ * }
+ * return true;
+ * }
+ *
+ * {@literal @}Override
+ * public boolean handleReference(SearchResultReference reference) {
+ * System.out.println("Got a reference: " + reference.toString());
+ * return false;
+ * }
+ * }
+ * </pre>
*
* @see VirtualListViewResponseControl
* @see ServerSideSortRequestControl
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewResponseControl.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewResponseControl.java
index da58acd..c987f00 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewResponseControl.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/controls/VirtualListViewResponseControl.java
@@ -57,6 +57,70 @@
* <p>
* The content count and context ID should be used in a subsequent virtual list
* view requests.
+ * <p>
+ * The following example demonstrates use of the virtual list view controls.
+ *
+ * <pre>
+ * ByteString contextID = ByteString.empty();
+ *
+ * // Add a window of 2 entries on either side of the first sn=Jensen entry.
+ * SearchRequest request = Requests.newSearchRequest("ou=People,dc=example,dc=com",
+ * SearchScope.WHOLE_SUBTREE, "(sn=*)", "sn", "givenName")
+ * .addControl(ServerSideSortRequestControl.newControl(true, new SortKey("sn")))
+ * .addControl(VirtualListViewRequestControl.newAssertionControl(
+ * true, ByteString.valueOf("Jensen"), 2, 2, contextID));
+ *
+ * SearchResultHandler resultHandler = new MySearchResultHandler();
+ * Result result = connection.search(request, resultHandler);
+ *
+ * ServerSideSortResponseControl sssControl =
+ * result.getControl(ServerSideSortResponseControl.DECODER, new DecodeOptions());
+ * if (sssControl != null && sssControl.getResult() == ResultCode.SUCCESS) {
+ * // Entries are sorted.
+ * } else {
+ * // Entries not necessarily sorted
+ * }
+ *
+ * VirtualListViewResponseControl vlvControl =
+ * result.getControl(VirtualListViewResponseControl.DECODER, new DecodeOptions());
+ * // Position in list: vlvControl.getTargetPosition()/vlvControl.getContentCount()
+ * </pre>
+ *
+ * The search result handler in this case displays pages of results as LDIF on
+ * standard out.
+ *
+ * <pre>
+ * private static class MySearchResultHandler implements SearchResultHandler {
+ *
+ * {@literal @}Override
+ * public void handleErrorResult(ErrorResultException error) {
+ * // Ignore.
+ * }
+ *
+ * {@literal @}Override
+ * public void handleResult(Result result) {
+ * // Ignore.
+ * }
+ *
+ * {@literal @}Override
+ * public boolean handleEntry(SearchResultEntry entry) {
+ * final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ * try {
+ * writer.writeEntry(entry);
+ * writer.flush();
+ * } catch (final IOException e) {
+ * // The writer could not write to System.out.
+ * }
+ * return true;
+ * }
+ *
+ * {@literal @}Override
+ * public boolean handleReference(SearchResultReference reference) {
+ * System.out.println("Got a reference: " + reference.toString());
+ * return false;
+ * }
+ * }
+ * </pre>
*
* @see VirtualListViewRequestControl
* @see <a href="http://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv">
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/CompareRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/CompareRequest.java
index 9ad8d85..6235f24 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/CompareRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/CompareRequest.java
@@ -45,6 +45,22 @@
* Note that some directory systems may establish access controls that permit
* the values of certain attributes (such as {@code userPassword} ) to be
* compared but not interrogated by other means.
+ * <p>
+ * The following excerpt shows how to use the Compare operation to check whether
+ * a member belongs to a (possibly large) static group.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String groupDN = ...;
+ * String memberDN = ...;
+ *
+ * CompareRequest request =
+ * Requests.newCompareRequest(groupDN, "member", memberDN);
+ * CompareResult result = connection.compare(request);
+ * if (result.matched()) {
+ * // The member belongs to the group.
+ * }
+ * </pre>
*/
public interface CompareRequest extends Request {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/DeleteRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/DeleteRequest.java
index e2f08d2..4c4e552 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/DeleteRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/DeleteRequest.java
@@ -45,6 +45,16 @@
* Only leaf entries (those with no subordinate entries) can be deleted with
* this operation. However, addition of the {@code SubtreeDeleteControl} permits
* whole sub-trees to be deleted using a single Delete request.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String baseDN = ...;
+ *
+ * DeleteRequest request =
+ * Requests.newDeleteRequest(baseDN)
+ * .addControl(SubtreeDeleteRequestControl.newControl(true));
+ * connection.delete(request);
+ * </pre>
*/
public interface DeleteRequest extends Request, ChangeRecord {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ExtendedRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ExtendedRequest.java
index fdb4948..369710f 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ExtendedRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ExtendedRequest.java
@@ -42,6 +42,23 @@
* operation which installs transport layer security (see
* {@link StartTLSExtendedRequest}).
*
+ * <p>
+ * To determine whether a directory server supports a given extension, read the
+ * list of supported extensions from the root DSE to get a collection of
+ * extension OIDs, and then check for a match. For example:
+ *
+ * <pre>
+ * Connection connection = ...;
+ * Collection<String> supported =
+ * RootDSE.readRootDSE(connection).getSupportedExtendedOperations();
+ *
+ * ExtendedRequest extension = ...;
+ * String OID = extension.getOID();
+ * if (supported != null && !supported.isEmpty() && supported.contains(OID)) {
+ * // The extension is supported. Use it here...
+ * }
+ * </pre>
+ *
* @param <S>
* The type of result.
*/
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ModifyRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ModifyRequest.java
index 2f8f539..10fb5cd 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ModifyRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/ModifyRequest.java
@@ -44,6 +44,18 @@
/**
* The Modify operation allows a client to request that a modification of an
* entry be performed on its behalf by a server.
+ * <p>
+ * The following example adds a member to a static group entry.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String groupDN = ...;
+ * String memberDN = ...;
+ *
+ * ModifyRequest addMember = Requests.newModifyRequest(groupDN)
+ * .addModification(ModificationType.ADD, "member", memberDN);
+ * connection.modify(addMember);
+ * </pre>
*/
public interface ModifyRequest extends Request, ChangeRecord {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PasswordModifyExtendedRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PasswordModifyExtendedRequest.java
index 7c4318f..e8194e0 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PasswordModifyExtendedRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PasswordModifyExtendedRequest.java
@@ -45,6 +45,26 @@
* addition, it includes support for requiring the user's current password as
* well as for generating a new password if none was provided.
*
+ * <pre>
+ * String userIdentity = ...; // For example, u:<uid> or dn:<DN>
+ * char[] oldPassword = ...;
+ * char[] newPassword = ...;
+ * Connection connection = ...;
+ *
+ * PasswordModifyExtendedRequest request =
+ * Requests.newPasswordModifyExtendedRequest()
+ * .setUserIdentity(userIdentity)
+ * .setOldPassword(oldPassword)
+ * .setNewPassword(newPassword);
+ *
+ * PasswordModifyExtendedResult result = connection.extendedRequest(request);
+ * if (result.isSuccess()) {
+ * // Changed password
+ * } else {
+ * // Use result to diagnose error.
+ * }
+ * </pre>
+ *
* @see PasswordModifyExtendedResult
* @see <a href="http://tools.ietf.org/html/rfc3062">RFC 3062 - LDAP Password
* Modify Extended Operation </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PlainSASLBindRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PlainSASLBindRequest.java
index 334bd36..c59c6e7 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PlainSASLBindRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/PlainSASLBindRequest.java
@@ -44,6 +44,20 @@
* The authentication and optional authorization identity is specified using an
* authorization ID, or {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
*
+ * <pre>
+ * String authcid = ...; // Authentication ID, e.g. dn:<dn>, u:<uid>
+ * String authzid = ...; // Authorization ID, e.g. dn:<dn>, u:<uid>
+ * char[] password = ...;
+ * Connection connection = ...; // Use StartTLS to protect the request
+ *
+ * PlainSASLBindRequest request =
+ * Requests.newPlainSASLBindRequest(authcid, password)
+ * .setAuthorizationID(authzid);
+ *
+ * connection.bind(request);
+ * // Authenticated if the connection succeeds
+ * </pre>
+ *
* @see <a href="http://tools.ietf.org/html/rfc4616">RFC 4616 - The PLAIN Simple
* Authentication and Security Layer (SASL) Mechanism </a>
* @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SASLBindRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SASLBindRequest.java
index 0bf01fb..b595740 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SASLBindRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SASLBindRequest.java
@@ -40,6 +40,9 @@
* 4513.
* <p>
* <TODO>finish doc.
+ *
+ * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
+ * SASL Authorization Identities (authzId) </a>
*/
public interface SASLBindRequest extends BindRequest {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SearchRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SearchRequest.java
index bf6e98b..152b4b3 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SearchRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SearchRequest.java
@@ -45,6 +45,25 @@
* criterion. This can be used to read attributes from a single entry, from
* entries immediately subordinate to a particular entry, or from a whole
* subtree of entries.
+ * <p>
+ * Use {@link Requests#newSearchRequest(DN, SearchScope, Filter, String...)} or
+ * {@link Requests#newSearchRequest(String, SearchScope, String, String...)} to
+ * create a new search request.
+ *
+ * <pre>
+ * SearchRequest request = Requests.newSearchRequest(
+ * "dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn");
+ * </pre>
+ *
+ * Alternatively, use the
+ * {@link org.forgerock.opendj.ldap.Connection#search(String, SearchScope, String, String...)
+ * Connection.search()} method to specify the arguments directly.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * ConnectionEntryReader reader = connection.search(
+ * "dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn");
+ * </pre>
*/
public interface SearchRequest extends Request {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SimpleBindRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SimpleBindRequest.java
index e86f9dc..a8695ab 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SimpleBindRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SimpleBindRequest.java
@@ -46,6 +46,26 @@
* <li>A name/password authentication mechanism using credentials consisting of
* a name and a password.
* </ul>
+ * {@link Requests} has methods to create a {@code SimpleBindRequest}.
+ *
+ * <pre>
+ * String bindDN = ...;
+ * char[] bindPassword = ...;
+ *
+ * SimpleBindRequest sbr = Requests.newSimpleBindRequest(bindDN, bindPassword);
+ * </pre>
+ *
+ * Alternatively, use
+ * {@link org.forgerock.opendj.ldap.Connection#bind(String, char[])
+ * Connection.bind}.
+ *
+ * <pre>
+ * Connection connection;
+ * String bindDN = ...;
+ * char[] bindPassword = ...;
+ *
+ * connection.bind(bindDN, bindPassword);
+ * </pre>
*/
public interface SimpleBindRequest extends BindRequest {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/StartTLSExtendedRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/StartTLSExtendedRequest.java
index 3a8b218..7410713 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/StartTLSExtendedRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/StartTLSExtendedRequest.java
@@ -43,6 +43,25 @@
* The start TLS extended request as defined in RFC 4511. The Start Transport
* Layer Security (StartTLS) operation's purpose is to initiate installation of
* a TLS layer.
+ * <p>
+ * Use an {@link org.forgerock.opendj.ldap.SSLContextBuilder SSLContextBuilder}
+ * when setting up LDAP options needed to use StartTLS.
+ * {@link org.forgerock.opendj.ldap.TrustManagers TrustManagers} has methods you
+ * can use to set the trust manager for the SSL context builder.
+ *
+ * <pre>
+ * LDAPOptions options = new LDAPOptions();
+ * SSLContext sslContext =
+ * new SSLContextBuilder().setTrustManager(...).getSSLContext();
+ * options.setSSLContext(sslContext);
+ * options.setUseStartTLS(true);
+ *
+ * String host = ...;
+ * int port = ...;
+ * LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port, options);
+ * Connection connection = factory.getConnection();
+ * // Connection uses StartTLS...
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 - Lightweight
* Directory Access Protocol (LDAP): The Protocol </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/WhoAmIExtendedRequest.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/WhoAmIExtendedRequest.java
index 626c231..1abd08a 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/WhoAmIExtendedRequest.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/WhoAmIExtendedRequest.java
@@ -41,6 +41,24 @@
* clients to obtain the primary authorization identity, in its primary form,
* that the server has associated with the user or application entity.
* <p>
+ * The following example demonstrates use of the Who Am I? request and response.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String name = ...;
+ * char[] password = ...;
+ *
+ * Result result = connection.bind(name, password);
+ * if (result.isSuccess()) {
+ * WhoAmIExtendedRequest request = Requests.newWhoAmIExtendedRequest();
+ * WhoAmIExtendedResult extResult = connection.extendedRequest(request);
+ *
+ * if (extResult.isSuccess()) {
+ * // Authz ID: " + extResult.getAuthorizationID());
+ * }
+ * }
+ * </pre>
+ *
* This operation may preferable to the Authorization Identity Controls
* mechanism defined in RFC 3829, which uses Bind request and response controls
* to request and return the authorization identity. Bind controls are not
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/CompareResult.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/CompareResult.java
index e29932a..c3503c9 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/CompareResult.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/CompareResult.java
@@ -41,6 +41,22 @@
* the attribute or sub-type according to the attribute's equality matching rule
* then the result code is set to {@link ResultCode#COMPARE_TRUE} and can be
* determined by invoking the {@link #matched} method.
+ * <p>
+ * The following excerpt shows how to use the Compare operation to check whether
+ * a member belongs to a (possibly large) static group.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String groupDN = ...;
+ * String memberDN = ...;
+ *
+ * CompareRequest request =
+ * Requests.newCompareRequest(groupDN, "member", memberDN);
+ * CompareResult result = connection.compare(request);
+ * if (result.matched()) {
+ * // The member belongs to the group.
+ * }
+ * </pre>
*/
public interface CompareResult extends Result {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/IntermediateResponse.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/IntermediateResponse.java
index fe7b4b7..476dc87 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/IntermediateResponse.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/IntermediateResponse.java
@@ -46,6 +46,9 @@
* An Intermediate response may convey an optional response name and value.
* These can be retrieved using the {@link #getOID} and {@link #getValue}
* methods respectively.
+ *
+ * @see <a href="http://tools.ietf.org/html/rfc3771">RFC 3771 - The Lightweight
+ * Directory Access Protocol (LDAP) Intermediate Response Message</a>
*/
public interface IntermediateResponse extends Response {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/WhoAmIExtendedResult.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/WhoAmIExtendedResult.java
index e3cb1cb..028f662 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/WhoAmIExtendedResult.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/responses/WhoAmIExtendedResult.java
@@ -45,6 +45,24 @@
* <p>
* The authorization identity is specified using an authorization ID, or
* {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
+ * <p>
+ * The following example demonstrates use of the Who Am I? request and response.
+ *
+ * <pre>
+ * Connection connection = ...;
+ * String name = ...;
+ * char[] password = ...;
+ *
+ * Result result = connection.bind(name, password);
+ * if (result.isSuccess()) {
+ * WhoAmIExtendedRequest request = Requests.newWhoAmIExtendedRequest();
+ * WhoAmIExtendedResult extResult = connection.extendedRequest(request);
+ *
+ * if (extResult.isSuccess()) {
+ * // Authz ID: " + extResult.getAuthorizationID());
+ * }
+ * }
+ * </pre>
*
* @see org.forgerock.opendj.ldap.requests.WhoAmIExtendedRequest
* @see org.forgerock.opendj.ldap.controls.AuthorizationIdentityRequestControl
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/AttributeUsage.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/AttributeUsage.java
index d5a1a6d..99403fe 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/AttributeUsage.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/AttributeUsage.java
@@ -29,6 +29,9 @@
/**
* This enumeration defines the set of possible attribute usage values that may
* apply to an attribute type, as defined in RFC 2252.
+ *
+ * @see <a href="http://tools.ietf.org/html/rfc2252">RFC 2252 - Lightweight
+ * Directory Access Protocol (v3): Attribute Syntax Definitions</a>
*/
public enum AttributeUsage {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/ObjectClassType.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/ObjectClassType.java
index 76f301e..d178778 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/ObjectClassType.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/schema/ObjectClassType.java
@@ -29,6 +29,9 @@
/**
* This enumeration defines the set of possible objectclass types that may be
* used, as defined in RFC 2252.
+ *
+ * @see <a href="http://tools.ietf.org/html/rfc2252">RFC 2252 - Lightweight
+ * Directory Access Protocol (v3): Attribute Syntax Definitions</a>
*/
public enum ObjectClassType {
/**
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordReader.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordReader.java
index 8f3edde..eead980 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordReader.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordReader.java
@@ -65,6 +65,25 @@
* An LDIF change record reader reads change records using the LDAP Data
* Interchange Format (LDIF) from a user defined source.
*
+ * <p>
+ * The following example reads changes from LDIF, and writes the changes to the
+ * directory server.
+ *
+ * <pre>
+ * InputStream ldif = ...;
+ * LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);
+ *
+ * Connection connection = ...;
+ * connection.bind(...);
+ *
+ * ConnectionChangeRecordWriter writer =
+ * new ConnectionChangeRecordWriter(connection);
+ * while (reader.hasNext()) {
+ * ChangeRecord changeRecord = reader.readChangeRecord();
+ * writer.writeChangeRecord(changeRecord);
+ * }
+ * </pre>
+ *
* @see <a href="http://tools.ietf.org/html/rfc2849">RFC 2849 - The LDAP Data
* Interchange Format (LDIF) - Technical Specification </a>
*/
diff --git a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordWriter.java b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordWriter.java
index 4f102fe..15387ac 100644
--- a/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordWriter.java
+++ b/opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldif/LDIFChangeRecordWriter.java
@@ -47,6 +47,24 @@
/**
* An LDIF change record writer writes change records using the LDAP Data
* Interchange Format (LDIF) to a user defined destination.
+ * <p>
+ * The following example reads changes from LDIF, and writes the changes to the
+ * directory server.
+ *
+ * <pre>
+ * InputStream ldif = ...;
+ * LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);
+ *
+ * Connection connection = ...;
+ * connection.bind(...);
+ *
+ * ConnectionChangeRecordWriter writer =
+ * new ConnectionChangeRecordWriter(connection);
+ * while (reader.hasNext()) {
+ * ChangeRecord changeRecord = reader.readChangeRecord();
+ * writer.writeChangeRecord(changeRecord);
+ * }
+ * </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc2849">RFC 2849 - The LDAP Data
* Interchange Format (LDIF) - Technical Specification </a>
diff --git a/opendj3/opendj-ldap-sdk/src/main/javadoc/overview.html b/opendj3/opendj-ldap-sdk/src/main/javadoc/overview.html
index 93c6513..69b8d30 100644
--- a/opendj3/opendj-ldap-sdk/src/main/javadoc/overview.html
+++ b/opendj3/opendj-ldap-sdk/src/main/javadoc/overview.html
@@ -6,9 +6,16 @@
LDAP Directory Services as defined in <a
href="http://tools.ietf.org/html/rfc4510">RFC 4510</a>.
<br>
- <h1>Getting started</h1>
+ For an introduction to LDAP, read the <em>OpenDJ SDK Developer's Guide</em>
+ chapter on <a
+ href="http://opendj.forgerock.org/doc/dev-guide/index.html#chap-understanding-ldap"
+ >Understanding LDAP</a>. Also see the chapter on <a
+ href="http://opendj.forgerock.org/doc/dev-guide/index.html#chap-best-practices"
+ >Best Practices For LDAP Application Developers</a>.
+ <br>
+ <h1>Getting Started</h1>
The following example shows how the OpenDJ SDK may be used to
- connect to a Directory Server, authenticate, and then perform a
+ connect to a directory server, authenticate, and then perform a
search. The search results are output as LDIF to the standard
output:
<br>
@@ -63,32 +70,32 @@
</tr>
</tbody>
</table>
+ <br><!-- It seems the .zip is not packaged with the SDK. -->
+ Additional examples can be found online at the <a
+ href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ >OpenDJ LDAP SDK Examples</a> site.
<br>
- Additional examples can be found in the file examples.zip which is
- included with this SDK.
- <br>
- <h1>Creating connections</h1>
+ <h1>Creating Connections</h1>
The following classes can be used to create and manage connections to
- LDAP Directory Servers:
+ LDAP directory servers:
<ul>
<li>{@link org.forgerock.opendj.ldap.LDAPConnectionFactory}</li>
<li>{@link org.forgerock.opendj.ldap.Connection}</li>
<li>{@link org.forgerock.opendj.ldap.Connections}</li>
</ul>
<br>
- <h1>Creating requests</h1>
+ <h1>Creating Requests</h1>
The following classes can be used to create LDAP requests:
<ul>
<li>{@link org.forgerock.opendj.ldap.requests.Requests}</li>
<li>{@link org.forgerock.opendj.ldap.requests.Request}</li>
</ul>
<br>
- <h1>Using controls</h1>
+ <h1>Using Controls</h1>
Common LDAP control implementations can be found in
{@link org.forgerock.opendj.ldap.controls}.
<br>
- <br>
- <h1>Core types</h1>
+ <h1>Core Types</h1>
The following classes and interfaces represent core types:
<ul>
<li>{@link org.forgerock.opendj.ldap.AttributeDescription}</li>
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml b/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml
index 8beb191..3425ee8 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-authenticating.xml
@@ -248,9 +248,9 @@
final LDAPConnectionFactory factory =
new LDAPConnectionFactory(host, port, getTrustAllOptions());
connection = factory.getConnection();
- PlainSASLBindRequest request = Requests.newPlainSASLBindRequest(
- authcid, passwd.toCharArray());
- if (authzid != null) request.setAuthorizationID(authzid);
+ PlainSASLBindRequest request =
+ Requests.newPlainSASLBindRequest(authcid, passwd.toCharArray())
+ .setAuthorizationID(authzid);
connection.bind(request);
System.out.println("Authenticated as " + authcid + ".");
}</programlisting>
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-writing.xml b/opendj3/src/main/docbkx/dev-guide/chap-writing.xml
index 8b6677f..7546ba9 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-writing.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-writing.xml
@@ -139,8 +139,7 @@
<literal>ou=People,dc=example,dc=com</literal>.</para>
<programlisting language="java">// An entry to add to the directory
-DN entryDN = DN.valueOf("cn=Bob,ou=People,dc=example,dc=com");
-Entry entry = new LinkedHashMapEntry(entryDN.toString())
+Entry entry = new LinkedHashMapEntry("cn=Bob,ou=People,dc=example,dc=com")
.addAttribute("cn", "Bob")
.addAttribute("objectclass", "top")
.addAttribute("objectclass", "person")
@@ -231,7 +230,7 @@
// Here, entryDN contains cn=Bob,ou=People,dc=example,dc=com.
// The second argument is the new relative distinguished name.
- connection.modifyDN(entryDN.toString(), "cn=Ted");
+ connection.modifyDN(entryDN, "cn=Ted");
} catch (final ErrorResultException e) {
System.err.println(e.getMessage());
--
Gitblit v1.10.0