analytics/webcontent/dojo16/dojox/atom/io/Connection.js

/*
	Copyright (c) 2004-2012, The Dojo Foundation All Rights Reserved.
	Available via Academic Free License >= 2.1 OR the modified BSD license.
	see: http://dojotoolkit.org/license for details
*/


if(!dojo._hasResource['dojox.atom.io.Connection']){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
dojo._hasResource['dojox.atom.io.Connection'] = true;
dojo.provide('dojox.atom.io.Connection');
dojo.require('dojox.atom.io.model');

dojo.declare("dojox.atom.io.Connection",null,{
	// summary: This object implements a transport layer for working with ATOM feeds and ATOM publishing protocols.
	// description: This object implements a transport layer for working with ATOM feeds and ATOM publishing protocols.
	//   Specifically, it provides a mechanism by which feeds can be fetched and entries can be fetched, created
	//   deleted, and modified.  It also provides access to the introspection data.

	constructor: function(/* Boolean */sync, /* Boolean */preventCache){
		// 	summary:
		//		initializer
		this.sync = sync;
		this.preventCache = preventCache;
	},

	preventCache: false, //Flag to denote if the instance should use the xhr prevent cache mechanism

	alertsEnabled: false, //Flag to turn on alerts instead of throwing errors.

	getFeed: function(/*String*/url, /*Function*/callback, /*Function*/errorCallback, scope){
		// 	summary:
		//		Function to obtain a s specific ATOM feed from a given ATOM Feed url.
		//	description:
		//		This function takes the URL for a specific ATOM feed and returns
		//		the data from that feed to the caller through the use of a callback
		//		handler.
		//
		// 	url: String
		//		The URL of the ATOM feed to fetch.
		//	callback:
		//		Function
		//		A function reference that will handle the feed when it has been retrieved.
		//		The callback should accept two parameters:  The feed object and the original complete DOM object.
		//	scope: Object
		//		The scope to use for all callbacks.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		this._getXmlDoc(url, "feed", new dojox.atom.io.model.Feed(), dojox.atom.io.model._Constants.ATOM_NS, callback, /*handleDocumentRetrieved,*/ errorCallback, scope);
	},
	
	getService: function(url, callback, errorCallback, scope){
		//	summary:
		//		Function to retrieve an introspection document from the given URL.
		// 	description:
		//		This function takes the URL for an ATOM item and feed and returns
		//		the introspection document.
		//
		//	url:
		//		String
		//		The URL of the ATOM document to obtain the introspection document of.
		//	callback:
		//		Function
		//		A function reference that will handle the introspection document when it has been retrieved.
		//		The callback should accept two parameters:  The introspection document object and the original complete DOM object.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		this._getXmlDoc(url, "service", new dojox.atom.io.model.Service(url), dojox.atom.io.model._Constants.APP_NS, callback, errorCallback, scope);
	},
	
	getEntry: function(url, callback, errorCallback, scope){
		//	summary:
		//		Function to retrieve a single entry from an ATOM feed from the given URL.
		//	description:
		//		This function takes the URL for an ATOM entry and returns the constructed dojox.atom.io.model.Entry object through
		//		the specified callback.
		//
		//	url:
		//		String
		//		The URL of the ATOM Entry document to parse.
		//	callback:
		//		Function
		//		A function reference that will handle the Entry object obtained.
		//		The callback should accept two parameters, the dojox.atom.io.model.Entry object and the original dom.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		this._getXmlDoc(url, "entry", new dojox.atom.io.model.Entry(), dojox.atom.io.model._Constants.ATOM_NS, callback, errorCallback, scope);
	},

	_getXmlDoc: function(url, nodeName, newNode, namespace, callback, errorCallback, scope){
		//	summary:
		//		Internal Function to retrieve an XML document and pass the results to a callback.
		//	description:
		//		This internal function takes the URL for an XML document and and passes the
		//		parsed contents to a specified callback.
		//
		//	url:
		//		String
		//		The URL of the XML document to retrieve
		//	callback:
		//		Function
		//		A function reference that will handle the retrieved XML data.
		//		The callback should accept one parameter, the DOM of the parsed XML document.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		if(!scope){
			scope = dojo.global;
		}
		var ae = this.alertsEnabled;
		var xhrArgs = {
			url: url,
			handleAs: "xml",
			sync: this.sync,
			preventCache: this.preventCache,
			load: function(data, args){
				var node	 = null;
				var evaldObj = data;
				var nodes;
				if(evaldObj){
					//find the first node of the appropriate name
					if(typeof(evaldObj.getElementsByTagNameNS)!= "undefined"){
						nodes = evaldObj.getElementsByTagNameNS(namespace,nodeName);
						if(nodes && nodes.length > 0){
							node = nodes.item(0);
						}else if(evaldObj.lastChild){
							// name_spaces can be used without declaration of atom (for example
							// gooogle feeds often returns iTunes name_space qualifiers on elements)
							// Treat this situation like name_spaces not enabled.
							node = evaldObj.lastChild;
						}
					}else if(typeof(evaldObj.getElementsByTagName)!= "undefined"){
						// Find the first eith the correct tag name and correct namespace.
						nodes = evaldObj.getElementsByTagName(nodeName);
						if(nodes && nodes.length > 0){
							for(var i=0; i<nodes.length; i++){
								if(nodes[i].namespaceURI == namespace){
									node = nodes[i];
									break;
								}
							}
						}else if(evaldObj.lastChild){
							node = evaldObj.lastChild;
						}
					}else if(evaldObj.lastChild){
						node = evaldObj.lastChild;
					}else{
						callback.call(scope, null, null, args);
						return;
					}
					newNode.buildFromDom(node);
					if(callback){
						callback.call(scope, newNode, evaldObj, args);
					}else if(ae){
						throw new Error("The callback value does not exist.");
					}
				}else{
					callback.call(scope, null, null, args);
				}
			}
		};

		if(this.user && this.user !== null){
			xhrArgs.user = this.user;
		}
		if(this.password && this.password !== null){
			xhrArgs.password = this.password;
		}

		if(errorCallback){
			xhrArgs.error = function(error, args){errorCallback.call(scope, error, args);};
		}else{
			xhrArgs.error = function(){
				throw new Error("The URL requested cannot be accessed");
			};
		}
		dojo.xhrGet(xhrArgs);
	},

	updateEntry: function(entry, callback, errorCallback, retrieveUpdated, xmethod, scope){
		//	summary:
		//		Function to update a specific ATOM entry by putting the new changes via APP.
		//	description:
		//		This function takes a specific dojox.atom.io.model.Entry object and pushes the
		//		changes back to the provider of the Entry.
		//		The entry MUST have a link tag with rel="edit" for this to work.
		//
		//	entry:
		//		Object
		//		The dojox.atom.io.model.Entry object to update.
		//	callback:
		//		Function
		//		A function reference that will handle the results from the entry update.
		//		The callback should accept two parameters:  The first is an Entry object, and the second is the URL of that Entry
		//		Either can be null, depending on the value of retrieveUpdated.
		//	retrieveUpdated:
		//		boolean
		//		A boolean flag denoting if the entry that was updated should then be
		//		retrieved and returned to the caller via the callback.
		//	xmethod:
		//		boolean
		//		Whether to use POST for PUT/DELETE items and send the X-Method-Override header.
		//	scope:
		//		Object
		//		The scope to use for all callbacks.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		if(!scope){
			scope = dojo.global;
		}
		entry.updated = new Date();
		var url = entry.getEditHref();
		if(!url){
			throw new Error("A URL has not been specified for editing this entry.");
		}

		var self = this;
		var ae = this.alertsEnabled;
		var xhrArgs = {
			url: url,
			handleAs: "text",
			contentType: "text/xml",
			sync: this.sync,
			preventCache: this.preventCache,
			load: function(data, args){
				var location = null;
				if(retrieveUpdated){
					location = args.xhr.getResponseHeader("Location");
					if(!location){location = url;}

					//Function to handle the callback mapping of a getEntry after an update to return the
					//entry and location.
					var handleRetrieve = function(entry, dom, args){
						if(callback){
							callback.call(scope, entry, location, args);
						}else if(ae){
							throw new Error("The callback value does not exist.");
						}
					};
					self.getEntry(location,handleRetrieve);
				}else{
					if(callback){
						callback.call(scope, entry, args.xhr.getResponseHeader("Location"), args);
					}else if(ae){
						throw new Error("The callback value does not exist.");
					}
				}
				return data;
			}
		};
		
		if(this.user && this.user !== null){
			xhrArgs.user = this.user;
		}
		if(this.password && this.password !== null){
			xhrArgs.password = this.password;
		}

		if(errorCallback){
			xhrArgs.error = function(error, args){errorCallback.call(scope, error, args);};
		}else{
			xhrArgs.error = function(){
				throw new Error("The URL requested cannot be accessed");
			};
		}

		if(xmethod){
			xhrArgs.postData = entry.toString(true); //Set the content to send.
			xhrArgs.headers = {"X-Method-Override": "PUT"};
			dojo.rawXhrPost(xhrArgs);
		}else{
			xhrArgs.putData = entry.toString(true); //Set the content to send.
			var xhr = dojo.rawXhrPut(xhrArgs);
		}
	},

	addEntry: function(entry, url, callback, errorCallback, retrieveEntry, scope){
		//	summary:
		//		Function to add a new ATOM entry by posting the new entry via APP.
		//	description:
		//		This function takes a specific dojox.atom.io.model.Entry object and pushes the
		//		changes back to the provider of the Entry.
		//
		//	entry:
		//		Object
		//		The dojox.atom.io.model.Entry object to publish.
		//	callback:
		//		Function
		//		A function reference that will handle the results from the entry publish.
		//		The callback should accept two parameters:   The first is an dojox.atom.io.model.Entry object, and the second is the location of the entry
		//		Either can be null, depending on the value of retrieveUpdated.
		//	retrieveEntry:
		//		boolean
		//		A boolean flag denoting if the entry that was created should then be
		//		retrieved and returned to the caller via the callback.
		//	scope:
		//		Object
		//	 	The scope to use for all callbacks.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		if(!scope){
			scope = dojo.global;
		}

		entry.published = new Date();
		entry.updated = new Date();

		var feedUrl = entry.feedUrl;
		var ae = this.alertsEnabled;

		//Determine which URL to use for the post.
		if(!url && feedUrl){url = feedUrl;}
		if(!url){
			if(ae){
				throw new Error("The request cannot be processed because the URL parameter is missing.");
			}
			return;
		}

		var self = this;
		var xhrArgs = {
			url: url,
			handleAs: "text",
			contentType: "text/xml",
			sync: this.sync,
			preventCache: this.preventCache,
			postData: entry.toString(true),
			load: function(data, args){
				var location = args.xhr.getResponseHeader("Location");
				if(!location){
					location = url;
				}
				if(!args.retrieveEntry){
					if(callback){
						callback.call(scope, entry, location, args);
					}else if(ae){
						throw new Error("The callback value does not exist.");
					}
				}else{
					//Function to handle the callback mapping of a getEntry after an update to return the
					//entry and location.
					var handleRetrieve = function(entry, dom, args){
						if(callback){
							callback.call(scope, entry, location, args);
						}else if(ae){
							throw new Error("The callback value does not exist.");
						}
					};
					self.getEntry(location,handleRetrieve);
				}
				return data;
			}
		};

		if(this.user && this.user !== null){
			xhrArgs.user = this.user;
		}
		if(this.password && this.password !== null){
			xhrArgs.password = this.password;
		}

		if(errorCallback){
			xhrArgs.error = function(error, args){errorCallback.call(scope, error, args);};
		}else{
			xhrArgs.error = function(){
				throw new Error("The URL requested cannot be accessed");
			};
		}
		dojo.rawXhrPost(xhrArgs);
	},

	deleteEntry: function(entry,callback,errorCallback,xmethod,scope){
		//	summary:
		//		Function to delete a specific ATOM entry via APP.
		//	description:
		//		This function takes a specific dojox.atom.io.model.Entry object and calls for a delete on the
		//		service housing the ATOM Entry database.
		//		The entry MUST have a link tag with rel="edit" for this to work.
		//
		//	entry:
		//		Object
		//		The dojox.atom.io.model.Entry object to delete.
		//	callback:
		//		Function
		//		A function reference that will handle the results from the entry delete.
		//		The callback is called only if the delete is successful.
		//
		//	returns:
		//		Nothing. The return is handled through the callback handler.
		if(!scope){
			scope = dojo.global;
		}

		var url = null;
		if(typeof(entry) == "string"){
			url = entry;
		}else{
			url = entry.getEditHref();
		}
		if(!url){
			callback.call(scope, false, null);
			throw new Error("The request cannot be processed because the URL parameter is missing.");
		}

		var xhrArgs = {
			url: url,
			handleAs: "text",
			sync: this.sync,
			preventCache: this.preventCache,
			load: function(data, args){
				callback.call(scope, args);
				return data;
			}
		};

		if(this.user && this.user !== null){
			xhrArgs.user = this.user;
		}
		if(this.password && this.password !== null){
			xhrArgs.password = this.password;
		}

		if(errorCallback){
			xhrArgs.error = function(error, args){errorCallback.call(scope, error, args);};
		}else{
			xhrArgs.error = function(){
				throw new Error("The URL requested cannot be accessed");
			};
		}
		if(xmethod){
			xhrArgs.headers = {"X-Method-Override": "DELETE"};
			dojo.xhrPost(xhrArgs);
		}else{
			dojo.xhrDelete(xhrArgs);
		}
	}
});

}