001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2010 Sun Microsystems, Inc.
015 */
016package org.forgerock.opendj.ldap.controls;
017
018import org.forgerock.opendj.ldap.ByteString;
019
020/**
021 * Controls provide a mechanism whereby the semantics and arguments of existing
022 * LDAP operations may be extended. One or more controls may be attached to a
023 * single LDAP message. A control only affects the semantics of the message it
024 * is attached to. Controls sent by clients are termed 'request controls', and
025 * those sent by servers are termed 'response controls'.
026 * <p>
027 * To determine whether a directory server supports a given control, read the
028 * list of supported controls from the root DSE to get a collection of control
029 * OIDs, and then check for a match:
030 *
031 * <pre>
032 * Connection connection = ...;
033 * Collection&lt;String&gt; supported =
034 *     RootDSE.readRootDSE(connection).getSupportedControls();
035 *
036 * Control control = ...;
037 * String OID = control.getOID();
038 * if (supported != null && !supported.isEmpty() && supported.contains(OID)) {
039 *     // The control is supported. Use it here...
040 * }
041 * </pre>
042 *
043 * @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 - Lightweight
044 *      Directory Access Protocol (LDAP): The Protocol </a>
045 */
046public interface Control {
047
048    /**
049     * Returns the numeric OID associated with this control.
050     *
051     * @return The numeric OID associated with this control.
052     */
053    String getOID();
054
055    /**
056     * Returns the value, if any, associated with this control. Its format is
057     * defined by the specification of this control.
058     *
059     * @return The value associated with this control, or {@code null} if there
060     *         is no value.
061     */
062    ByteString getValue();
063
064    /**
065     * Returns {@code true} if this control has a value. In some circumstances
066     * it may be useful to determine if a control has a value, without actually
067     * calculating the value and incurring any performance costs.
068     *
069     * @return {@code true} if this control has a value, or {@code false} if
070     *         there is no value.
071     */
072    boolean hasValue();
073
074    /**
075     * Returns {@code true} if it is unacceptable to perform the operation
076     * without applying the semantics of this control.
077     * <p>
078     * The criticality field only has meaning in controls attached to request
079     * messages (except UnbindRequest). For controls attached to response
080     * messages and the UnbindRequest, the criticality field SHOULD be
081     * {@code false}, and MUST be ignored by the receiving protocol peer. A
082     * value of {@code true} indicates that it is unacceptable to perform the
083     * operation without applying the semantics of the control.
084     *
085     * @return {@code true} if this control must be processed by the Directory
086     *         Server, or {@code false} if it can be ignored.
087     */
088    boolean isCritical();
089
090}