| New file |
|---|
| 0,0 → 1,690 |
|---|
| 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(); |
| |
| } |