sproutit-sproutcore 1.0.0.20090416161445 → 1.0.0.20090720093355

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

@@ -57,7 +57,7 @@ SC.CascadeDataSource = SC.DataSource.extend(
     
     for(idx=0;idx<len;idx++) {
       source = sources.objectAt(idx);
-      cur = source.retrieveRecords.call(this, store, storeKeys);
+      cur = source.fetchRecords.call(this, store, SC.Record.STORE_KEYS, storeKeys);
       ret = this._handleResponse(ret, cur);
       if (ret === YES) return YES ;
     }
@@ -73,7 +73,7 @@ SC.CascadeDataSource = SC.DataSource.extend(
     
     for(idx=0;idx<len;idx++) {
       source = sources.objectAt(idx);
-      cur = source.retrieveRecords.call(this, store, createStoreKeys, updateStoreKeys, destroyStoreKeys);
+      cur = source.commitRecords.call(this, store, createStoreKeys, updateStoreKeys, destroyStoreKeys);
       ret = this._handleResponse(ret, cur);
       if (ret === YES) return YES ;
     }

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

@@ -19,31 +19,64 @@ SC.DataSource = SC.Object.extend( /** SC.DataSource.prototype */ {
   // SC.STORE ENTRY POINTS
   // 
   
+
   /**
-    Invoked by the Store to load or refresh records in the store.  You can 
-    map the storeKeys back to recordType and ids as needed to perform the 
-    retrieval.
+    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.
     
-    Typically you will override this method to initial a retrieval for the
-    records and then provide the data to the store using the standard data
-    source callbacks on the store.
+    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.
     
-    If you are implementing an in-memory data source, you can provide this 
-    data immediately if you want before returning.
+    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.
     
-    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.
+    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.DataSource} dataSource the receiver
     @param {SC.Store} store the requesting store
-    @param {Array} storeKeys array of storeKeys to retrieve
-    @returns {Boolean} YES if data source can handle keys
+    @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.
   */
-  retrieveRecords: function(store, storeKeys) {
-    return NO;    
+  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
@@ -79,36 +112,6 @@ SC.DataSource = SC.Object.extend( /** SC.DataSource.prototype */ {
     return (cret === uret === dret) ? (cret || uret || dret) : SC.MIXED_STATE ;
   },
   
-  /**
-    Invoked by the store whenever it needs to retrieve an array of storeKeys
-    matching a specific query.  Your subclass should override this method 
-    to return an array of storeKeys that match the passed fetchKey and 
-    optional params.  Often the fetchKey will actually be an SC.Record 
-    subclass used as a filter or string, but it could be anything you want.
-    
-    If your data source subclass can handle the fetch, it should either return
-    an array of storeKeys immediately or it can return an empty array and 
-    populate it dynamically later one the result set has arrived.  Optionally
-    you can also implement "server-side results" by returning a SparseArray
-    and then dynamically populating the contents of the array as it is 
-    requested.
-    
-    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.
-    
-    @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.  May be sparse.
-  */
-  fetchRecords: function(store, fetchKey, params) {
-    return null;  
-  },
-  
-  
   /**
     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
@@ -188,10 +191,12 @@ SC.DataSource = SC.Object.extend( /** SC.DataSource.prototype */ {
   /** @private
     invokes the named action for each store key.  returns proper value
   */
-  _handleEach: function(store, storeKeys, action) {
+  _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]);
+      cur = action.call(this, store, storeKeys[idx], ids[idx]);
       if (ret === undefined) {
         ret = cur ;
       } else if (ret === YES) {
@@ -223,6 +228,18 @@ SC.DataSource = SC.Object.extend( /** SC.DataSource.prototype */ {
     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.

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

@@ -22,57 +22,142 @@ SC.FixturesDataSource = SC.DataSource.extend( {
   // 
   
   /**
-     Invoked by the store whenever it needs to retrieve an array of records.
-
-     @param {SC.Store} store the requesting store
-     @param {SC.Array} the array with the storeKeys to be retrieved
-     @returns {SC.Bool} return YES because Fixtures supports the function.  
-  */
-  retrieveRecords: function(store, storeKeys) {
-    var len = storeKeys.length, dataHash, storeKey, i;
-    for(i=0; i<len; i++){
-      storeKey = storeKeys[i];
-      dataHash = this.fixtureForStoreKey(store, storeKey);
-      if (dataHash) store.dataSourceDidComplete(storeKey, dataHash);
+    
+    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 YES;    
+    
+    return ret;
   },
-
+  
   /**
-    Invoked by the store whenever it needs to retrieve an array of storeKeys
-    matching a specific query.  For the fixtures params are ignored and all 
-    storeKeys for the specific recordType are returned.
+    Load fixtures for a given fetchKey into the store
+    and push it to the ret array.
     
-    @param {SC.Store} store the requesting store
-    @param {Object} recordType key describing the request, may be SC.Record
-    @param {Hash} params optional additonal fetch params
-    @returns {SC.Array} result set with storeKeys.  May be sparse.
+    @param {SC.Store} store
+    @param {SC.Record} fetchKey
+    @param {SC.Array} ret
   */
-  fetchRecords: function(store, recordType, params) {
-    var ret = [], dataHashes, i, storeKey;
+  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);
+    }
     
-    // only support loading records
-    if (!(recordType === SC.Record || SC.Record.hasSubclass(recordType))) {
-      return null ;
+    // 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.
     
-    dataHashes = this.fixturesFor(recordType);
+    @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 = recordType.storeKeyFor(i);
+      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));
@@ -80,7 +165,6 @@ SC.FixturesDataSource = SC.DataSource.extend( {
     return YES ;
   },
 
-
   /**
     Adds records to this._fixtures.  If the record does not have an id yet,
     then then calls generateIdFor() and sets that.
@@ -96,6 +180,7 @@ SC.FixturesDataSource = SC.DataSource.extend( {
         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);
@@ -113,7 +198,8 @@ SC.FixturesDataSource = SC.DataSource.extend( {
     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 ;
@@ -157,6 +243,7 @@ SC.FixturesDataSource = SC.DataSource.extend( {
     var id         = store.idFor(storeKey),
         recordType = store.recordTypeFor(storeKey),
         fixtures   = this.fixturesFor(recordType);
+    this._invalidateCachesFor(recordType, storeKey, id);
     fixtures[id] = dataHash;
     return this ;
   },
@@ -188,6 +275,34 @@ SC.FixturesDataSource = SC.DataSource.extend( {
       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 ;
   }
   
 });

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

@@ -0,0 +1,238 @@
+// ==========================================================================
+// 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');
+sc_require('system/query');
+
+/** @class
+
+  TODO: Describe Class
+  
+  @extends SC.DataSource
+  @since SproutCore 1.0
+*/
+SC.FixturesWithQueriesDataSource = SC.DataSource.extend( {
+
+  // ..........................................................
+  // PREDEFINED EXAMPLE QUERIES
+  //
+  
+  queries: {
+    nameIs: SC.Query.create({queryString: "name = %@"}),
+    countIsLesserThan: SC.Query.create({queryString: "count < %@"})
+  },
+  
+  
+  // ..........................................................
+  // STANDARD DATA SOURCE METHODS
+  // 
+  
+  /**
+     Invoked by the store whenever it needs to retrieve an array of records.
+
+     @param {SC.Store} store the requesting store
+     @param {SC.Array} the array with the storeKeys to be retrieved
+     @returns {SC.Bool} return YES because Fixtures supports the function.  
+  */
+  retrieveRecords: function(store, storeKeys) {
+    var len = storeKeys.length, dataHash, storeKey, i;
+    for(i=0; i<len; i++){
+      storeKey = storeKeys[i];
+      dataHash = this.fixtureForStoreKey(store, storeKey);
+      if (dataHash) store.dataSourceDidComplete(storeKey, dataHash);
+    }
+    return YES;    
+  },
+
+  /**
+    Invoked by the store whenever it needs to retrieve an array of storeKeys
+    matching a specific query.  For the fixtures params are ignored and all 
+    storeKeys for the specific recordType are returned.
+    
+    @param {SC.Store} store the requesting store
+    @param {Object} recordType key describing the request, may be SC.Record
+    @param {Hash} params optional additonal fetch params
+    @returns {SC.Array} result set with storeKeys.  May be sparse.
+  */
+  fetchRecords: function(store, queryKey, params) {
+    var ret = [], dataHashes, i, storeKey, recordType;
+    var query = null;
+    
+    if (!params) params = {};
+    
+    if (queryKey === SC.Record || SC.Record.hasSubclass(queryKey)) {
+      // loading by recordType now
+      recordType = queryKey;
+      dataHashes = this.fixturesFor(recordType);
+      for(i in dataHashes){
+        storeKey = recordType.storeKeyFor(i);
+        ret.push(storeKey);
+      }
+    } 
+    else if (typeof queryKey == 'string') {
+      // doing a real query now
+      // first check if this is a known query
+      if (this.queries[queryKey]) query = this.queries[queryKey];
+      // if not, make a new query and remember it
+      else {
+        params.queryString = queryKey;
+        query = this.queries[queryKey] = SC.Query.create(params);
+      }
+      
+      // now lets determine which records to check
+      if (query.recordType)
+        // !!! this doesn't work !!!
+        dataHashes = store.recordsFor(recordType);
+      else
+        // !!! this is a hack - but it works !!!
+        dataHashes = store.dataHashes;
+      
+      // now match the dataHashes against the query
+      for(i in dataHashes){
+        if (query.contains(dataHashes[i],params.parameters)) {
+          //storeKey = recordType.storeKeyFor(i);
+          ret.push(i);
+        }
+      }
+    }
+    
+    
+    
+    return ret;
+  },
+  
+  /**
+    Fixture operations complete immediately so you cannot cancel them.
+  */
+  cancel: function(store, storeKeys) {
+    return NO;
+  },
+  
+ /**
+    Update the dataHash in this._fixtures
+  */
+  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);
+    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);
+        
+    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);
+    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;
+  }
+  
+});
+
+// create default instance for use when configuring
+SC.Record.fixturesWithQueries = SC.FixturesWithQueriesDataSource.create();