com.afrigis.services.Request 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.util.Collection;

import com.afrigis.services.exceptions.AfriGISServicesException;

/**
 * 
 * Interface for object acting as request object to {@link Service} objects.
 * 
 * @author hendrikc
 * @see com.afrigis.services.impl.GenericRequest
 * @see Service
 */
public interface Request {
    /**
     * 
     * Returns the current request parameters as a {@link Collection}. Note this should
     * NOT return a copy of the underlying data structure.
     * 
     * @return the current request parameters
     */
    Collection getRequestParameters();

    /**
     * 
     * Builds up a query parameter string (properly URL encoded).
     * 
     * 
     * THIS IS NOT HTTP QUERY PARAMATERS.
     * 
     * 
     * Well, it IS, BUT these parameters are very very specific to the service
     * sitting behind the SaaS wall.
     * 
     * 
     * @return a string that can (and should) be used as a query parameter
     *         string in a HTTP URL. All keys and values will be properly URL
     *         encoded
     */
    String toQueryString();

    /**
     * 
     * Provides the name of the service this request is accessing.
     * 
     * @return the name of the requested service
     * 
     */
    String getServiceName();

    /**
     * 
     * Validates the provided parameters.
     * 
     * 
     * @throws AfriGISServicesException
     *             if not all required parameters have been supplied, or if
     *             something is picked up as invalid
     */
    void validate() throws AfriGISServicesException;
    
    /**
     * 
     * Must supply the class of a {@link Response} implementation. The implementing class must
     * supply a null constructor.
     * 
     * 
     * Because of type erasure, we can not programmatically determine declared types at runtime.
     *  
     * 
     * For easy of use, we want ONE {@link ServiceCallFactory} at run time to handle multiple
     * types of requests and responses.
     * 
     * 
     * For alignment with .Net implementation, we can't supply the Response object via argument list to 
     * the {@link ServiceCallFactory}. 
     * 
     * 
     * Which brings us to this work-a-round.
     * 
     * @return the class of the {@link Response} subclass associated with this request
     */
    Class getResponseType ();

    /**
     * 
     * Allows overriding of the reported library mode.
     * 
     * 
     * Primarily provided for internal purposes.
     * 
     * @param libMode the lib mode supposed to be reported
     * @see LibMode
     */
    void setLibMode(LibMode libMode);

    /**
     * 
     * Retrieves the library mode that will be reported. Default is {@link LibMode#sync}
     * 
     * @return the lib mode that should be reported. Defaults to {@link LibMode#sync}
     */
    LibMode getLibMode();
    
    /**
     * 
     * Allows user to provide additional parameters to the service request that might
     * not be catered for via programmatic API.
     * 
     * 
     * @param extraParam the list of additional parameters. The list contents is copied into internal data structure. 
     */
    void setExtraParameters (Collection extraParam);

    /**
     * 
     * Usefull when the library is being used as a pass-through between server and browser-based clients, where
     * JSONP techniques are required.
     * 
     * 
     * Essentially this will request the server to wrap the JSON response in a javascript function as required by JSONP.
     * 
     * @param callBack the javascript function to be pre-pended to the JSON response.
     */
    void setCallBack(String callBack);

    /**
     * 
     * Request the server to format the json response.
     * 
     *  
     * @param indent true if the json response should be formatted. 
     */
    void setIndent(boolean indent);
}