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}