sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

data/frameworks/sproutcore/frameworks/datastore/data_sources/data_source.js

@@ -0,0 +1,273 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+
+/** @class
+
+  TODO: Describe
+  
+  @extend SC.Object
+  @since SproutCore 1.0
+*/
+SC.DataSource = SC.Object.extend( /** SC.DataSource.prototype */ {
+
+  // ..........................................................
+  // SC.STORE ENTRY POINTS
+  // 
+  
+
+  /**
+    Invoked by the store whenever it needs to retrieve data matching a specific 
+    query, triggered by findAll() or retrieveRecords(). The fetchKey will most 
+    times be either an SC.Record subclass or an SC.Query object, but it could 
+    be anything you want.
+    
+    If your data source subclass can handle the fetch you should override this 
+    method to return a SC.Array with storeKeys. You can return it immediately 
+    or return an empty array and populate it dynamically later once the result 
+    set has arrived with .replace() . You can also return a SC.SparseArray, 
+    where data source will be consulted to dynamically populate the contents 
+    of the array as it is requested.
+    
+    Note that if you gave an SC.Query as the fetchKey to findAll() on the store
+    you do not have to return anything from this method as you are from then on 
+    delegating the responsibility to keep the record array updated to the store.
+    The fetch() method in that case merely functions as a notification 
+    mechanism where you get the opportunity to fetch more data from a backend
+    based on the SC.Query.
+    
+    On return, the Store will write your result set in an SC.RecordArray 
+    instance, which will monitor your array for changes and then maps those
+    store keys to actual SC.Record instances.  SC.RecordArray can also use 
+    your underlying storeKeys to create subqueries for client-side searching
+    and filtering.
+    
+    findAll() will request all records and load them using store.loadRecords(). 
+    retrieveRecords() checks if the record is already loaded and in a clean 
+    state to then just materialize it. If the record is in an empty state, it 
+    will call this method to load the required record to then materialize it.
+    
+    @param {SC.Store} store the requesting store
+    @param {Object|SC.Query} fetchKey key describing the request, may be 
+      SC.Record or SC.Record.STORE_KEYS if invoked from store.retrieveRecords.
+      Could also be an SC.Query if that was passed in to findAll()
+    @param {Hash} params optional additonal fetch params. storeKeys if invoked
+      from store.retrieveRecords
+    @returns {SC.Array} result set with storeKeys. In case of SC.Array
+      it may be sparse.
+  */
+  fetch: function(store, fetchKey, params) {
+    return null;  
+  },
+  
+  /**
+    Called when store needs a set of storeKeys
+    
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKeys
+    @param {Array} ids - optional
+    @returns 
+  */
+  
+  retrieveRecords: function(store, storeKeys, ids) {
+    return this._handleEach(store, storeKeys, this.retrieveRecord, ids);  
+  },
+  
+  /**
+    Invoked by the store whenever it has one or more records with pending 
+    changes that need to be sent back to the server.  The store keys will be
+    separated into three categories:
+    
+     - createStoreKeys: records that need to be created on server
+     - updateStoreKeys: existing records that have been modified
+     - destroyStoreKeys: records need to be destroyed on the server
+     
+    If you do not override this method yourself, this method will actually
+    invoke createRecords(), updateRecords(), and destroyRecords() on the 
+    dataSource, passing each array of storeKeys.  You can usually implement
+    those methods instead of overriding this method.
+    
+    However, if your server API can sync multiple changes at once, you may
+    prefer to override this method instead.
+    
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle any of the keys, YES if you can handle all of the keys, or
+    SC.MIXED_STATE if you can handle some of them.
+
+    @param {SC.Store} store the requesting store
+    @param {Array} createStoreKeys keys to create
+    @param {Array} updateStoreKeys keys to update
+    @param {Array} destroyStoreKeys keys to destroy
+    @returns {Boolean} YES if data source can handle keys
+  */
+  commitRecords: function(store, createStoreKeys, updateStoreKeys, destroyStoreKeys) {
+    var cret, uret, dret;
+    if(createStoreKeys.length>0) cret = this.createRecords.call(this, store, createStoreKeys);    
+    if(updateStoreKeys.length>0) uret = this.updateRecords.call(this, store, updateStoreKeys);    
+    if(destroyStoreKeys.length>0) dret = this.destroyRecords.call(this, store, destroyStoreKeys); 
+    return (cret === uret === dret) ? (cret || uret || dret) : SC.MIXED_STATE ;
+  },
+  
+  /**
+    Invoked by the store whenever it needs to cancel one or more records that
+    are currently in-flight.  If any of the storeKeys match records you are
+    currently acting upon, you should cancel the in-progress operation and 
+    return YES.
+    
+    If you implement an in-memory data source that immediately services the
+    other requests, then this method will never be called on your data source.
+    
+    To support cascading data stores, be sure to return NO if you cannot 
+    retrieve any of the keys, YES if you can retrieve all of the, or
+    SC.MIXED_STATE if you can retrieve some of the.
+    
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKeys array of storeKeys to retrieve
+    @returns {Boolean} YES if data source can handle keys
+  */
+  cancel: function(store, storeKeys) {
+    return NO;
+  },
+  
+  // ..........................................................
+  // BULK RECORD ACTIONS
+  // 
+  
+  /**
+    Called from commitRecords() to commit modified existing records to the 
+    store.  You can override this method to actually send the updated 
+    records to your store.  The default version will simply call 
+    updateRecord() for each storeKey.
+
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle any of the keys, YES if you can handle all of the keys, or
+    SC.MIXED_STATE if you can handle some of them.
+
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKeys keys to update
+  */
+  updateRecords: function(store, storeKeys) {
+    return this._handleEach(store, storeKeys, this.updateRecord);
+  },
+  
+  /**
+    Called from commitRecords() to commit newly created records to the 
+    store.  You can override this method to actually send the created 
+    records to your store.  The default version will simply call 
+    createRecord() for each storeKey.
+
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle any of the keys, YES if you can handle all of the keys, or
+    SC.MIXED_STATE if you can handle some of them.
+
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKeys keys to update
+  */
+  createRecords: function(store, storeKeys) {
+    return this._handleEach(store, storeKeys, this.createRecord);
+  },
+
+  /**
+    Called from commitRecords() to commit destroted records to the 
+    store.  You can override this method to actually send the destroyed 
+    records to your store.  The default version will simply call 
+    destroyRecord() for each storeKey.
+
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle any of the keys, YES if you can handle all of the keys, or
+    SC.MIXED_STATE if you can handle some of them.
+
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKeys keys to update
+  */
+  destroyRecords: function(store, storeKeys) {
+    return this._handleEach(store, storeKeys, this.destroyRecord);
+  },
+
+  /** @private
+    invokes the named action for each store key.  returns proper value
+  */
+  _handleEach: function(store, storeKeys, action, ids) {
+    var len = storeKeys.length, idx, ret, cur;
+    if(!ids) ids = [];
+    
+    for(idx=0;idx<len;idx++) {
+      cur = action.call(this, store, storeKeys[idx], ids[idx]);
+      if (ret === undefined) {
+        ret = cur ;
+      } else if (ret === YES) {
+        ret = (cur === YES) ? YES : SC.MIXED_STATE ;
+      } else if (ret === NO) {
+        ret = (cur === NO) ? NO : SC.MIXED_STATE ;
+      }
+    }
+    return ret ? ret : null ;
+  },
+  
+
+  // ..........................................................
+  // SINGLE RECORD ACTIONS
+  // 
+  
+  /**
+    Called from updatesRecords() to update a single record.  This is the 
+    most basic primitive to can implement to support updating a record.
+    
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle the passed storeKey or YES if you can.
+    
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKey key to update
+    @returns {Boolean} YES if handled
+  */
+  updateRecord: function(store, storeKey) {
+    return NO ;
+  },
+
+  /**
+    Called from retrieveRecords() to retrieve a single record.
+    
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKey key to retrieve
+    @param {String} id the id to retrieve
+    @returns {Boolean} YES if handled
+  */
+  retrieveRecord: function(store, storeKey, id) {
+    return NO ;
+  },
+
+  /**
+    Called from createdRecords() to created a single record.  This is the 
+    most basic primitive to can implement to support creating a record.
+    
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle the passed storeKey or YES if you can.
+    
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKey key to update
+    @returns {Boolean} YES if handled
+  */
+  createRecord: function(store, storeKey) {
+    return NO ;
+  },
+
+  /**
+    Called from destroyRecords() to destroy a single record.  This is the 
+    most basic primitive to can implement to support destroying a record.
+    
+    To support cascading data stores, be sure to return NO if you cannot 
+    handle the passed storeKey or YES if you can.
+    
+    @param {SC.Store} store the requesting store
+    @param {Array} storeKey key to update
+    @returns {Boolean} YES if handled
+  */
+  destroyRecord: function(store, storeKey) {
+    return NO ;
+  }  
+    
+});

data/frameworks/sproutcore/frameworks/datastore/data_sources/fixtures.js

@@ -0,0 +1,311 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('data_sources/data_source');
+sc_require('models/record');
+
+/** @class
+
+  TODO: Describe Class
+  
+  @extends SC.DataSource
+  @since SproutCore 1.0
+*/
+SC.FixturesDataSource = SC.DataSource.extend( {
+
+  // ..........................................................
+  // STANDARD DATA SOURCE METHODS
+  // 
+  
+  /**
+    
+    Invoked by the store whenever it needs to load a fresh new batch or 
+    records or simply refresh based on their storeKeys. This method is 
+    invoked from the store methods 'findAll' and 'retrieveRecords'. 
+    
+    findAll() will request all records and load them using 
+    store.loadRecords(). retrieveRecords() checks if the record is already 
+    loaded and in a clean state to then just materialize it or if is in an 
+    empty state, it will call this method to load the required record to 
+    then materialize it. 
+    
+    @param {SC.Store} store the requesting store
+    @param {Object} fetchKey key describing the request, may be SC.Record
+    @param {Hash} params optional additonal fetch params
+    @returns {SC.Array} result set with storeKeys.  
+  */  
+  fetch: function(store, fetchKey, params) {
+    
+    var ret = [], fixtures;
+    
+    // TODO: this currently only supports one recordType per SC.Query
+    if(SC.instanceOf(fetchKey, SC.Query)) {
+      fetchKey = fetchKey.recordType;
+    }
+    
+    if(SC.typeOf(fetchKey)===SC.T_STRING) {
+      fetchKey = SC.objectForPropertyPath(fetchKey);
+    }
+    
+    if(fetchKey === SC.Record || SC.Record.hasSubclass(fetchKey)) {
+      this.loadFixturesFor(store, fetchKey, ret);
+    }
+    
+    return ret;
+  },
+  
+  /**
+    Load fixtures for a given fetchKey into the store
+    and push it to the ret array.
+    
+    @param {SC.Store} store
+    @param {SC.Record} fetchKey
+    @param {SC.Array} ret
+  */
+  loadFixturesFor: function(store, fetchKey, ret) {
+    var dataHashes, i, storeKey, hashes = [];
+    
+    dataHashes = this.fixturesFor(fetchKey);
+    
+    for(i in dataHashes){
+      storeKey = fetchKey.storeKeyFor(i);
+      hashes.push(dataHashes[i]);
+      ret.push(storeKey);
+    }
+    
+    // before loading fixtures again, make sure they have not been
+    // loaded already, so that SC.Query does not end up in 
+    // infinite loop
+    if(!this.fixturesLoadedFor(fetchKey)) {
+      store.loadRecords(fetchKey, hashes);
+    }
+    
+  },
+  
+  /**
+    Load fixtures for a given fetchKey into the store
+    and push it to the ret array.
+    
+    @param {SC.Store} store
+    @param {SC.Record} fetchKey
+    @param {SC.Array} ret
+  */
+  loadFixturesFor: function(store, fetchKey, ret) {
+    var dataHashes, i, storeKey, hashes = [];
+    dataHashes = this.fixturesFor(fetchKey);
+    for(i in dataHashes){
+      storeKey = fetchKey.storeKeyFor(i);
+      hashes.push(dataHashes[i]);
+      ret.push(storeKey);
+    }
+    store.loadRecords(fetchKey, hashes);
+  },
+  
+  /**
+    Load fixtures for a given fetchKey into the store
+    and push it to the ret array.
+    
+    @param {SC.Store} store
+    @param {SC.Record} fetchKey
+    @param {SC.Array} ret
+  */
+  loadFixturesFor: function(store, fetchKey, ret) {
+    var dataHashes, i, storeKey, hashes = [];
+    dataHashes = this.fixturesFor(fetchKey);
+    for(i in dataHashes){
+      storeKey = fetchKey.storeKeyFor(i);
+      hashes.push(dataHashes[i]);
+      ret.push(storeKey);
+    }
+    store.loadRecords(fetchKey, hashes);
+  },
+  
+  /**
+    Retrieve a record from fixtures.
+    
+    @param {SC.Store} store
+    @param {Number} storeKey
+    @param {SC.Array} ret
+  */
+  retrieveRecord: function(store, storeKey) {
+    var ret = [], recordType = SC.Store.recordTypeFor(storeKey),
+        id = store.idFor(storeKey),
+        hash = this.fixtureForStoreKey(store, storeKey);
+    ret.push(storeKey);
+    store.dataSourceDidComplete(storeKey, hash, id);
+    
+    return ret;
+  },
+  
+  /**
+    Fixture operations complete immediately so you cannot cancel them.
+    
+    @param {SC.Store} store
+    @param {SC.Array} storeKeys
+    @returns {Boolean} YES if handled
+  */
+  cancel: function(store, storeKeys) {
+    return NO;
+  },
+  
+  /**
+    Update the dataHash in this._fixtures
+    
+    @param {SC.Store} store
+    @param {Number} storeKey
+    @returns {Boolean} YES if handled
+  */
+  updateRecord: function(store, storeKey) {
+    this.setFixtureForStoreKey(store, storeKey, store.readDataHash(storeKey));
+    store.dataSourceDidComplete(storeKey);  
+    return YES ;
+  },
+
+  /**
+    Adds records to this._fixtures.  If the record does not have an id yet,
+    then then calls generateIdFor() and sets that.
+    
+    @param {SC.Store} store the store
+    @param {Number} storeKey the store key
+    @returns {Boolean} YES if successful
+  */
+  createRecord: function(store, storeKey) {
+    var id         = store.idFor(storeKey),
+        recordType = store.recordTypeFor(storeKey),
+        dataHash   = store.readDataHash(storeKey), 
+        fixtures   = this.fixturesFor(recordType);
+        
+    if (!id) id = this.generateIdFor(recordType, dataHash, store, storeKey);
+    this._invalidateCachesFor(recordType, storeKey, id);
+    fixtures[id] = dataHash;
+
+    store.dataSourceDidComplete(storeKey, null, id);
+    return YES ;
+  },
+
+  /**
+    Removes the data from the fixtures.  
+    
+    @param {SC.Store} store the store
+    @param {Number} storeKey the store key
+    @returns {Boolean} YES if successful
+  */
+  destroyRecord: function(store, storeKey) {
+    var id         = store.idFor(storeKey),
+        recordType = store.recordTypeFor(storeKey),
+        fixtures   = this.fixturesFor(recordType);
+
+    this._invalidateCachesFor(recordType, storeKey, id);
+    if (id) delete fixtures[id];
+    store.dataSourceDidDestroy(storeKey);  
+    return YES ;
+  },
+  
+  // ..........................................................
+  // INTERNAL METHODS
+  // 
+
+  /**
+    Generates an id for the passed record type.  You can override this if 
+    needed.  The default generates a storekey and formats it as a string.
+  */
+  generateIdFor: function(recordType, dataHash, store, storeKey) {
+    return "@id%@".fmt(SC.Store.generateStoreKey());
+  },
+  
+  /**
+    Based on the storeKey it returns the specified fixtures
+    
+    @param {SC.Store} store the store 
+    @param {Number} storeKey the storeKey
+    @returns {Hash} data hash or null
+  */
+  fixtureForStoreKey: function(store, storeKey) {
+    var id         = store.idFor(storeKey),
+        recordType = store.recordTypeFor(storeKey),
+        fixtures   = this.fixturesFor(recordType);
+    return fixtures ? fixtures[id] : null;
+  },
+  
+  /**
+    Sets the data hash fixture for the named store key.  
+    
+    @param {SC.Store} store the store 
+    @param {Number} storeKey the storeKey
+    @param {Hash} dataHash 
+    @returns {SC.FixturesDataSource} receiver
+  */
+  setFixtureForStoreKey: function(store, storeKey, dataHash) {
+    var id         = store.idFor(storeKey),
+        recordType = store.recordTypeFor(storeKey),
+        fixtures   = this.fixturesFor(recordType);
+    this._invalidateCachesFor(recordType, storeKey, id);
+    fixtures[id] = dataHash;
+    return this ;
+  },
+  
+  /** 
+    Invoked methods to ensure fixtures for a particular record type have been
+    loaded.
+    
+    @param {SC.Record} recordType
+    @returns {Hash} data hashes
+  */
+  fixturesFor: function(recordType) {
+    // get basic fixtures hash.
+    if (!this._fixtures) this._fixtures = {};
+    var fixtures = this._fixtures[SC.guidFor(recordType)];
+    if (fixtures) return fixtures ; 
+    
+    // need to load fixtures.
+    var dataHashes = recordType ? recordType.FIXTURES : null,
+        len        = dataHashes ? dataHashes.length : 0,
+        primaryKey = recordType ? recordType.prototype.primaryKey : 'guid',
+        idx, dataHash, id ;
+
+    this._fixtures[SC.guidFor(recordType)] = fixtures = {} ; 
+    for(idx=0;idx<len;idx++) {      
+      dataHash = dataHashes[idx];
+      id = dataHash[primaryKey];
+      if (!id) id = this.generateIdFor(recordType, dataHash); 
+      fixtures[id] = dataHash;
+    }  
+    return fixtures;
+  },
+  
+  /**
+    Returns YES is fixtures for a given recordType have already been loaded
+    
+    @param {SC.Record} recordType
+    @returns {Boolean} storeKeys
+  */
+  fixturesLoadedFor: function(recordType) {
+    if (!this._fixtures) return NO;
+    var ret = [], fixtures = this._fixtures[SC.guidFor(recordType)];
+    return fixtures ? YES: NO;
+  },
+  
+  /**
+    Invalidates any internal caches based on the recordType and optional 
+    other parameters.  Currently this only invalidates the storeKeyCache used
+    for fetch, but it could invalidate others later as well.
+    
+    @param {SC.Record} recordType the type of record modified
+    @param {Number} storeKey optional store key
+    @param {String} id optional record id
+    @returns {SC.FixturesDataSource} receiver
+  */
+  _invalidateCachesFor: function(recordType, storeKey, id) {
+    var cache = this._storeKeyCache;
+    if (cache) delete cache[SC.guidFor(recordType)]
+    return this ;
+  }
+  
+});
+
+// create default instance for use when configuring
+SC.Record.fixtures = SC.FixturesDataSource.create();