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