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 2009 Sun Microsystems, Inc.
015 */
016
017package org.forgerock.opendj.ldap.requests;
018
019import java.util.List;
020
021import org.forgerock.opendj.ldap.ByteString;
022import org.forgerock.opendj.ldap.DecodeException;
023import org.forgerock.opendj.ldap.DecodeOptions;
024import org.forgerock.opendj.ldap.controls.Control;
025import org.forgerock.opendj.ldap.controls.ControlDecoder;
026import org.forgerock.opendj.ldap.responses.ExtendedResult;
027import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
028
029/**
030 * The Extended operation allows additional operations to be defined for
031 * services not already available in the protocol; for example, to implement an
032 * operation which installs transport layer security (see
033 * {@link StartTLSExtendedRequest}).
034 * <p>
035 * To determine whether a directory server supports a given extension, read the
036 * list of supported extensions from the root DSE to get a collection of
037 * extension OIDs, and then check for a match. For example:
038 *
039 * <pre>
040 * Connection connection = ...;
041 * Collection&lt;String&gt; supported =
042 *     RootDSE.readRootDSE(connection).getSupportedExtendedOperations();
043 *
044 * ExtendedRequest extension = ...;
045 * String OID = extension.getOID();
046 * if (supported != null && !supported.isEmpty() && supported.contains(OID)) {
047 *     // The extension is supported. Use it here...
048 * }
049 * </pre>
050 *
051 * @param <S>
052 *            The type of result.
053 */
054public interface ExtendedRequest<S extends ExtendedResult> extends Request {
055
056    @Override
057    ExtendedRequest<S> addControl(Control control);
058
059    @Override
060    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
061            throws DecodeException;
062
063    @Override
064    List<Control> getControls();
065
066    /**
067     * Returns the numeric OID associated with this extended request.
068     *
069     * @return The numeric OID associated with this extended request.
070     */
071    String getOID();
072
073    /**
074     * Returns a decoder which can be used to decoded responses to this extended
075     * request.
076     *
077     * @return A decoder which can be used to decoded responses to this extended
078     *         request.
079     */
080    ExtendedResultDecoder<S> getResultDecoder();
081
082    /**
083     * Returns the value, if any, associated with this extended request. Its
084     * format is defined by the specification of this extended request.
085     *
086     * @return The value associated with this extended request, or {@code null}
087     *         if there is no value.
088     */
089    ByteString getValue();
090
091    /**
092     * Returns {@code true} if this extended request has a value. In some
093     * circumstances it may be useful to determine if a extended request has a
094     * value, without actually calculating the value and incurring any
095     * performance costs.
096     *
097     * @return {@code true} if this extended request has a value, or
098     *         {@code false} if there is no value.
099     */
100    boolean hasValue();
101
102}