com.afrigis.services.Service 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.concurrent.Future;

import com.afrigis.services.exceptions.AfriGISServicesException;

/**
 * 
 * Main Interface for things that want to act as "Service clients".
 *  
 * 
 * @author hendrikc
 *
 */
public interface Service {
        
    /**
     * 
     * Blocking (synchronous) call to fetch deserialized object.
     * 
     * @param  the specific {@link Response} type this method will return
     * @param params the request parameters
     * @return a deserialized response object
     * @throws AfriGISServicesException if problems are encountered, this is thrown
     * @see Request
     * @see com.afrigis.services.impl.GenericRequest#build(String, java.util.Collection)
     */
     T get(Request params) throws AfriGISServicesException;
    
    /**
     * 
     * 
     * Blocking (synchronous) call to fetch server response as a UTF-8 encoded string.
     * 
     * 
     * @param params the request parameters
     * @return the response as a string (as received from server)
     * @see #get(Request)
     */
    String getString (Request params);
    
    /**
     * 
     * Fetches server response as a UTF-8 encoded String
     * 
     * 
     * Fair warning: there are many ways you can damage yourself with this.
     * I urge you to rather look at {@link #getString(Request)}
     * 
     * @param serviceName the name of the target service
     * @param queryParameters the HTTP Query parameters string
     * @return the Server response as received from the server
     * @see Query String
     */
    String getString (String serviceName, String queryParameters);
    
    /**
     * 
     * Returns a copy of the bytes received from the server.
     * 
     * @param params the request parameters
     * @return a copy of the byte array as received from the server
     */
    byte[] getByteArray (Request params);
        
    /**
     * 
     * Asynchronously executes the request against the server.
     * 
     * @param  the specific type of the {@link Response} object
     * @param params the request parameters
     * @return parsed response object, wrapped in a {@link Future} promise
     */
     Future  getAsync(Request params);
    
    /**
     * 
     * Same function as {@link #getAsync(Request)}, but returns the response as a {@link String}.
     * 
     * @param req  the request parameters 
     * @return the server response as a {@link String}, wrapped ina {@link Future} promise
     */
    Future getStringAsync(Request req);
    
    /**
     * 
     * Same function as {@link #getAsync(Request)}, but returns the response as a byte array.
     * 
     * @param req the request parameters 
     * @return bytes received from the server, wrapped in a Fu
     */
    Future getByteArrayAsync(Request req);
    
    /**
     * 
     * Produces a valid URL that can be used by external tools/code - for a limited time (server configured).
     * 
     * @param params the request parameters
     * @return a valid URL 
     */
    String buildUrl (Request params);

    /**
     * 
     * Used by implementors.
     * 
     * 
     * Should check if the implementing class is willing/able to handle the {@link Request} type.
     * 
     * @param requestType the type of the request
     * @return true if the instance is able to handle the request, false otherwise
     */
    boolean canHandle (Class requestType);
    
}