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<String> 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}