sync.js
No OneTemporary
Actions

Size

21 KB

Subscribers

None

sync.js
View Options

	if(!dojo._hasResource["dojox.off.sync"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
	dojo._hasResource["dojox.off.sync"] = true;
	dojo.provide("dojox.off.sync");

	dojo.require("dojox.storage.GearsStorageProvider");
	dojo.require("dojox.off._common");
	dojo.require("dojox.off.files");

	// Author: Brad Neuberg, bkn3@columbia.edu, http://codinginparadise.org

	// summary:
	// Exposes syncing functionality to offline applications
	dojo.mixin(dojox.off.sync, {
	// isSyncing: boolean
	// Whether we are in the middle of a syncing session.
	isSyncing: false,

	// cancelled: boolean
	// Whether we were cancelled during our last sync request or not. If
	// we are cancelled, then successful will be false.
	cancelled: false,

	// successful: boolean
	// Whether the last sync was successful or not. If false, an error
	// occurred.
	successful: true,

	// details: String[]
	// Details on the sync. If the sync was successful, this will carry
	// any conflict or merging messages that might be available; if the
	// sync was unsuccessful, this will have an error message. For both
	// of these, this should be an array of Strings, where each string
	// carries details on the sync.
	// Example:
	// dojox.off.sync.details = ["The document 'foobar' had conflicts - yours one",
	// "The document 'hello world' was automatically merged"];
	details: [],

	// error: boolean
	// Whether an error occurred during the syncing process.
	error: false,

	// actions: dojox.off.sync.ActionLog
	// Our ActionLog that we store offline actions into for later
	// replaying when we go online
	actions: null,

	// autoSync: boolean
	// For advanced usage; most developers can ignore this.
	// Whether we do automatically sync on page load or when we go online.
	// If true we do, if false syncing must be manually initiated.
	// Defaults to true.
	autoSync: true,

	// summary:
	// An event handler that is called during the syncing process with
	// the state of syncing. It is important that you connect to this
	// method and respond to certain sync events, especially the
	// "download" event.
	// description:
	// This event handler is called during the syncing process. You can
	// do a dojo.connect to receive sync feedback:
	//
	// dojo.connect(dojox.off.sync, "onSync", someFunc);
	//
	// You will receive one argument, which is the type of the event
	// and which can have the following values.
	//
	// The most common two types that you need to care about are "download"
	// and "finished", especially if you are using the default
	// Dojo Offline UI widget that does the hard work of informing
	// the user through the UI about what is occuring during syncing.
	//
	// If you receive the "download" event, you should make a network call
	// to retrieve and store your data somehow for offline access. The
	// "finished" event indicates that syncing is done. An example:
	//
	// dojo.connect(dojox.off.sync, "onSync", function(type){
	// if(type == "download"){
	// // make a network call to download some data
	// // for use offline
	// dojo.xhrGet({
	// url: "downloadData.php",
	// handleAs: "javascript",
	// error: function(err){
	// dojox.off.sync.finishedDownloading(false, "Can't download data");
	// },
	// load: function(data){
	// // store our data
	// dojox.storage.put("myData", data);
	//
	// // indicate we are finished downloading
	// dojox.off.sync.finishedDownloading(true);
	// }
	// });
	// }else if(type == "finished"){
	// // update UI somehow to indicate we are finished,
	// // such as using the download data to change the
	// // available data
	// }
	// })
	//
	// Here is the full list of event types if you want to do deep
	// customization, such as updating your UI to display the progress
	// of syncing (note that the default Dojo Offline UI widget does
	// this for you if you choose to pull that in). Most of these
	// are only appropriate for advanced usage and can be safely
	// ignored:
	//
	// * "start"
	// syncing has started
	// * "refreshFiles"
	// syncing will begin refreshing
	// our offline file cache
	// * "upload"
	// syncing will begin uploading
	// any local data changes we have on the client.
	// This event is fired before we fire
	// the dojox.off.sync.actions.onReplay event for
	// each action to replay; use it to completely
	// over-ride the replaying behavior and prevent
	// it entirely, perhaps rolling your own sync
	// protocol if needed.
	// * "download"
	// syncing will begin downloading any new data that is
	// needed into persistent storage. Applications are required to
	// implement this themselves, storing the required data into
	// persistent local storage using Dojo Storage.
	// * "finished"
	// syncing is finished; this
	// will be called whether an error ocurred or not; check
	// dojox.off.sync.successful and dojox.off.sync.error for sync details
	// * "cancel"
	// Fired when canceling has been initiated; canceling will be
	// attempted, followed by the sync event "finished".
	onSync: function(/* String */ type){},

	synchronize: function(){ /* void */
	// summary: Starts synchronizing

	//dojo.debug("synchronize");
	if(this.isSyncing \|\| dojox.off.goingOnline \|\| (!dojox.off.isOnline)){
	return;
	}

	this.isSyncing = true;
	this.successful = false;
	this.details = [];
	this.cancelled = false;

	this.start();
	},

	cancel: function(){ /* void */
	// summary:
	// Attempts to cancel this sync session

	if(!this.isSyncing){ return; }

	this.cancelled = true;
	if(dojox.off.files.refreshing){
	dojox.off.files.abortRefresh();
	}

	this.onSync("cancel");
	},

	finishedDownloading: function(successful /* boolean? */,
	errorMessage /* String? */){
	// summary:
	// Applications call this method from their
	// after getting a "download" event in
	// dojox.off.sync.onSync to signal that
	// they are finished downloading any data
	// that should be available offline
	// successful: boolean?
	// Whether our downloading was successful or not.
	// If not present, defaults to true.
	// errorMessage: String?
	// If unsuccessful, a message explaining why
	if(typeof successful == "undefined"){
	successful = true;
	}

	if(!successful){
	this.successful = false;
	this.details.push(errorMessage);
	this.error = true;
	}

	this.finished();
	},

	start: function(){ /* void */
	// summary:
	// For advanced usage; most developers can ignore this.
	// Called at the start of the syncing process. Advanced
	// developers can over-ride this method to use their
	// own sync mechanism to start syncing.

	if(this.cancelled){
	this.finished();
	return;
	}
	this.onSync("start");
	this.refreshFiles();
	},

	refreshFiles: function(){ /* void */
	// summary:
	// For advanced usage; most developers can ignore this.
	// Called when we are going to refresh our list
	// of offline files during syncing. Advanced developers
	// can over-ride this method to do some advanced magic related to
	// refreshing files.

	//dojo.debug("refreshFiles");
	if(this.cancelled){
	this.finished();
	return;
	}

	this.onSync("refreshFiles");

	dojox.off.files.refresh(dojo.hitch(this, function(error, errorMessages){
	if(error){
	this.error = true;
	this.successful = false;
	for(var i = 0; i < errorMessages.length; i++){
	this.details.push(errorMessages[i]);
	}

	// even if we get an error while syncing files,
	// keep syncing so we can upload and download
	// data
	}

	this.upload();
	}));
	},

	upload: function(){ /* void */
	// summary:
	// For advanced usage; most developers can ignore this.
	// Called when syncing wants to upload data. Advanced
	// developers can over-ride this method to completely
	// throw away the Action Log and replaying system
	// and roll their own advanced sync mechanism if needed.

	if(this.cancelled){
	this.finished();
	return;
	}

	this.onSync("upload");

	// when we are done uploading start downloading
	dojo.connect(this.actions, "onReplayFinished", this, this.download);

	// replay the actions log
	this.actions.replay();
	},

	download: function(){ /* void */
	// summary:
	// For advanced usage; most developers can ignore this.
	// Called when syncing wants to download data. Advanced
	// developers can over-ride this method to use their
	// own sync mechanism.

	if(this.cancelled){
	this.finished();
	return;
	}

	// apps should respond to the "download"
	// event to download their data; when done
	// they must call dojox.off.sync.finishedDownloading()
	this.onSync("download");
	},

	finished: function(){ /* void */
	// summary:
	// For advanced usage; most developers can ignore this.
	// Called when syncing is finished. Advanced
	// developers can over-ride this method to clean
	// up after finishing their own sync
	// mechanism they might have rolled.
	this.isSyncing = false;

	this.successful = (!this.cancelled && !this.error);

	this.onSync("finished");
	},

	_save: function(callback){
	this.actions._save(function(){
	callback();
	});
	},

	_load: function(callback){
	this.actions._load(function(){
	callback();
	});
	}
	});


	// summary:
	// A class that records actions taken by a user when they are offline,
	// suitable for replaying when the network reappears.
	// description:
	// The basic idea behind this method is to record user actions that would
	// normally have to contact a server into an action log when we are
	// offline, so that later when we are online we can simply replay this log
	// in the order user actions happened so that they can be executed against
	// the server, causing synchronization to happen.
	//
	// When we replay, for each of the actions that were added, we call a
	// method named onReplay that applications should connect to and
	// which will be called over and over for each of our actions --
	// applications should take the offline action
	// information and use it to talk to a server to have this action
	// actually happen online, 'syncing' themselves with the server.
	//
	// For example, if the action was "update" with the item that was updated, we
	// might call some RESTian server API that exists for updating an item in
	// our application. The server could either then do sophisticated merging
	// and conflict resolution on the server side, for example, allowing you
	// to pop up a custom merge UI, or could do automatic merging or nothing
	// of the sort. When you are finished with this particular action, your
	// application is then required to call continueReplay() on the actionLog object
	// passed to onReplay() to continue replaying the action log, or haltReplay()
	// with the reason for halting to completely stop the syncing/replaying
	// process.
	//
	// For example, imagine that we have a web application that allows us to add
	// contacts. If we are offline, and we update a contact, we would add an action;
	// imagine that the user has to click an Update button after changing the values
	// for a given contact:
	//
	// dojox.off.whenOffline(dojo.byId("updateButton"), "onclick", function(evt){
	// // get the updated customer values
	// var customer = getCustomerValues();
	//
	// // we are offline -- just record this action
	// var action = {name: "update", customer: customer};
	// dojox.off.sync.actions.add(action)
	//
	// // persist this customer data into local storage as well
	// dojox.storage.put(customer.name, customer);
	// })
	//
	// Then, when we go back online, the dojox.off.sync.actions.onReplay event
	// will fire over and over, once for each action that was recorded while offline:
	//
	// dojo.connect(dojox.off.sync.actions, "onReplay", function(action, actionLog){
	// // called once for each action we added while offline, in the order
	// // they were added
	// if(action.name == "update"){
	// var customer = action.customer;
	//
	// // call some network service to update this customer
	// dojo.xhrPost({
	// url: "updateCustomer.php",
	// content: {customer: dojo.toJson(customer)},
	// error: function(err){
	// actionLog.haltReplay(err);
	// },
	// load: function(data){
	// actionLog.continueReplay();
	// }
	// })
	// }
	// })
	//
	// Note that the actions log is always automatically persisted locally while using it, so
	// that if the user closes the browser or it crashes the actions will safely be stored
	// for later replaying.
	dojo.declare("dojox.off.sync.ActionLog", null, {
	// entries: Array
	// An array of our action entries, where each one is simply a custom
	// object literal that were passed to add() when this action entry
	// was added.
	entries: [],

	// reasonHalted: String
	// If we halted, the reason why
	reasonHalted: null,

	// isReplaying: boolean
	// If true, we are in the middle of replaying a command log; if false,
	// then we are not
	isReplaying: false,

	// autoSave: boolean
	// Whether we automatically save the action log after each call to
	// add(); defaults to true. For applications that are rapidly adding
	// many action log entries in a short period of time, it can be
	// useful to set this to false and simply call save() yourself when
	// you are ready to persist your command log -- otherwise performance
	// could be slow as the default action is to attempt to persist the
	// actions log constantly with calls to add().
	autoSave: true,

	add: function(action /* Object /){ / void */
	// summary:
	// Adds an action to our action log
	// description:
	// This method will add an action to our
	// action log, later to be replayed when we
	// go from offline to online. 'action'
	// will be available when this action is
	// replayed and will be passed to onReplay.
	//
	// Example usage:
	//
	// dojox.off.sync.log.add({actionName: "create", itemType: "document",
	// {title: "Message", content: "Hello World"}});
	//
	// The object literal is simply a custom object appropriate
	// for our application -- it can be anything that preserves the state
	// of a user action that will be executed when we go back online
	// and replay this log. In the above example,
	// "create" is the name of this action; "documents" is the
	// type of item this command is operating on, such as documents, contacts,
	// tasks, etc.; and the final argument is the document that was created.

	if(this.isReplaying){
	throw "Programming error: you can not call "
	+ "dojox.off.sync.actions.add() while "
	+ "we are replaying an action log";
	}

	this.entries.push(action);

	// save our updated state into persistent
	// storage
	if(this.autoSave){
	this._save();
	}
	},

	onReplay: function(action /* Object */,
	actionLog /* dojox.off.sync.ActionLog /){ / void */
	// summary:
	// Called when we replay our log, for each of our action
	// entries.
	// action: Object
	// A custom object literal representing an action for this
	// application, such as
	// {actionName: "create", item: {title: "message", content: "hello world"}}
	// actionLog: dojox.off.sync.ActionLog
	// A reference to the dojox.off.sync.actions log so that developers
	// can easily call actionLog.continueReplay() or actionLog.haltReplay().
	// description:
	// This callback should be connected to by applications so that
	// they can sync themselves when we go back online:
	//
	// dojo.connect(dojox.off.sync.actions, "onReplay", function(action, actionLog){
	// // do something
	// })
	//
	// When we replay our action log, this callback is called for each
	// of our action entries in the order they were added. The
	// 'action' entry that was passed to add() for this action will
	// also be passed in to onReplay, so that applications can use this information
	// to do their syncing, such as contacting a server web-service
	// to create a new item, for example.
	//
	// Inside the method you connected to onReplay, you should either call
	// actionLog.haltReplay(reason) if an error occurred and you would like to halt
	// action replaying or actionLog.continueReplay() to have the action log
	// continue replaying its log and proceed to the next action;
	// the reason you must call these is the action you execute inside of
	// onAction will probably be asynchronous, since it will be talking on
	// the network, and you should call one of these two methods based on
	// the result of your network call.
	},

	length: function(){ /* Number */
	// summary:
	// Returns the length of this
	// action log
	return this.entries.length;
	},

	haltReplay: function(reason /* String /){ / void */
	// summary: Halts replaying this command log.
	// reason: String
	// The reason we halted.
	// description:
	// This method is called as we are replaying an action log; it
	// can be called from dojox.off.sync.actions.onReplay, for
	// example, for an application to indicate an error occurred
	// while replaying this action, halting further processing of
	// the action log. Note that any action log entries that
	// were processed before have their effects retained (i.e.
	// they are not rolled back), while the action entry that was
	// halted stays in our list of actions to later be replayed.
	if(!this.isReplaying){
	return;
	}

	if(reason){
	this.reasonHalted = reason.toString();
	}

	// save the state of our action log, then
	// tell anyone who is interested that we are
	// done when we are finished saving
	if(this.autoSave){
	var self = this;
	this._save(function(){
	self.isReplaying = false;
	self.onReplayFinished();
	});
	}else{
	this.isReplaying = false;
	this.onReplayFinished();
	}
	},

	continueReplay: function(){ /* void */
	// summary:
	// Indicates that we should continue processing out list of
	// actions.
	// description:
	// This method is called by applications that have overridden
	// dojox.off.sync.actions.onReplay() to continue replaying our
	// action log after the application has finished handling the
	// current action.
	if(!this.isReplaying){
	return;
	}

	// shift off the old action we just ran
	this.entries.shift();

	// are we done?
	if(!this.entries.length){
	// save the state of our action log, then
	// tell anyone who is interested that we are
	// done when we are finished saving
	if(this.autoSave){
	var self = this;
	this._save(function(){
	self.isReplaying = false;
	self.onReplayFinished();
	});
	return;
	}else{
	this.isReplaying = false;
	this.onReplayFinished();
	return;
	}
	}

	// get the next action
	var nextAction = this.entries[0];
	this.onReplay(nextAction, this);
	},

	clear: function(){ /* void */
	// summary:
	// Completely clears this action log of its entries

	if(this.isReplaying){
	return;
	}

	this.entries = [];

	// save our updated state into persistent
	// storage
	if(this.autoSave){
	this._save();
	}
	},

	replay: function(){ /* void */
	// summary:
	// For advanced usage; most developers can ignore this.
	// Replays all of the commands that have been
	// cached in this command log when we go back online;
	// onCommand will be called for each command we have

	if(this.isReplaying){
	return;
	}

	this.reasonHalted = null;

	if(!this.entries.length){
	this.onReplayFinished();
	return;
	}

	this.isReplaying = true;

	var nextAction = this.entries[0];
	this.onReplay(nextAction, this);
	},

	// onReplayFinished: Function
	// For advanced usage; most developers can ignore this.
	// Called when we are finished replaying our commands;
	// called if we have successfully exhausted all of our
	// commands, or if an error occurred during replaying.
	// The default implementation simply continues the
	// synchronization process. Connect to this to register
	// for the event:
	//
	// dojo.connect(dojox.off.sync.actions, "onReplayFinished",
	// someFunc)
	onReplayFinished: function(){
	},

	toString: function(){
	var results = "";
	results += "[";

	for(var i = 0; i < this.entries.length; i++){
	results += "{";
	for(var j in this.entries[i]){
	results += j + ": \"" + this.entries[i][j] + "\"";
	results += ", ";
	}
	results += "}, ";
	}

	results += "]";

	return results;
	},

	_save: function(callback){
	if(!callback){
	callback = function(){};
	}

	try{
	var self = this;
	var resultsHandler = function(status, key, message){
	//console.debug("resultsHandler, status="+status+", key="+key+", message="+message);
	if(status == dojox.storage.FAILED){
	dojox.off.onFrameworkEvent("save",
	{status: dojox.storage.FAILED,
	isCoreSave: true,
	key: key,
	value: message,
	namespace: dojox.off.STORAGE_NAMESPACE});
	callback();
	}else if(status == dojox.storage.SUCCESS){
	callback();
	}
	};

	dojox.storage.put("actionlog", this.entries, resultsHandler,
	dojox.off.STORAGE_NAMESPACE);
	}catch(exp){
	console.debug("dojox.off.sync._save: " + exp.message\|\|exp);
	dojox.off.onFrameworkEvent("save",
	{status: dojox.storage.FAILED,
	isCoreSave: true,
	key: "actionlog",
	value: this.entries,
	namespace: dojox.off.STORAGE_NAMESPACE});
	callback();
	}
	},

	_load: function(callback){
	var entries = dojox.storage.get("actionlog", dojox.off.STORAGE_NAMESPACE);

	if(!entries){
	entries = [];
	}

	this.entries = entries;

	callback();
	}
	}
	);

	dojox.off.sync.actions = new dojox.off.sync.ActionLog();

	}

File Metadata

Mime Type: text/plain
Expires: Sat, Feb 22, 15:28 (22 h, 36 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 23334
Default Alt Text: sync.js (21 KB)

sync.jsNo OneTemporaryActions

sync.jsView Options

File Metadata

Event Timeline

sync.js
No OneTemporary
Actions

sync.js
View Options