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 * Portions copyright 2012 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.ExtendedResult;
028import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
029
030/**
031 * The cancel extended request as defined in RFC 3909. This operation is similar
032 * to the abandon operation, except that it has a response and also requires the
033 * abandoned operation to return a response indicating it was canceled. This
034 * operation should be used instead of the abandon operation when the client
035 * needs an indication of the outcome. This operation may be used to cancel both
036 * interrogation and update operations.
037 *
038 * @see <a href="http://tools.ietf.org/html/rfc3909">RFC 3909 - Lightweight
039 *      Directory Access Protocol (LDAP) Cancel Operation </a>
040 */
041public interface CancelExtendedRequest extends ExtendedRequest<ExtendedResult> {
042
043    /**
044     * A decoder which can be used to decode cancel extended operation requests.
045     */
046    ExtendedRequestDecoder<CancelExtendedRequest, ExtendedResult> DECODER =
047            new CancelExtendedRequestImpl.RequestDecoder();
048
049    /**
050     * The OID for the cancel extended operation request.
051     */
052    String OID = "1.3.6.1.1.8";
053
054    @Override
055    CancelExtendedRequest addControl(Control control);
056
057    @Override
058    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
059            throws DecodeException;
060
061    @Override
062    List<Control> getControls();
063
064    @Override
065    String getOID();
066
067    /**
068     * Returns the request ID of the request to be abandoned.
069     *
070     * @return The request ID of the request to be abandoned.
071     */
072    int getRequestID();
073
074    @Override
075    ExtendedResultDecoder<ExtendedResult> getResultDecoder();
076
077    @Override
078    ByteString getValue();
079
080    @Override
081    boolean hasValue();
082
083    /**
084     * Sets the request ID of the request to be abandoned.
085     *
086     * @param id
087     *            The request ID of the request to be abandoned.
088     * @return This abandon request.
089     * @throws UnsupportedOperationException
090     *             If this abandon request does not permit the request ID to be
091     *             set.
092     */
093    CancelExtendedRequest setRequestID(int id);
094}