com.afrigis.services.Response Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of core Show documentation
Core Java library to ease use of AfriGIS Services
There is a newer version: 3.0.2
package com.afrigis.services;

import java.io.InputStream;
import java.util.List;

import com.afrigis.services.internal.saas.api2.impl.ParsedErrorData;

/**
 * 
 * Main interface for objects that act as response handlers.
 * 
 * 
 * @author hendrikc
 *
 */
public interface Response {

    /**
     * 
     * Returns a copy of the entire raw byte stream as received from the server.
     * 
     * 
     * @return a copy of the entire raw byte stream as received from the server 
     */
    byte[] getByteArray();

    /**
     * 
     * A list of deserialized objects based on the results obtained from the
     * service.
     * 
     * 
     * @param 
     *            the type of the parsed objects returned in the list
     * @return a list of objects of type T, deserialized from the service
     *         response
     */
     List listResults();

    /**
     * 
     * Used when re-trying requests under certain conditions.
     * 
     * TODO WHY is this in the response objects? Why not {@link Request}?
     * 
     * @param i
     *            the number of times called
     */
    void setTimesCalled(int i);

    /**
     * 
     * If the server responded with something that looks like an error, this method will receive the {@link ParsedErrorData}.
     * 
     * @param ped the processed error data
     */
    void setError(ParsedErrorData ped);

    /**
     * 
     * Used when we have to retry requests under certain conditions.
     * 
     * TODO WHY is this in the response objects? Why not {@link Request}?
     * 
     * @return the number of times the request has been called
     */
    int getTimesCalled();

    /**
     * 
     * Receives the input stream from the server, and is responsible for copying
     * data into local memory, checking for error conditions and so forth.
     * 
     * 
     * After calling this method, clients should be able to rely on the
     * following post conditions:
     * 
     * 
     * {@link #getByteArray()} should return non-empty, non-null array
     * {@link #getError()} will return NULL only if no errror condition was
     * detected in the response (NOT only based on the HTTP status line code)
     * 
     * 
     * 
     * @param fin
     *            input stream to read from
     * @param statusCode
     *            the HTTP Status code as received
     */
    void consume(InputStream fin, int statusCode);

    /**
     * 
     * If things have gone wrong is an understandable way, this field will be
     * populated.
     * 
     * 
     * @return information about the error encountered.
     * @see ParsedErrorData
     */
    ParsedErrorData getError();

    /**
     * 
     * Called to finalize the parsing of the response and so forth.
     * 
     */
    void completeBuild();
}