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 * Portions copyright 2012-2015 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.opendj.ldap.ByteString;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.controls.Control;
026import org.forgerock.opendj.ldap.controls.ControlDecoder;
027import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
028import org.forgerock.opendj.ldap.responses.GenericExtendedResult;
029
030/**
031 * A generic Extended request which should be used for unsupported extended
032 * operations. Servers list the names of Extended requests they recognize in the
033 * {@code supportedExtension} attribute in the root DSE. Where the name is not
034 * recognized, the server returns
035 * {@link org.forgerock.opendj.ldap.ResultCode#PROTOCOL_ERROR} (the server may
036 * return this error in other cases).
037 */
038public interface GenericExtendedRequest extends ExtendedRequest<GenericExtendedResult> {
039    /**
040     * A decoder which can be used to decode generic extended operation
041     * requests.
042     */
043    ExtendedRequestDecoder<GenericExtendedRequest, GenericExtendedResult> DECODER =
044            new GenericExtendedRequestImpl.RequestDecoder();
045
046    @Override
047    GenericExtendedRequest addControl(Control control);
048
049    @Override
050    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
051            throws DecodeException;
052
053    @Override
054    List<Control> getControls();
055
056    @Override
057    String getOID();
058
059    @Override
060    ExtendedResultDecoder<GenericExtendedResult> getResultDecoder();
061
062    @Override
063    ByteString getValue();
064
065    @Override
066    boolean hasValue();
067
068    /**
069     * Sets the numeric OID associated with this extended request.
070     *
071     * @param oid
072     *            The numeric OID associated with this extended request.
073     * @return This generic extended request.
074     * @throws UnsupportedOperationException
075     *             If this generic extended request does not permit the request
076     *             name to be set.
077     * @throws NullPointerException
078     *             If {@code oid} was {@code null}.
079     */
080    GenericExtendedRequest setOID(String oid);
081
082    /**
083     * Sets the value, if any, associated with this extended request. Its format
084     * is defined by the specification of this extended request.
085     * <p>
086     * If {@code value} is not an instance of {@code ByteString} then it will be
087     * converted using the {@link ByteString#valueOfObject(Object)} method.
088     *
089     * @param value
090     *            TThe value associated with this extended request, or
091     *            {@code null} if there is no value. Its format is defined by
092     *            the specification of this control.
093     * @return This generic extended request.
094     * @throws UnsupportedOperationException
095     *             If this generic extended request does not permit the request
096     *             value to be set.
097     */
098    GenericExtendedRequest setValue(Object value);
099}