Start adding content to the chapter on LDAP controls

Mark Craig

02.18.2012 19772d267299ace5f85c6fc6ae9b1edc5f6a9c60

Start adding content to the chapter on LDAP controls

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

New file
@@ -0,0 +1,164 @@
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 * or http://forgerock.org/license/CDDLv1.0.html.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at legal-notices/CDDLv1_0.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *      Copyright 2012 ForgeRock AS
 *
 */

package org.forgerock.opendj.examples;

import java.io.IOException;
import java.util.Collection;

import org.forgerock.opendj.ldap.Connection;
import org.forgerock.opendj.ldap.ErrorResultException;
import org.forgerock.opendj.ldap.Filter;
import org.forgerock.opendj.ldap.LDAPConnectionFactory;
import org.forgerock.opendj.ldap.ModificationType;
import org.forgerock.opendj.ldap.RootDSE;
import org.forgerock.opendj.ldap.controls.AssertionRequestControl;
import org.forgerock.opendj.ldap.requests.ModifyRequest;
import org.forgerock.opendj.ldap.requests.Requests;
import org.forgerock.opendj.ldif.LDIFEntryWriter;

/**
 * This command-line client demonstrates use of LDAP controls. The client takes
 * as arguments the host and port for the directory server, and expects to find
 * the entries and access control instructions as defined in <a
 * href="http://opendj.forgerock.org/Example.ldif">Example.ldif</a>.
 *
 * This client connects as <code>cn=Directory Manager</code> with password
 * <code>password</code>. Not a best practice; in real code use application
 * specific credentials to connect, and ensure that your application has access
 * to use the LDAP controls needed.
 */
public final class Controls {
    /**
     * Connect to the server, and then try to use some LDAP controls.
     *
     * @param args
     *            The command line arguments: host, port
     */
    public static void main(final String[] args) {
        if (args.length != 2) {
            System.err.println("Usage: host port");
            System.err.println("For example: localhost 1389");
            System.exit(1);
        }
        String host = args[0];
        int port = Integer.parseInt(args[1]);

        final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
        Connection connection = null;
        try {
            connection = factory.getConnection();
            checkSupportedControls(connection);

            String user = "cn=Directory Manager";
            char[] password = "password".toCharArray();
            connection.bind(user, password);

            useAssertionControl(connection);
            // TODO: The rest of the supported controls

        } catch (final ErrorResultException e) {
            System.err.println(e.getMessage());
            System.exit(e.getResult().getResultCode().intValue());
            return;
        } finally {
            if (connection != null) {
                connection.close();
            }
        }
    }

    /**
     * Use the LDAP assertion control to perform a trivial modification.
     *
     * @param connection
     *            Active connection to LDAP server containing <a
     *            href="http://opendj.forgerock.org/Example.ldif"
     *            >Example.ldif</a> content.
     */
    static void useAssertionControl(Connection connection) throws ErrorResultException {
        if (isSupported(AssertionRequestControl.OID)) {
            // Modify Babs Jensen's description if her entry does not have
            // a description, yet.
            String dn = "uid=bjensen,ou=People,dc=example,dc=com";

            ModifyRequest request = Requests.newModifyRequest(dn);
            request.addControl(AssertionRequestControl.newControl(true,
                    Filter.valueOf("!(description=*)")));
            request.addModification(ModificationType.ADD, "description",
                    "Created with the help of the LDAP assertion control");

            connection.modify(request);

            LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
            try {
                writer.writeEntry(connection.readEntry(dn, "description"));
                writer.close();
            } catch (final IOException e) {
                // Ignore.
            }
        }
    }

    /**
     * Controls supported by the LDAP server.
     */
    private static Collection<String> controls;

    /**
     * Populate the list of supported LDAP control OIDs.
     *
     * @param connection
     *            Active connection to the LDAP server.
     * @throws ErrorResultException
     */
    static void checkSupportedControls(Connection connection) throws ErrorResultException {
        RootDSE dse = RootDSE.readRootDSE(connection);
        controls = dse.getSupportedControls();
    }

    /**
     * Check whether a control is supported. Call {@code checkSupportedControls}
     * first.
     *
     * @param control
     *            Check support for this control, provided by OID.
     * @return True if the control is supported.
     */
    static boolean isSupported(String control) {
        if (controls != null && !controls.isEmpty()) {
            return controls.contains(control);
        }
        return false;
    }

    /**
     * Constructor not used.
     */
    private Controls() {
        // Not used.
    }
}

 opendj3/opendj-ldap-sdk-examples/src/site/xdoc/index.xml.vm

@@ -81,6 +81,10 @@
          <a href="xref/org/forgerock/opendj/examples/ShortLife.html">Short life</a>
          - illustrates how to create, update, rename, and delete an entry
        </li>
        <li>
          <a href="xref/org/forgerock/opendj/examples/Controls.html">Use LDAP Controls</a>
          - illustrates how to use supported LDAP controls
        </li>
      </ul>
    </section>
    <section name="Get the OpenDJ LDAP SDK Examples">

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

@@ -114,7 +114,37 @@
 
 <section xml:id="use-assertion-request-control">
  <title>Assertion Request Control</title>
  <para>TODO</para>

  <para>The <link xlink:href="http://tools.ietf.org/html/rfc4528"
  xlink:show="new" >LDAP assertion control</link> lets you specify a condition
  that must be true in order for the operation you request to be processed
  normally. The following excerpt shows, for example, how you might check
  that no description exists on the entry before adding your description.</para>

  <programlisting language="java">
if (isSupported(AssertionRequestControl.OID)) {
    // Modify Babs Jensen's description if her entry does not have
    // a description, yet.
    String dn = "uid=bjensen,ou=People,dc=example,dc=com";

    ModifyRequest request = Requests.newModifyRequest(dn);
    request.addControl(AssertionRequestControl.newControl(true,
            Filter.valueOf("!(description=*)")));
    request.addModification(ModificationType.ADD, "description",
            "Created with the help of the LDAP assertion control");

    connection.modify(request);

    LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
    try {
        writer.writeEntry(connection.readEntry(dn, "description"));
        writer.close();
    } catch (final IOException e) {
        // Ignore.
    }
}</programlisting>

  <para>OpenDJ directory server supports the LDAP assertion control.</para>
 </section>
 
 <section xml:id="use-authorization-identity-control">