Yet a bit more for the LDAP controls chapter

Mark Craig

03.04.2012 d90325658a4a301663616d4c5513dd52f61e1c03

Yet a bit more for the LDAP controls chapter

 opendj3/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples/Controls.java

@@ -45,6 +45,7 @@
import org.forgerock.opendj.ldap.controls.AuthorizationIdentityResponseControl;
import org.forgerock.opendj.ldap.controls.EntryChangeNotificationResponseControl;
import org.forgerock.opendj.ldap.controls.GetEffectiveRightsRequestControl;
import org.forgerock.opendj.ldap.controls.ManageDsaITRequestControl;
import org.forgerock.opendj.ldap.controls.PersistentSearchChangeType;
import org.forgerock.opendj.ldap.controls.PersistentSearchRequestControl;
import org.forgerock.opendj.ldap.requests.BindRequest;
@@ -53,6 +54,7 @@
import org.forgerock.opendj.ldap.requests.SearchRequest;
import org.forgerock.opendj.ldap.responses.BindResult;
import org.forgerock.opendj.ldap.responses.SearchResultEntry;
import org.forgerock.opendj.ldap.responses.SearchResultReference;
import org.forgerock.opendj.ldif.ConnectionEntryReader;
import org.forgerock.opendj.ldif.LDIFEntryWriter;

@@ -97,11 +99,12 @@
            // Uncomment one of the methods:

            //useAssertionControl(connection);
            useAuthorizationIdentityRequestControl(connection);
            //useAuthorizationIdentityRequestControl(connection);
            // For the EntryChangeNotificationResponseControl see
            // usePersistentSearchRequestControl()
            //useGetEffectiveRightsRequestControl(connection);
            //usePersistentSearchRequestControl(connection);
            useManageDsaITRequestControl(connection);
            // TODO: The rest of the supported controls

        } catch (final ErrorResultException e) {
@@ -225,6 +228,49 @@
    }

    /**
     * Use the ManageDsaIT Request Control to show the difference between a
     * referral accessed with and without use of the control.
     *
     * @param connection
     *            Active connection to LDAP server containing <a
     *            href="http://opendj.forgerock.org/Example.ldif"
     *            >Example.ldif</a> content.
     * @throws ErrorResultException
     *             Operation failed.
     */
    static void useManageDsaITRequestControl(Connection connection) throws ErrorResultException {
        if (isSupported(ManageDsaITRequestControl.OID)) {
            // This entry is a referral object:
            final String dn = "dc=references,dc=example,dc=com";

            final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
            try {
                System.out.println("Referral without the ManageDsaIT control.");
                SearchRequest request = Requests.newSearchRequest(dn,
                        SearchScope.BASE_OBJECT, "(objectclass=*)", "");
                final ConnectionEntryReader reader = connection.search(request);
                while (reader.hasNext()) {
                    if (reader.isReference()) {
                        final SearchResultReference ref = reader.readReference();
                        System.out.println("Reference: " + ref.getURIs().toString());
                    }
                }

                System.out.println("Referral with the ManageDsaIT control.");
                request.addControl(ManageDsaITRequestControl.newControl(true));
                final SearchResultEntry entry = connection.searchSingleEntry(request);
                writer.writeEntry(entry);
                writer.close();
            } catch (final ErrorResultIOException e) {
                e.printStackTrace();
            } catch (final SearchResultReferenceIOException e) {
                e.printStackTrace();
            } catch (final IOException e) {
                e.printStackTrace();
            }
        }
    }
    /**
     * Use the LDAP PersistentSearchRequestControl to set up a persistent
     * search. Also use the Entry Change Notification Response Control to get
     * details about why an entry was returned for a persistent search.

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

@@ -372,9 +372,50 @@
</programlisting>
 </section>
 
 <section xml:id="use-manage-dsait-control-control">
  <title>Manage DSAIT Request Control</title>
  <para>TODO</para>
 <section xml:id="use-managedsait-control">
  <title>ManageDsaIT Request Control</title>

  <para>The ManageDsaIT control, described in <link xlink:show="new"
  xlink:href="http://tools.ietf.org/html/rfc3296">RFC 3296, <citetitle>Named
  Subordinate References in LDAP Directories</citetitle></link>, lets your
  application handle references and other special entries as normal entries.
  Use it when you want to read from or write to reference or special
  entry.</para>

  <programlisting language="java">
if (isSupported(ManageDsaITRequestControl.OID)) {
    // This entry is a referral object:
    final String dn = "dc=references,dc=example,dc=com";

    final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        System.out.println("Referral without the ManageDsaIT control.");
        SearchRequest request = Requests.newSearchRequest(dn,
                SearchScope.BASE_OBJECT, "(objectclass=*)", "");
        final ConnectionEntryReader reader = connection.search(request);
        while (reader.hasNext()) {
            if (reader.isReference()) {
                final SearchResultReference ref = reader.readReference();
                System.out.println("Reference: " + ref.getURIs().toString());
            }
        }

        System.out.println("Referral with the ManageDsaIT control.");
        request.addControl(ManageDsaITRequestControl.newControl(true));
        final SearchResultEntry entry = connection.searchSingleEntry(request);
        writer.writeEntry(entry)
        writer.close();
    } catch (final ErrorResultIOException e) {
        e.printStackTrace();
    } catch (final SearchResultReferenceIOException e) {
        e.printStackTrace();
    } catch (final IOException e) {
        e.printStackTrace();
    }
}
</programlisting>

  <para>OpenDJ directory server supports the ManageDsaIT Request Control.</para>
 </section>
 
 <section xml:id="use-matched-values-request-control">

 opendj3/src/site/resources/Example.ldif

@@ -3749,3 +3749,10 @@
description: Special Administrative Accounts
ou: Special Users

dn: dc=references,dc=example,dc=com
dc: references
objectClass: extensibleObject
objectClass: referral
objectClass: top
ref: ldap:///ou=People,dc=example,dc=com