sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/datastore/models/record_attribute.js

@@ -0,0 +1,361 @@
+// ==========================================================================
+// 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('models/record');
+
+/** @class
+
+  A RecordAttribute describes a single attribute on a record.  It is used to
+  generate computed properties on records that can automatically convert data
+  types and verify data.
+  
+  You usually will not work with RecordAttribute objects directly, though you
+  may extend the class in any way that you like to create a custom attribute.
+
+  A number of default RecordAttribute types are defined on the SC.Record.
+  
+  @extends SC.Object
+  @since SproutCore 1.0
+*/
+SC.RecordAttribute = SC.Object.extend(
+  /** @scope SC.RecordAttribute.prototype */ {
+
+  /**
+    The default value.  If attribute is null or undefined, this default value
+    will be substituted instead.  Note that defaultValues are not converted
+    so the value should be in the output type expected by the attribute.
+    
+    @property {Object}
+  */
+  defaultValue: null,
+  
+  /**
+    The attribute type.  Must be either an object class or a property path
+    naming a class.  The built in handler allows all native types to pass 
+    through, converts records to ids and dates to UTF strings.
+    
+    If you use the attr() helper method to create a RecordAttribute instance,
+    it will set this property to the first parameter you pass.
+    
+    @property {Object|String}
+  */
+  type: String,
+  
+  /**
+    The underlying attribute key name this attribute should manage.  If this
+    property is left empty, then the key will be whatever property name this
+    attribute assigned to on the record.  If you need to provide some kind
+    of alternate mapping, this provides you a way to override it.
+    
+    @property {String}
+  */
+  key: null,
+  
+  /**
+    If YES, then the attribute is required and will fail validation unless
+    the property is set to a non-null or undefined value.
+    
+    @property {Boolean}
+  */
+  isRequired: NO,
+  
+  /**
+    If NO then attempts to edit the attribute will be ignored.
+    
+    @property {Boolean}
+  */
+  isEditable: YES,  
+  
+  /**
+    If set when using the Date format, expect the ISO8601 date format.  
+    This is the default.
+    
+    @property {Boolean}
+  */
+  useIsoDate: YES,
+  
+  // ..........................................................
+  // HELPER PROPERTIES
+  // 
+  
+  /**
+    Returns the type, resolved to a class.  If the type property is a regular
+    class, returns the type unchanged.  Otherwise attempts to lookup the 
+    type as a property path.
+    
+    @property {Object}
+  */
+  typeClass: function() {
+    var ret = this.get('type');
+    if (SC.typeOf(ret) === SC.T_STRING) ret = SC.objectForPropertyPath(ret);
+    return ret ;
+  }.property('type').cacheable(),
+  
+  /**
+    Finds the transform handler. 
+  */
+  transform: function() {
+    var klass      = this.get('typeClass') || String,
+        transforms = SC.RecordAttribute.transforms,
+        ret ;
+    
+    // walk up class hierarchy looking for a transform handler
+    while(klass && !(ret = transforms[SC.guidFor(klass)])) {
+      klass = klass.superclass ;
+    }
+    
+    return ret ;
+  }.property('typeClass').cacheable(),
+  
+  // ..........................................................
+  // LOW-LEVEL METHODS
+  // 
+  
+  /** 
+    Converts the passed value into the core attribute value.  This will apply 
+    any format transforms.  You can install standard transforms by adding to
+    the SC.RecordAttribute.transforms hash.  See 
+    SC.RecordAttribute.registerTransform() for more.
+    
+    @param {SC.Record} record the record instance
+    @param {String} key the key used to access this attribute on the record
+    @param {Object} value the property value
+    @returns {Object} attribute value
+  */
+  toType: function(record, key, value) {
+    var transform = this.get('transform'),
+        type      = this.get('typeClass');
+    if (transform && transform.to) {
+      value = transform.to(value, this, type, record, key) ;
+    }
+    return value ;        
+  },
+
+  /** 
+    Converts the passed value from the core attribute value.  This will apply 
+    any format transforms.  You can install standard transforms by adding to
+    the SC.RecordAttribute.transforms hash.  See 
+    SC.RecordAttribute.registerTransform() for more.
+
+    @param {SC.Record} record the record instance
+    @param {String} key the key used to access this attribute on the record
+    @param {Object} value the property value
+    @returns {Object} attribute value
+  */
+  fromType: function(record, key, value) {
+    var transform = this.get('transform'),
+        type      = this.get('typeClass');
+    if (transform && transform.from) {
+      value = transform.from(value, this, type, record, key);
+    }
+    return value;
+  },
+
+  /**
+    The core handler.  Called from the property.
+    
+    @param {SC.Record} record the record instance
+    @param {String} key the key used to access this attribute on the record
+    @param {Object} value the property value if called as a setter
+    @returns {Object} property value
+  */
+  call: function(record, key, value) {
+    var attrKey = this.get('key') || key;
+    
+    if (value !== undefined) {
+      value = this.fromType(record, key, value) ; // convert to attribute.
+      record.writeAttribute(attrKey, value);
+    } else {
+      value = record.readAttribute(attrKey);
+      if (SC.none(value) && (value = this.get('defaultValue'))) {
+        if (typeof value === SC.T_FUNCTION) {
+          value = this.defaultValue(record, key, this);
+        }
+      } else value = this.toType(record, key, value);
+    }
+    return value ;
+  },
+
+  // ..........................................................
+  // INTERNAL SUPPORT
+  // 
+  
+  /** @private - Make this look like a property so that get() will call it. */
+  isProperty: YES,
+  
+  /** @private - Make this look cacheable */
+  isCacheable: YES,
+  
+  /** @private - needed for KVO property() support */
+  dependentKeys: [],
+  
+  /** @private */
+  init: function() {
+    sc_super();
+    // setup some internal properties needed for KVO - faking 'cacheable'
+    this.cacheKey = "__cache__" + SC.guidFor(this) ;
+    this.lastSetValueKey = "__lastValue__" + SC.guidFor(this) ;
+  }
+  
+}) ;
+
+// ..........................................................
+// CLASS METHODS
+// 
+
+/**
+  The default method used to create a record attribute instance.  Unlike 
+  create(), takes an attributeType as the first parameter which will be set 
+  on the attribute itself.  You can pass a string naming a class or a class
+  itself.
+  
+  @param {Object|String} attributeType the assumed attribute type
+  @param {Hash} opts optional additional config options
+  @returns {SC.RecordAttribute} new instance
+*/
+SC.RecordAttribute.attr = function(attributeType, opts) {
+  if (!opts) opts = {} ;
+  if (!opts.type) opts.type = attributeType || String ;
+  return this.create(opts);
+};
+
+/** @private
+  Hash of registered transforms by class guid. 
+*/
+SC.RecordAttribute.transforms = {};
+
+/**
+  Call to register a transform handler for a specific type of object.  The
+  object you pass can be of any type as long as it responds to the following
+  methods:
+
+  | *to(value, attr, klass, record, key)* | converts the passed value (which will be of the class expected by the attribute) into the underlying attribute value |
+  | *from(value, attr, klass, record, key)* | converts the underyling attribute value into a value of the class |
+  
+  @param {Object} klass the type of object you convert
+  @param {Object} transform the transform object
+  @returns {SC.RecordAttribute} receiver
+*/
+SC.RecordAttribute.registerTransform = function(klass, transform) {
+  SC.RecordAttribute.transforms[SC.guidFor(klass)] = transform;  
+};
+
+// ..........................................................
+// STANDARD ATTRIBUTE TRANSFORMS
+// 
+
+// Object, String, Number just pass through.
+
+/** @private - generic converter for Boolean records */
+SC.RecordAttribute.registerTransform(Boolean, {
+  /** @private - convert an arbitrary object value to a boolean */
+  to: function(obj) {
+    return SC.none(obj) ? null : !!obj;
+  }
+});
+
+/** @private - generic converter for Numbers */
+SC.RecordAttribute.registerTransform(Number, {
+  /** @private - convert an arbitrary object value to a Number */
+  to: function(obj) {
+    return SC.none(obj) ? null : Number(obj) ;
+  }
+});
+
+/** @private - generic converter for Strings */
+SC.RecordAttribute.registerTransform(String, {
+  /** @private - 
+    convert an arbitrary object value to a String 
+    allow null through as that will be checked separately
+  */
+  to: function(obj) {
+    if (!(typeof obj === SC.T_STRING) && !SC.none(obj) && obj.toString) {
+      obj = obj.toString();
+    }
+    return obj;
+  }
+});
+
+/** @private - generic converter for SC.Record-type records */
+SC.RecordAttribute.registerTransform(SC.Record, {
+
+  /** @private - convert a record id to a record instance */
+  to: function(id, attr, recordType, parentRecord) {
+    var store = parentRecord.get('store');
+    return store.find(recordType, id);
+  },
+  
+  /** @private - convert a record instance to a record id */
+  from: function(record) { return record.get('id'); }
+});
+
+/** @private - generic converter for Date records */
+SC.RecordAttribute.registerTransform(Date, {
+
+  /** @private - convert a string to a Date */
+  to: function(str, attr) {
+    var ret ;
+    
+    if (attr.get('useIsoDate')) {
+      var regexp = "([0-9]{4})(-([0-9]{2})(-([0-9]{2})" +
+             "(T([0-9]{2}):([0-9]{2})(:([0-9]{2})(\\.([0-9]+))?)?" +
+             "(Z|(([-+])([0-9]{2}):([0-9]{2})))?)?)?)?",
+          d      = str.match(new RegExp(regexp)),
+          offset = 0,
+          date   = new Date(d[1], 0, 1),
+          time ;
+
+      if (d[3]) { date.setMonth(d[3] - 1); }
+      if (d[5]) { date.setDate(d[5]); }
+      if (d[7]) { date.setHours(d[7]); }
+      if (d[8]) { date.setMinutes(d[8]); }
+      if (d[10]) { date.setSeconds(d[10]); }
+      if (d[12]) { date.setMilliseconds(Number("0." + d[12]) * 1000); }
+      if (d[14]) {
+         offset = (Number(d[16]) * 60) + Number(d[17]);
+         offset *= ((d[15] == '-') ? 1 : -1);
+      }
+
+      offset -= date.getTimezoneOffset();
+      time = (Number(date) + (offset * 60 * 1000));
+      
+      ret = new Date();
+      ret.setTime(Number(time));
+    } else ret = Date.parse(str);
+    return ret ;
+  },
+  
+  _dates: {},
+
+  _zeropad: function(num) { 
+    return ((num<0) ? '-' : '') + ((num<10) ? '0' : '') + Math.abs(num); 
+  },
+  
+  /** @private - convert a date to a string */
+  from: function(date) { 
+    var ret = this._dates[date.getTime()];
+    if (ret) return ret ; 
+    
+    // figure timezone
+    var zp = this._zeropad,
+        tz = 0-date.getTimezoneOffset()/60;
+        
+    tz = (tz === 0) ? 'Z' : '%@:00'.fmt(zp(tz));
+    
+    this._dates[date.getTime()] = ret = "%@-%@-%@T%@:%@:%@%@".fmt(
+      zp(date.getFullYear()),
+      zp(date.getMonth()+1),
+      zp(date.getDate()),
+      zp(date.getHours()),
+      zp(date.getMinutes()),
+      zp(date.getSeconds()),
+      tz) ;
+    
+    return ret ;
+  }
+});
+

data/frameworks/sproutcore/frameworks/datastore/system/nested_store.js

@@ -0,0 +1,305 @@
+// ==========================================================================
+// 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('system/store');
+
+/**
+  @class
+
+  A nested store can buffer changes to a parent store and then commit them
+  all at once.  You usually will use a NestedStore as part of store chaining
+  to stage changes to your object graph before sharing them with the rest of
+  the application.
+  
+  Normally you will not create a nested store directly.  Instead, you can 
+  retrieve a nested store by using the chain() method.  When you are finished
+  working with the nested store, destroy() will dispose of it.
+  
+  @extends SC.Store
+  @since SproutCore 1.0
+*/
+SC.NestedStore = SC.Store.extend(
+/** @scope SC.NestedStore.prototype */ {
+
+  /**
+    This is set to YES when there are changes that have not been committed 
+    yet.
+
+    @property
+    @type {Boolean}
+    @default NO
+  */
+  hasChanges: NO,
+
+  /**
+    The parent store this nested store is chained to.  Nested stores must have
+    a parent store in order to function properly.  Normally, you create a 
+    nested store using the SC.Store#chain() method and this property will be
+    set for you.
+    
+    @property {SC.Store}
+  */
+  parentStore: null,
+
+  /**
+    YES if the view is nested. Walk like a duck
+  */
+  isNested: YES,
+
+  /**
+    If YES, then the attribute hash state will be locked when you first 
+    read the data hash or status.  This means that if you retrieve a record
+    then change the record in the parent store, the changes will not be 
+    visible to your nested store until you commit or discard changes.
+    
+    If NO, then the attribute hash will lock only when you write data.
+    
+    Normally you want to lock your attribute hash the first time you read it.
+    This will make your nested store behave most consistently.  However, if
+    you are using multiple sibling nested stores at one time, you may want
+    to turn off this property so that changes from one store will be reflected
+    in the other one immediately.  In this case you will be responsible for
+    ensuring that the sibling stores do not edit the same part of the object
+    graph at the same time.
+    
+    @property {Boolean} 
+  */
+  lockOnRead: YES,
+
+  /** @private
+    Array contains the base revision for an attribute hash when it was first
+    cloned from the parent store.  If the attribute hash is edited and 
+    commited, the commit will fail if the parent attributes hash has been 
+    edited since.
+    
+    This is a form of optimistic locking, hence the name.
+    
+    Each store gets its own array of locks, which are selectively populated
+    as needed.
+    
+    Note that this is kept as an array because it will be stored as a dense 
+    array on some browsers, making it faster.
+    
+    @property {Array}
+  */
+  locks: null,
+
+  /** @private
+    An array that includes the store keys that have changed since the store
+    was last committed.  This array is used to sync data hash changes between
+    chained stores.  For a log changes that may actually be committed back to
+    the server see the changelog property.
+    
+    @property {Array}
+  */
+  chainedChanges: null,
+    
+  // ..........................................................
+  // STORE CHAINING
+  // 
+  
+  /**
+    Resets a store's data hash contents to match its parent.
+    
+    @returns {SC.Store} receiver
+  */
+  reset: function() {
+    console.error('not implemented');
+  },
+  
+  /**
+    Propagate this store's changes to it's parent.  If the store does not 
+    have a parent, this has no effect other than to clear the change set.
+
+    @param {Boolean} force if YES, does not check for conflicts first
+    @returns {SC.Store} receiver
+  */
+  commitChanges: function(force) {
+    var pstore = this.get('parentStore');
+    pstore.commitChangesFromNestedStore(this, this.chainedChanges, force);
+    this.reset(); // clear out custom changes 
+    return this ;
+  },
+
+  /**
+    Discard the changes made to this store and reset the store.
+    
+    @returns {SC.Store} receiver
+  */
+  discardChanges: function() {
+    console.error('not implemented');
+  },
+  
+  /**
+    When you are finished working with a chained store, call this method to 
+    tear it down.  This will also discard any pending changes.
+    
+    @returns {SC.Store} receiver
+  */
+  destroy: function() {
+    console.error('not implemented');
+  },
+
+  /**
+    Resets a store's data hash contents to match its parent.
+    
+    @returns {SC.Store} receiver
+  */
+  reset: function() {
+    console.error('not implemented');
+  },
+  
+  // ..........................................................
+  // CORE ATTRIBUTE API
+  // 
+  // The methods in this layer work on data hashes in the store.  They do not
+  // perform any changes that can impact records.  Usually you will not need 
+  // to use these methods.
+  
+  /**
+    Returns the current edit status of a storekey.  May be one of INHERITED,
+    EDITABLE, and LOCKED.  Used mostly for unit testing.
+    
+    @param {Number} storeKey the store key
+    @returns {Number} edit status
+  */
+  storeKeyEditState: function(storeKey) {
+    console.error('not implemented');
+  },
+   
+  /**  @private
+    Locks the data hash so that it iterates independently from the parent 
+    store.
+  */
+  _lock: function(storeKey) {
+    console.error('not implemented');
+  },
+  
+  /** @private - adds chaining support */
+  readDataHash: function(storeKey) {
+    console.error('not implemented');
+  },
+  
+  /** @private - adds chaining support */
+  readEditableDataHash: function(storeKey) {
+    console.error('not implemented');
+  },
+  
+  /** @private - adds chaining support - 
+    Does not call sc_super because the implementation of the method vary too
+    much. 
+  */
+  writeDataHash: function(storeKey, hash, status) {
+    console.error('not implemented');
+  },
+
+  /** @private - adds chaining support */
+  removeDataHash: function(storeKey, status) {
+    console.error('not implemented');
+  },
+  
+  /** @private - book-keeping for a single data hash. */
+  dataHashDidChange: function(storeKeys, rev) {
+    console.error('not implemented');
+  },
+
+  // ..........................................................
+  // SYNCING CHANGES
+  // 
+  
+  /** @private - adapt for nested store */
+  commitChangesFromNestedStore: function(nestedStore, changes, force) {
+    console.error('not implemented');
+  },
+
+  // ..........................................................
+  // HIGH-LEVEL RECORD API
+  // 
+  
+  
+  /** @private - adapt for nested store */
+  findAll: function(queryKey, params, _store) { 
+    console.error('not implemented');
+  },
+
+  // ..........................................................
+  // CORE RECORDS API
+  // 
+  // The methods in this section can be used to manipulate records without 
+  // actually creating record instances.
+  
+  /** @private - adapt for nested store */
+  retrieveRecords: function(recordTypes, ids, storeKeys, _isRefresh) {
+    console.error('not implemented');
+  },
+
+  /** @private - adapt for nested store */
+  commitRecords: function(recordTypes, ids, storeKeys) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+
+  /** @private - adapt for nested store */
+  commitRecord: function(recordType, id, storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+  
+  /** @private - adapt for nested store */
+  cancelRecords: function(recordTypes, ids, storeKeys) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+
+  /** @private - adapt for nested store */
+  cancelRecord: function(recordType, id, storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+  
+  // ..........................................................
+  // DATA SOURCE CALLBACKS
+  // 
+  // Mathods called by the data source on the store
+
+  /** @private - adapt for nested store */
+  dataSourceDidCancel: function(storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+  
+  /** @private - adapt for nested store */
+  dataSourceDidComplete: function(storeKey, dataHash, newId) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+  
+  /** @private - adapt for nested store */
+  dataSourceDidDestroy: function(storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+
+  /** @private - adapt for nested store */
+  dataSourceDidError: function(storeKey, error) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+
+  // ..........................................................
+  // PUSH CHANGES FROM DATA SOURCE
+  // 
+  
+  /** @private - adapt for nested store */
+  pushRetrieve: function(recordType, id, dataHash, storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+  
+  /** @private - adapt for nested store */
+  pushDestroy: function(recordType, id, storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  },
+
+  /** @private - adapt for nested store */
+  pushError: function(recordType, id, error, storeKey) {
+    throw SC.Store.NESTED_STORE_UNSUPPORTED_ERROR;
+  }
+  
+}) ;
+