apicall.java

Vodafone betavine java api source code, the latest snapshot.

package com.bv.api;
import com.bv.api.response.ApiResponse;
import java.io.UnsupportedEncodingException;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;

/** 
 * Base API class for Vodafone Betavine API. 
 * Designed for use with "plain" response.
 * 
 * @author C. Oattes, Kris Nobes
 */
public abstract class APICall  {

	protected String url;
	protected abstract String constructParameterString(String uaid) throws InvalidParameterException;
	
	/**
	 * Check that the required parameters set for the API Call are set and present.
	 * @return <code>true</code> if all required parameters are set and present
	 * @throws ParamNotPresentException If a required parameter is not set
	 * @throws InvalidParameterException If a supplied parameter is outside the allowed range
	 */
	protected abstract boolean checkParams(String uaid) throws ParamNotPresentException, InvalidParameterException;
	
	/**
	 * Send request to API server.
	 * @return {@link ApiResponse}
	 * @throws ParamNotPresentException If a required parameter is not set
	 * @throws InvalidParameterException If a supplied parameter is outside the allowed range
	 */
	public abstract ApiResponse execute(String uaid, String serverURL) throws ParamNotPresentException, InvalidParameterException;
	
	
	protected APICall() {}
	

	/**
	 * Returns UTF-8 encoded key and parameter in the form <code>key=parameter</code>. The = is not UTF-8 encoded.
	 * @param key The name of the parameter to set
	 * @param parameter The data to be set
	 * @return A String in the form key=parameter
	 */
	protected static String getEncodedParams(String key, String parameter) { 
		String encodedString = "";
		try {
			encodedString = URLEncoder.encode(key, "UTF-8") + "=" + URLEncoder.encode(parameter, "UTF-8");
		} catch (UnsupportedEncodingException e) { /*Do nothing*/ }
		return encodedString;
	}
	
	/**
	 * Generates a {@link URL} object for the API call. The URL will have the structure: <code>http://server_address/api_name.plain?key1=param1&key2=param2&...&keyn=paramn</code>
	 * @return {@link URL}
	 * @throws InvalidParameterException If a supplied parameter is outside the allowed range
	 * @throws MalformedURLException If the generated URL is invalid.
	 */
	protected URL constructURL(String uaid, String serverURL) throws InvalidParameterException, MalformedURLException {
		URL connectionURL = null;
		String constructedURL = serverURL + url + ".plain?" + constructParameterString(uaid);
		connectionURL = new URL(constructedURL);
		return connectionURL;
	}
	


}