001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 *      Portions copyright 2012 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031
032import org.forgerock.opendj.ldap.ByteString;
033import org.forgerock.opendj.ldap.DecodeException;
034import org.forgerock.opendj.ldap.DecodeOptions;
035import org.forgerock.opendj.ldap.controls.Control;
036import org.forgerock.opendj.ldap.controls.ControlDecoder;
037import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
038import org.forgerock.opendj.ldap.responses.GenericExtendedResult;
039
040/**
041 * A generic Extended request which should be used for unsupported extended
042 * operations. Servers list the names of Extended requests they recognize in the
043 * {@code supportedExtension} attribute in the root DSE. Where the name is not
044 * recognized, the server returns
045 * {@link org.forgerock.opendj.ldap.ResultCode#PROTOCOL_ERROR} (the server may
046 * return this error in other cases).
047 */
048public interface GenericExtendedRequest extends ExtendedRequest<GenericExtendedResult> {
049    /**
050     * A decoder which can be used to decode generic extended operation
051     * requests.
052     */
053    ExtendedRequestDecoder<GenericExtendedRequest, GenericExtendedResult> DECODER =
054            new GenericExtendedRequestImpl.RequestDecoder();
055
056    @Override
057    GenericExtendedRequest 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    @Override
067    String getOID();
068
069    @Override
070    ExtendedResultDecoder<GenericExtendedResult> getResultDecoder();
071
072    @Override
073    ByteString getValue();
074
075    @Override
076    boolean hasValue();
077
078    /**
079     * Sets the numeric OID associated with this extended request.
080     *
081     * @param oid
082     *            The numeric OID associated with this extended request.
083     * @return This generic extended request.
084     * @throws UnsupportedOperationException
085     *             If this generic extended request does not permit the request
086     *             name to be set.
087     * @throws NullPointerException
088     *             If {@code oid} was {@code null}.
089     */
090    GenericExtendedRequest setOID(String oid);
091
092    /**
093     * Sets the value, if any, associated with this extended request. Its format
094     * is defined by the specification of this extended request.
095     * <p>
096     * If {@code value} is not an instance of {@code ByteString} then it will be
097     * converted using the {@link ByteString#valueOf(Object)} method.
098     *
099     * @param value
100     *            TThe value associated with this extended request, or
101     *            {@code null} if there is no value. Its format is defined by
102     *            the specification of this control.
103     * @return This generic extended request.
104     * @throws UnsupportedOperationException
105     *             If this generic extended request does not permit the request
106     *             value to be set.
107     */
108    GenericExtendedRequest setValue(Object value);
109}