device_storage_delegate.js

// ==========================================================================
// Project:   hub.js - cloud-friendly object graph sync
// Copyright: ©2010 Erich Ocean.
//            Portions ©2006-2009 Sprout Systems, Inc. and contributors.
//            Portions ©2008-2009 Apple Inc. All rights reserved.
// License:   Licensed under an MIT license (see license.js).
// ==========================================================================
/*global hub */

/**
  FIXME: Just document manually (and remove this file).
  
  @protocol
*/
hub.DeviceStorageDelegateProtocol = {
  
  /**
    Called whenever hub.js needs to commit the changes in a hub to device 
    storage. You should commit the hashes to persistent storage on the device 
    and invoke the relevant hub.js callbacks on the hub once the data has been 
    safely stored to disk.
    
    You should return from this call immediately and invoke the success or 
    failure callbacks asychronously.
    
    @param hub {hub.Hub} the hub to commit
    @param commit {Hash} a hash for the commit attributes
    @param dataHashes {Array} an array of hashes with data attributes
    @param metadataHashes {Array} an array of hashes with metadata attributes
  */
  hubDeviceCommit: function(hub, commit, dataHashes, metadataHashes) {},

  /**
    Called whenever hub.js wants to retrieve a previously committed commit, 
    data or metadata hash.
    
    Oftentimes, hub.js only needs a subset of the stored keys, in which case 
    the hashKeys parameter will contain an array of those keys. In the event 
    that a single key is passed, you should return an array of values *for that 
    key only*, rather than an array of hashes.
    
    @param deviceKeys {SC.Array} an array of device keys
    @param hashKeys {String|Array} optional: a single key or array of keys to 
        return (see docs above for details)
    @returns {SC.Array} the results array
  */
  hubDeviceFetch: function(hub, deviceKeys, hashKeys) {},

  /**
    Called whenever hub.js needs to retrieve a range of deviceKeys for a given 
    query. This callback allows you to load query results on-demand, reducing 
    memory use in a data model.
    
    When a query on a given hub is instantiated, you will receive a 
    prepareDeviceFetchQuery() callback so that you can create any indexes you 
    may need to satisfy this callback efficiently.
    
    @param hub {hub.Hub} the hub being queried
    @param query {hub.Query} the query to return results for
    @returns {SC.Array} an array of store keys satisfying the query
  */
  hubDeviceQuery: function(hub, query) {}
  
};