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.responses;
019
020import org.forgerock.opendj.ldap.DecodeException;
021import org.forgerock.opendj.ldap.DecodeOptions;
022import org.forgerock.opendj.ldap.ResultCode;
023import org.forgerock.opendj.ldap.LdapResultHandler;
024import org.forgerock.opendj.ldap.requests.ExtendedRequest;
025
026/**
027 * A factory interface for decoding a generic extended result as an extended
028 * result of specific type.
029 *
030 * @param <S>
031 *            The type of result.
032 */
033public interface ExtendedResultDecoder<S extends ExtendedResult> {
034
035    /**
036     * Creates a new extended operation error result using the provided decoding
037     * exception. This method should be used to adapt {@code DecodeException}
038     * encountered while decoding an extended request or result. The returned
039     * error result will have the result code {@link ResultCode#PROTOCOL_ERROR}.
040     *
041     * @param exception
042     *            The decoding exception to be adapted.
043     * @return An extended operation error result representing the decoding
044     *         exception.
045     * @throws NullPointerException
046     *             If {@code exception} was {@code null}.
047     */
048    S adaptDecodeException(DecodeException exception);
049
050    /**
051     * Adapts the provided extended result handler into a result handler which
052     * is compatible with this extended result decoder. Extended results handled
053     * by the returned handler will be automatically converted and passed to the
054     * provided result handler. Decoding errors encountered while decoding the
055     * extended result will be converted into protocol errors.
056     *
057     * @param <R>
058     *            The type of result handler to be adapted.
059     * @param request
060     *            The extended request whose result handler is to be adapted.
061     * @param resultHandler
062     *            The extended result handler which is to be adapted.
063     * @param options
064     *            The set of decode options which should be used when decoding
065     *            the extended operation result.
066     * @return A result handler which is compatible with this extended result
067     *         decoder.
068     */
069    <R extends ExtendedResult> LdapResultHandler<S> adaptExtendedResultHandler(
070            ExtendedRequest<R> request, LdapResultHandler<? super R> resultHandler, DecodeOptions options);
071
072    /**
073     * Decodes the provided extended operation result as a {@code Result} of
074     * type {@code S}. This method is called when an extended result is received
075     * from the server. The result may indicate success or failure of the
076     * extended request.
077     *
078     * @param result
079     *            The extended operation result to be decoded.
080     * @param options
081     *            The set of decode options which should be used when decoding
082     *            the extended operation result.
083     * @return The decoded extended operation result.
084     * @throws DecodeException
085     *             If the provided extended operation result could not be
086     *             decoded. For example, if the request name was wrong, or if
087     *             the request value was invalid.
088     */
089    S decodeExtendedResult(ExtendedResult result, DecodeOptions options) throws DecodeException;
090
091    /**
092     * Creates a new extended error result using the provided result code,
093     * matched DN, and diagnostic message. This method is called when a generic
094     * failure occurs, such as a connection failure, and the error result needs
095     * to be converted to a {@code Result} of type {@code S}.
096     *
097     * @param resultCode
098     *            The result code.
099     * @param matchedDN
100     *            The matched DN, which may be empty if none was provided.
101     * @param diagnosticMessage
102     *            The diagnostic message, which may be empty if none was
103     *            provided.
104     * @return The decoded extended operation error result.
105     * @throws NullPointerException
106     *             If {@code resultCode}, {@code matchedDN}, or
107     *             {@code diagnosticMessage} were {@code null}.
108     */
109    S newExtendedErrorResult(ResultCode resultCode, String matchedDN, String diagnosticMessage);
110
111}