- Author:
- David Nickerson <nickerso@users.sourceforge.net>
- Date:
- 2009-07-16 02:00:03+12:00
- Desc:
- the starting point for the HH tutorial example
- Permanent Source URI:
- https://models.fieldml.org/workspace/a1/rawfile/f6a8f90307388eb4b040ee3566b84d88b59247f7/dojo-presentation/js/dojo/dojox/off/sync.js
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();
