Summary

Garmin.RemoteTransfer is a high-level API to transfer data to remote servers using POST, web service calls, and the like.

Version: 1.0

Author: Diana Chow diana.chow at garmin.com

if (Garmin == undefined) var Garmin = {};
/** Copyright © 2007 Garmin Ltd. or its subsidiaries.
 *
 * Licensed under the Apache License, Version 2.0 (the 'License')
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an 'AS IS' BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * @fileoverview Garmin.RemoteTransfer is a high-level API to transfer data to remote servers using POST, web service calls, and the like.
 * 
 * @author Diana Chow diana.chow at garmin.com
 * @version 1.0
 */
/** Provides the easiest avenue for getting a working instance of the plug-in onto your page.
 * Generates the UI elements and places them on the page.
 *
 * @class Garmin.RemoteTransfer
 * @constructor 
 * 
 * requires Prototype and Garmin.DeviceDisplay
 */
Garmin.RemoteTransfer = function(){}; //just here for jsdoc
//Garmin.RemoteTransfer  = {
Garmin.RemoteTransfer = Class.create();
Garmin.RemoteTransfer.prototype = {
	
	initialize: function() {
	},
	
	/** Open a REST request to a web service.  The JSON result is returned (if any) along 
	 * with request status and any error info provided by the HTTP response.
	 * 
	 * @param type - the type of REST call to make
	 * @param url - the URL of the web service endpoint
	 * @param async - true for async, false for synch. 
	 * @param parameters - parameters for the request, if any.  Should be in the hash format: 
	 * 	{paramName:paramValue, anotherParamName:anotherParamValue} 
	 * @return a response hash containing the JSON response object, and an error message if there was one. 
	 * 	message if available.  Ids of the response elements are as follows: json, error.  {json, error }
	 */
	openRequest: function(type, url, async, parameters ) {
		var response;
		var jsonResult;
		var errorMsg;
		
		var ajaxRequest = new Ajax.Request(url, {
			onSuccess: function(ajaxResponse) {
				jsonResult = ajaxResponse.responseJSON;
			},
			asynchronous: async,
			contentType: 'application/x-www-form-urlencoded',
			requestHeaders: ['X-HTTP-Method-Override', 'GET'],
			method: type,
			parameters: parameters,
			evalJSON: true,
			// Pass the general exception along for all 500 errors
			on500: function(xhr) {
				errorMsg = xhr.statusText;
			},
			// Pass the message in the exception along for all other errors.
			onFailure: function(xhr) {
				errorMsg = Garmin.RemoteTransfer.MESSAGES.generalException;
				throw new Error(xhr.statusText);
			}
		});
		
		response = {json: jsonResult, error: errorMsg};
		
		return response;
	}
};

Garmin.RemoteTransfer.MESSAGES = {
	generalException: "An error occured while completing the request."
};