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