com.afrigis.services.ServiceCallFactory Maven / Gradle / Ivy
Show all versions of core Show documentation
package com.afrigis.services;
import java.util.concurrent.Future;
/**
*
* Implementing classes are responsible for producing various service objects,
* that in turn implement the services provided by AfriGIS.
*
*
* @author hendrikc
*
*
*/
public interface ServiceCallFactory {
/**
*
* Allows overriding of the service end point URL to be used.
*
*
*
* If you provide a URL via this method, we assume you know what you are
* doing. So we will use this URL as the base for our calls AS-IS.
*
*
* @param server
* the server hostname,and optionally protocol
*
*/
void setServiceEndpoint(String server);
/**
*
* @return the base server url
*/
String getServiceEndpoint();
/**
*
* Allows user to hint at a connection, connection request, and socket
* timeout.
*
*
* Default should be 30seconds.
*
*
* @param timeoutInSec
* essentially HTTP/TCP/IP timeout, specified in seconds
*/
void setTimeout(int timeoutInSec); // units = seconds
/**
*
* Fetches the remaining credits for the account.
*
*
* @return remaining credit balance for the account
*/
int getCreditBalance();
/**
*
* Async version of {@link #getCreditBalance()}.
*
*
* @return a {@link Future} promise that should contain the remaining
* balance.
*/
Future getCreditBalanceAsync();
/**
*
* Fetches a deserialized object from the server. The Response object
* returned will extend/implement {@link Response} super class.
*
*
* @param
* the specific type of the service request. Must implement
* {@link Request}
* @param
* the specific type of the request object. Must implement
* {@link Response}
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return an implementation of {@link Response} appropriate for the desired
* service
*/
R get(T request);
/**
*
* Async version of {@link #get(Request)}.
*
*
* @param
* the specific type of the service request. Must implement
* {@link Request}
* @param
* the specific type of the request object. Must implement
* {@link Response}
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return an implementation of {@link Response} appropriate for the desired
* service, wrapped in a {@link Future} promise
*/
Future getAsync(T request);
/**
*
* Fetches a response from the server, as a String.
*
*
* @param
* the specific type of the service request. Must implement
* {@link Request}
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return the response of the server, converted to a UTF-8 String
*/
String getString(T request);
/**
*
* Fetches a response from the server, as a String, asynchronously.
*
*
* @param
* the specific type of the service request. Must implement
* {@link Request}
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return the response of the server, converted to a UTF-8 String
* @see #getString(Request)
*/
Future getStringAsync(T request);
/**
*
* Fetches a response from the server, as a byte array.
*
*
* @param
* the specific type of the service request. Must implement
* {@link Request}
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return the response of the server, as a byte array
*/
byte[] getByteArray(T request);
/**
*
* Asynchronous version of {@link #getByteArray(Request)}.
*
*
* @param
* the specific type of the service request. Must implement
* {@link Request}
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return the response of the server, as a byte array
*/
Future getByteArrayAsync(T request);
/**
*
* Produces a full valid url that can be used by an external call, while it
* is valid.
*
*
* URLs are valid for server configured amount of time. At time of writing,
* that is 1 minute.
*
*
* @param request
* the implementation of {@link Request} appropriate to the
* desired service
* @return a URL that can be used to query the desired AfriGIS Services
* (while valid)
*/
String buildUrl(Request request);
/**
*
* THis method allows the user to provide a service name, and a pre-built
* query parameter string.
*
*
* THe query parameters must not be encoded - the lib will attempt to do
* that for you.
*
*
* @param serviceName
* the valid AfriGIS Services service name
* @param queryString
* the pre-build (UNENCODED) query string
* @return the server response, as a UTF-8 encoded String.
*/
String getString(String serviceName, String queryString);
}