com.microsoft.rest.protocol.ResponseBuilder Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of client-runtime Show documentation
This package contains the basic runtime for AutoRest generated Java clients.
There is a newer version: 1.7.14
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See License.txt in the project root for
 * license information.
 */

package com.microsoft.rest.protocol;

import com.microsoft.rest.RestException;
import com.microsoft.rest.ServiceResponse;
import com.microsoft.rest.ServiceResponseWithHeaders;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.lang.reflect.Type;

/**
 * Defines an interface that can process a Retrofit 2 response
 * into a deserialized body or an exception, depending on the
 * status code registered.
 *
 * @param  the body type if the status code is considered successful
 * @param  the exception type if the status code is considered a failure
 */
public interface ResponseBuilder {
    /**
     * Register a mapping from a response status code to a response destination type.
     *
     * @param statusCode the status code.
     * @param type the type to deserialize.
     * @return the same builder instance.
     */
    ResponseBuilder register(int statusCode, final Type type);

    /**
     * Register a destination type for errors with models.
     *
     * @param type the type to deserialize.
     * @return the same builder instance.
     */
    ResponseBuilder registerError(final Class type);

    /**
     * Build a ServiceResponse instance from a REST call response and a
     * possible error.
     *
     * 
     *     If the status code in the response is registered, the response will
     *     be considered valid and deserialized into the specified destination
     *     type. If the status code is not registered, the response will be
     *     considered invalid and deserialized into the specified error type if
     *     there is one. An AutoRestException is also thrown.
     * 
     *
     * @param response the {@link Response} instance from REST call
     * @return a ServiceResponse instance of generic type {@link T}
     * @throws E exceptions from the REST call
     * @throws IOException exceptions from deserialization
     */
    ServiceResponse build(Response response) throws IOException;

    /**
     * Build a ServiceResponse instance from a REST call response and a
     * possible error, which does not have a response body.
     *
     * 
     *     If the status code in the response is registered, the response will
     *     be considered valid. If the status code is not registered, the
     *     response will be considered invalid. An AutoRestException is also thrown.
     * 
     *
     * @param response the {@link Response} instance from REST call
     * @return a ServiceResponse instance of generic type {@link T}
     * @throws E exceptions from the REST call
     * @throws IOException exceptions from deserialization
     */
    ServiceResponse buildEmpty(Response response) throws IOException;

    /**
     * Build a ServiceResponseWithHeaders instance from a REST call response, a header
     * in JSON format, and a possible error.
     *
     * 
     *     If the status code in the response is registered, the response will
     *     be considered valid and deserialized into the specified destination
     *     type. If the status code is not registered, the response will be
     *     considered invalid and deserialized into the specified error type if
     *     there is one. An AutoRestException is also thrown.
     * 
     *
     * @param response the {@link Response} instance from REST call
     * @param headerType the type of the header
     * @param  the type of the header
     * @return a ServiceResponseWithHeaders instance of generic type {@link T}
     * @throws E exceptions from the REST call
     * @throws IOException exceptions from deserialization
     */
     ServiceResponseWithHeaders buildWithHeaders(Response response, Class headerType) throws IOException;

    /**
     * Build a ServiceResponseWithHeaders instance from a REST call response, a header
     * in JSON format, and a possible error, which does not have a response body.
     *
     * 
     *     If the status code in the response is registered, the response will
     *     be considered valid. If the status code is not registered, the
     *     response will be considered invalid. An AutoRestException is also thrown.
     * 
     *
     * @param response the {@link Response} instance from REST call
     * @param headerType the type of the header
     * @param  the type of the header
     * @return a ServiceResponseWithHeaders instance of generic type {@link T}
     * @throws E exceptions from the REST call
     * @throws IOException exceptions from deserialization
     */
     ServiceResponseWithHeaders buildEmptyWithHeaders(Response response, Class headerType) throws IOException;

    /**
     * A factory that creates a builder based on the return type and the exception type.
     */
    interface Factory {
        /**
         * Returns a response builder instance. This can be created new or cached.
         *
         * @param  the type of the return object
         * @param  the type of the exception
         * @param serializerAdapter the serializer adapter to deserialize the response
         * @return a response builder instance
         */
         ResponseBuilder newInstance(final SerializerAdapter serializerAdapter);
    }
}