sproutcore 1.4.0-java

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/freezable.js

@@ -0,0 +1,110 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+
+/**
+  Standard Error that should be raised when you try to modify a frozen object.
+  
+  @property {Error}
+*/
+SC.FROZEN_ERROR = new Error("Cannot modify a frozen object");
+
+/** 
+  @namespace
+  
+  The SC.Freezable mixin implements some basic methods for marking an object
+  as frozen.  Once an object is frozen it should be read only.  No changes 
+  may be made the internal state of the object.
+  
+  h2. Enforcement
+
+  To fully support freezing in your subclass, you must include this mixin and
+  override any method that might alter any property on the object to instead
+  raise an exception.  You can check the state of an object by checking the
+  isFrozen property.
+
+  Although future versions of JavaScript may support language-level freezing
+  object objects, that is not the case today.  Even if an object is freezable,
+  it is still technically possible to modify the object, even though it could
+  break other parts of your application that do not expect a frozen object to
+  change.  It is, therefore, very important that you always respect the 
+  isFrozen property on all freezable objects.
+  
+  h2. Example
+
+  The example below shows a simple object that implement the SC.Freezable 
+  protocol.  
+  
+  {{{
+    Contact = SC.Object.extend(SC.Freezable, {
+      
+      firstName: null,
+      
+      lastName: null,
+      
+      // swaps the names
+      swapNames: function() {
+        if (this.get('isFrozen')) throw SC.FROZEN_ERROR;
+        var tmp = this.get('firstName');
+        this.set('firstName', this.get('lastName'));
+        this.set('lastName', tmp);
+        return this;
+      }
+      
+    });
+    
+    c = Context.create({ firstName: "John", lastName: "Doe" });
+    c.swapNames();  => returns c
+    c.freeze();
+    c.swapNames();  => EXCEPTION
+    
+  }}}
+  
+  h2. Copying
+  
+  Usually the SC.Freezable protocol is implemented in cooperation with the
+  SC.Copyable protocol, which defines a frozenCopy() method that will return
+  a frozen object, if the object implements this method as well.
+  
+*/
+SC.Freezable = {
+  
+  /**
+    Walk like a duck.
+    
+    @property {Boolean}
+  */
+  isFreezable: YES,
+  
+  /**
+    Set to YES when the object is frozen.  Use this property to detect whether
+    your object is frozen or not.
+    
+    @property {Boolean}
+  */
+  isFrozen: NO,
+  
+  /**
+    Freezes the object.  Once this method has been called the object should
+    no longer allow any properties to be edited.
+    
+    @returns {Object} reciever
+  */
+  freeze: function() {
+    // NOTE: Once someone actually implements Object.freeze() in the browser,
+    // add a call to that here also.
+    
+    if (this.set) this.set('isFrozen', YES);
+    else this.isFrozen = YES;
+    return this;
+  }
+    
+};
+
+
+// Add to Array
+SC.mixin(Array.prototype, SC.Freezable);

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/observable.js

@@ -0,0 +1,1347 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+require('private/observer_set') ;
+
+/*globals logChange */
+
+/**
+  Set to YES to have all observing activity logged to the console.  This 
+  should be used for debugging only.
+  
+  @property {Boolean}
+*/
+SC.LOG_OBSERVERS = NO ;
+
+/**
+  @namespace 
+  
+  Key-Value-Observing (KVO) simply allows one object to observe changes to a 
+  property on another object. It is one of the fundamental ways that models, 
+  controllers and views communicate with each other in a SproutCore 
+  application.  Any object that has this module applied to it can be used in 
+  KVO-operations.
+  
+  This module is applied automatically to all objects that inherit from
+  SC.Object, which includes most objects bundled with the SproutCore 
+  framework.  You will not generally apply this module to classes yourself,
+  but you will use the features provided by this module frequently, so it is
+  important to understand how to use it.
+  
+  h2. Enabling Key Value Observing
+
+  With KVO, you can write functions that will be called automatically whenever 
+  a property on a particular object changes.  You can use this feature to
+  reduce the amount of "glue code" that you often write to tie the various 
+  parts of your application together.
+  
+  To use KVO, just use the KVO-aware methods get() and set() to access 
+  properties instead of accessing properties directly.  Instead of writing:
+  
+  {{{
+    var aName = contact.firstName ;
+    contact.firstName = 'Charles' ;
+  }}}
+
+  use:
+
+  {{{
+    var aName = contact.get('firstName') ;
+    contact.set('firstName', 'Charles') ;
+  }}}
+  
+  get() and set() work just like the normal "dot operators" provided by 
+  JavaScript but they provide you with much more power, including not only
+  observing but computed properties as well.
+
+  h2. Observing Property Changes
+
+  You typically observe property changes simply by adding the observes() 
+  call to the end of your method declarations in classes that you write.  For
+  example:
+  
+  {{{
+    SC.Object.create({
+      valueObserver: function() {
+        // Executes whenever the "Value" property changes
+      }.observes('value')
+    }) ;
+  }}}
+  
+  Although this is the most common way to add an observer, this capability is
+  actually built into the SC.Object class on top of two methods defined in
+  this mixin called addObserver() and removeObserver().  You can use these two
+  methods to add and remove observers yourself if you need to do so at run 
+  time.  
+  
+  To add an observer for a property, just call:
+  
+  {{{
+    object.addObserver('propertyKey', targetObject, targetAction) ;
+  }}}
+  
+  This will call the 'targetAction' method on the targetObject to be called
+  whenever the value of the propertyKey changes.
+  
+  h2. Observer Parameters
+  
+  An observer function typically does not need to accept any parameters, 
+  however you can accept certain arguments when writing generic observers. 
+  An observer function can have the following arguments:
+  
+  {{{
+    propertyObserver(target, key, value, revision) ;
+  }}}
+  
+  - *target* - This is the object whose value changed.  Usually this.
+  - *key* - The key of the value that changed
+  - *value* - this property is no longer used.  It will always be null
+  - *revision* - this is the revision of the target object
+  
+  h2. Implementing Manual Change Notifications
+  
+  Sometimes you may want to control the rate at which notifications for 
+  a property are delivered, for example by checking first to make sure 
+  that the value has changed.
+  
+  To do this, you need to implement a computed property for the property 
+  you want to change and override automaticallyNotifiesObserversFor().
+  
+  The example below will only notify if the "balance" property value actually
+  changes:
+  
+  {{{
+    
+    automaticallyNotifiesObserversFor: function(key) {
+      return (key === 'balance') ? NO : sc_super() ;
+    },
+    
+    balance: function(key, value) {
+      var balance = this._balance ;
+      if ((value !== undefined) && (balance !== value)) {
+        this.propertyWillChange(key) ;
+        balance = this._balance = value ;
+        this.propertyDidChange(key) ;
+      }
+      return balance ;
+    }
+    
+  }}}
+  
+  h1. Implementation Details
+  
+  Internally, SproutCore keeps track of observable information by adding a
+  number of properties to the object adopting the observable.  All of these
+  properties begin with "_kvo_" to separate them from the rest of your object.
+  
+  @static
+  @since SproutCore 1.0
+*/
+SC.Observable = {
+
+  /** 
+    Walk like that ol' duck 
+    
+    @property {Boolean}
+  */
+  isObservable: YES,
+  
+  /**
+    Determines whether observers should be automatically notified of changes
+    to a key.
+    
+    If you are manually implementing change notifications for a property, you
+    can override this method to return NO for properties you do not want the
+    observing system to automatically notify for.
+    
+    The default implementation always returns YES.
+    
+    @param key {String} the key that is changing
+    @returns {Boolean} YES if automatic notification should occur.
+  */
+  automaticallyNotifiesObserversFor: function(key) { 
+    return YES;
+  },
+
+  // ..........................................
+  // PROPERTIES
+  // 
+  // Use these methods to get/set properties.  This will handle observing
+  // notifications as well as allowing you to define functions that can be 
+  // used as properties.
+
+  /**  
+    Retrieves the value of key from the object.
+    
+    This method is generally very similar to using object[key] or object.key,
+    however it supports both computed properties and the unknownProperty
+    handler.
+    
+    *Computed Properties*
+    
+    Computed properties are methods defined with the property() modifier
+    declared at the end, such as:
+    
+    {{{
+      fullName: function() {
+        return this.getEach('firstName', 'lastName').compact().join(' ');
+      }.property('firstName', 'lastName')
+    }}}
+    
+    When you call get() on a computed property, the property function will be
+    called and the return value will be returned instead of the function
+    itself.
+    
+    *Unknown Properties*
+    
+    Likewise, if you try to call get() on a property whose values is
+    undefined, the unknownProperty() method will be called on the object.
+    If this method reutrns any value other than undefined, it will be returned
+    instead.  This allows you to implement "virtual" properties that are 
+    not defined upfront.
+    
+    @param key {String} the property to retrieve
+    @returns {Object} the property value or undefined.
+    
+  */
+  get: function(key) {
+    var ret = this[key], cache ;
+    if (ret === undefined) {
+      return this.unknownProperty(key) ;
+    } else if (ret && ret.isProperty) {
+      if (ret.isCacheable) {
+        cache = this._kvo_cache ;
+        if (!cache) cache = this._kvo_cache = {};
+        return (cache[ret.cacheKey] !== undefined) ? cache[ret.cacheKey] : (cache[ret.cacheKey] = ret.call(this,key)) ;
+      } else return ret.call(this,key);
+    } else return ret ;
+  },
+
+  /**  
+    Sets the key equal to value.
+    
+    This method is generally very similar to calling object[key] = value or
+    object.key = value, except that it provides support for computed 
+    properties, the unknownProperty() method and property observers.
+    
+    *Computed Properties*
+    
+    If you try to set a value on a key that has a computed property handler
+    defined (see the get() method for an example), then set() will call
+    that method, passing both the value and key instead of simply changing 
+    the value itself.  This is useful for those times when you need to 
+    implement a property that is composed of one or more member
+    properties.
+    
+    *Unknown Properties*
+    
+    If you try to set a value on a key that is undefined in the target 
+    object, then the unknownProperty() handler will be called instead.  This
+    gives you an opportunity to implement complex "virtual" properties that
+    are not predefined on the obejct.  If unknownProperty() returns 
+    undefined, then set() will simply set the value on the object.
+    
+    *Property Observers*
+    
+    In addition to changing the property, set() will also register a 
+    property change with the object.  Unless you have placed this call 
+    inside of a beginPropertyChanges() and endPropertyChanges(), any "local"
+    observers (i.e. observer methods declared on the same object), will be
+    called immediately.  Any "remote" observers (i.e. observer methods 
+    declared on another object) will be placed in a queue and called at a
+    later time in a coelesced manner.
+    
+    *Chaining*
+    
+    In addition to property changes, set() returns the value of the object
+    itself so you can do chaining like this:
+    
+    {{{
+      record.set('firstName', 'Charles').set('lastName', 'Jolley');
+    }}}
+    
+    @param key {String} the property to set
+    @param value {Object} the value to set or null.
+    @returns {SC.Observable}
+  */
+  set: function(key, value) {
+    var func   = this[key], 
+        notify = this.automaticallyNotifiesObserversFor(key),
+        ret    = value, 
+        cachedep, cache, idx, dfunc ;
+
+    // if there are any dependent keys and they use caching, then clear the
+    // cache.  (If we're notifying, then propertyDidChange will do this for
+    // us.)
+    if (!notify && this._kvo_cacheable && (cache = this._kvo_cache)) {
+      // lookup the cached dependents for this key.  if undefined, compute.
+      // note that if cachdep is set to null is means we figure out it has no
+      // cached dependencies already.  this is different from undefined.
+      cachedep = this._kvo_cachedep;
+      if (!cachedep || (cachedep = cachedep[key])===undefined) {
+        cachedep = this._kvo_computeCachedDependentsFor(key);
+      }
+      
+      if (cachedep) {
+        idx = cachedep.length;
+        while(--idx>=0) {
+          dfunc = cachedep[idx];
+          cache[dfunc.cacheKey] = cache[dfunc.lastSetValueKey] = undefined;
+        }
+      }
+    }
+
+    // set the value.
+    if (func && func.isProperty) {
+      cache = this._kvo_cache;
+      if (func.isVolatile || !cache || (cache[func.lastSetValueKey] !== value)) {
+        if (!cache) cache = this._kvo_cache = {};
+
+        cache[func.lastSetValueKey] = value ;
+        if (notify) this.propertyWillChange(key) ;
+        ret = func.call(this,key,value) ;
+
+        // update cached value
+        if (func.isCacheable) cache[func.cacheKey] = ret ;
+        if (notify) this.propertyDidChange(key, ret, YES) ;
+      }
+
+    } else if (func === undefined) {
+      if (notify) this.propertyWillChange(key) ;
+      this.unknownProperty(key,value) ;
+      if (notify) this.propertyDidChange(key, ret) ;
+
+    } else {
+      if (this[key] !== value) {
+        if (notify) this.propertyWillChange(key) ;
+        ret = this[key] = value ;
+        if (notify) this.propertyDidChange(key, ret) ;
+      }
+    }
+
+    return this ;
+  },
+
+  /**  
+    Called whenever you try to get or set an undefined property.
+    
+    This is a generic property handler.  If you define it, it will be called
+    when the named property is not yet set in the object.  The default does
+    nothing.
+    
+    @param key {String} the key that was requested
+    @param value {Object} The value if called as a setter, undefined if called as a getter.
+    @returns {Object} The new value for key.
+  */
+  unknownProperty: function(key,value) {
+    if (!(value === undefined)) { this[key] = value; }
+    return value ;
+  },
+
+  /**  
+    Begins a grouping of property changes.
+    
+    You can use this method to group property changes so that notifications
+    will not be sent until the changes are finished.  If you plan to make a 
+    large number of changes to an object at one time, you should call this 
+    method at the beginning of the changes to suspend change notifications.
+    When you are done making changes, all endPropertyChanges() to allow 
+    notification to resume.
+    
+    @returns {SC.Observable}
+  */
+  beginPropertyChanges: function() {
+    this._kvo_changeLevel = (this._kvo_changeLevel || 0) + 1; 
+    return this;
+  },
+
+  /**  
+    Ends a grouping of property changes.
+    
+    You can use this method to group property changes so that notifications
+    will not be sent until the changes are finished.  If you plan to make a 
+    large number of changes to an object at one time, you should call 
+    beginPropertyChanges() at the beginning of the changes to suspend change 
+    notifications. When you are done making changes, call this method to allow 
+    notification to resume.
+    
+    @returns {SC.Observable}
+  */
+  endPropertyChanges: function() {
+    this._kvo_changeLevel = (this._kvo_changeLevel || 1) - 1 ;
+    var level = this._kvo_changeLevel, changes = this._kvo_changes;
+    if ((level<=0) && changes && (changes.length>0) && !SC.Observers.isObservingSuspended) {
+      this._notifyPropertyObservers() ;
+    } 
+    return this ;
+  },
+
+  /**  
+    Notify the observer system that a property is about to change.
+
+    Sometimes you need to change a value directly or indirectly without 
+    actually calling get() or set() on it.  In this case, you can use this 
+    method and propertyDidChange() instead.  Calling these two methods 
+    together will notify all observers that the property has potentially 
+    changed value.
+    
+    Note that you must always call propertyWillChange and propertyDidChange as 
+    a pair.  If you do not, it may get the property change groups out of order 
+    and cause notifications to be delivered more often than you would like.
+    
+    @param key {String} The property key that is about to change.
+    @returns {SC.Observable}
+  */
+  propertyWillChange: function(key) {
+    return this ;
+  },
+
+  /**  
+    Notify the observer system that a property has just changed.
+
+    Sometimes you need to change a value directly or indirectly without 
+    actually calling get() or set() on it.  In this case, you can use this 
+    method and propertyWillChange() instead.  Calling these two methods 
+    together will notify all observers that the property has potentially 
+    changed value.
+    
+    Note that you must always call propertyWillChange and propertyDidChange as 
+    a pair. If you do not, it may get the property change groups out of order 
+    and cause notifications to be delivered more often than you would like.
+    
+    @param key {String} The property key that has just changed.
+    @param value {Object} The new value of the key.  May be null.
+    @returns {SC.Observable}
+  */
+  propertyDidChange: function(key,value, _keepCache) {
+
+    this._kvo_revision = (this._kvo_revision || 0) + 1; 
+    var level = this._kvo_changeLevel || 0,
+        cachedep, idx, dfunc, cache, func,
+        log = SC.LOG_OBSERVERS && !(this.LOG_OBSERVING===NO);
+
+    if (cache = this._kvo_cache) {
+
+      // clear any cached value
+      if (!_keepCache) {
+        func = this[key] ;
+        if (func && func.isProperty) {
+          cache[func.cacheKey] = cache[func.lastSetValueKey] = undefined ;
+        }
+      }
+
+      if (this._kvo_cacheable) {
+        // if there are any dependent keys and they use caching, then clear the
+        // cache.  This is the same code as is in set.  It is inlined for perf.
+        cachedep = this._kvo_cachedep;
+        if (!cachedep || (cachedep = cachedep[key])===undefined) {
+          cachedep = this._kvo_computeCachedDependentsFor(key);
+        }
+
+        if (cachedep) {
+          idx = cachedep.length;
+          while(--idx>=0) {
+            dfunc = cachedep[idx];
+            cache[dfunc.cacheKey] = cache[dfunc.lastSetValueKey] = undefined;
+          }
+        }
+      }
+    }
+
+    // save in the change set if queuing changes
+    var suspended = SC.Observers.isObservingSuspended;
+    if ((level > 0) || suspended) {
+      var changes = this._kvo_changes ;
+      if (!changes) changes = this._kvo_changes = SC.CoreSet.create() ;
+      changes.add(key) ;
+      
+      if (suspended) {
+        if (log) console.log("%@%@: will not notify observers because observing is suspended".fmt(SC.KVO_SPACES,this));
+        SC.Observers.objectHasPendingChanges(this) ;
+      }
+      
+    // otherwise notify property observers immediately
+    } else this._notifyPropertyObservers(key) ;
+    
+    return this ;
+  },
+
+  // ..........................................
+  // DEPENDENT KEYS
+  // 
+
+  /**
+    Use this to indicate that one key changes if other keys it depends on 
+    change.  Pass the key that is dependent and additional keys it depends
+    upon.  You can either pass the additional keys inline as arguments or 
+    in a single array.
+    
+    You generally do not call this method, but instead pass dependent keys to
+    your property() method when you declare a computed property.
+    
+    You can call this method during your init to register the keys that should
+    trigger a change notification for your computed properties.  
+    
+    @param {String} key the dependent key
+    @param {Array|String} dependentKeys one or more dependent keys 
+    @returns {Object} this
+  */  
+  registerDependentKey: function(key, dependentKeys) {
+    var dependents = this._kvo_dependents,
+        func       = this[key],
+        keys, idx, lim, dep, queue;
+
+    // normalize input.
+    if (typeof dependentKeys === "object" && (dependentKeys instanceof Array)) {
+      keys = dependentKeys;
+      lim  = 0;
+    } else {
+      keys = arguments;
+      lim  = 1;
+    }
+    idx  = keys.length;
+
+    // define dependents if not defined already.
+    if (!dependents) this._kvo_dependents = dependents = {} ;
+
+    // for each key, build array of dependents, add this key...
+    // note that we ignore the first argument since it is the key...
+    while(--idx >= lim) {
+      dep = keys[idx] ;
+
+      // add dependent key to dependents array of key it depends on
+      queue = dependents[dep] ;
+      if (!queue) queue = dependents[dep] = [] ;
+      queue.push(key) ;
+    }
+  },
+
+  /** @private 
+  
+    Helper method used by computeCachedDependents.  Just loops over the 
+    array of dependent keys.  If the passed function is cacheable, it will
+    be added to the queue.  Also, recursively call on each keys dependent 
+    keys.
+  
+    @param {Array} queue the queue to add functions to
+    @param {Array} keys the array of dependent keys for this key
+    @param {Hash} dependents the _kvo_dependents cache
+    @param {SC.Set} seen already seen keys
+    @returns {void}
+  */
+  _kvo_addCachedDependents: function(queue, keys, dependents, seen) {
+    var idx = keys.length,
+        func, key, deps ;
+        
+    while(--idx >= 0) {
+      key  = keys[idx];
+      seen.add(key);
+      
+      // if the value for this key is a computed property, then add it to the
+      // set if it is cacheable, and process any of its dependent keys also.
+      func = this[key];
+      if (func && (func instanceof Function) && func.isProperty) {
+        if (func.isCacheable) queue.push(func); // handle this func
+        if ((deps = dependents[key]) && deps.length>0) { // and any dependents
+          this._kvo_addCachedDependents(queue, deps, dependents, seen);
+        }
+      } 
+    }
+        
+  },
+  
+  /** @private
+
+    Called by set() whenever it needs to determine which cached dependent
+    keys to clear.  Recursively searches dependent keys to determine all 
+    cached property direcly or indirectly affected.
+    
+    The return value is also saved for future reference
+    
+    @param {String} key the key to compute
+    @returns {Array}
+  */
+  _kvo_computeCachedDependentsFor: function(key) {
+    var cached     = this._kvo_cachedep,
+        dependents = this._kvo_dependents,
+        keys       = dependents ? dependents[key] : null,
+        queue, seen ;
+    if (!cached) cached = this._kvo_cachedep = {};
+
+    // if there are no dependent keys, then just set and return null to avoid
+    // this mess again.
+    if (!keys || keys.length===0) return cached[key] = null;
+
+    // there are dependent keys, so we need to do the work to find out if 
+    // any of them or their dependent keys are cached.
+    queue = cached[key] = [];
+    seen  = SC._TMP_SEEN_SET = (SC._TMP_SEEN_SET || SC.CoreSet.create());
+    seen.add(key);
+    this._kvo_addCachedDependents(queue, keys, dependents, seen);
+    seen.clear(); // reset
+    
+    if (queue.length === 0) queue = cached[key] = null ; // turns out nothing
+    return queue ;
+  },
+  
+  // ..........................................
+  // OBSERVERS
+  // 
+  
+  _kvo_for: function(kvoKey, type) {
+    var ret = this[kvoKey] ;
+
+    if (!this._kvo_cloned) this._kvo_cloned = {} ;
+    
+    // if the item does not exist, create it.  Unless type is passed, 
+    // assume array.
+    if (!ret) {
+      ret = this[kvoKey] = (type === undefined) ? [] : type.create();
+      this._kvo_cloned[kvoKey] = YES ;
+      
+    // if item does exist but has not been cloned, then clone it.  Note
+    // that all types must implement copy().0
+    } else if (!this._kvo_cloned[kvoKey]) {
+      ret = this[kvoKey] = ret.copy();
+      this._kvo_cloned[kvoKey] = YES; 
+    }
+    
+    return ret ;
+  },
+
+  /**  
+    Adds an observer on a property.
+    
+    This is the core method used to register an observer for a property.
+    
+    Once you call this method, anytime the key's value is set, your observer
+    will be notified.  Note that the observers are triggered anytime the
+    value is set, regardless of whether it has actually changed.  Your
+    observer should be prepared to handle that.
+    
+    You can also pass an optional context parameter to this method.  The 
+    context will be passed to your observer method whenever it is triggered.
+    Note that if you add the same target/method pair on a key multiple times
+    with different context parameters, your observer will only be called once
+    with the last context you passed.
+    
+    h2. Observer Methods
+    
+    Observer methods you pass should generally have the following signature if
+    you do not pass a "context" parameter:
+    
+    {{{
+      fooDidChange: function(sender, key, value, rev);
+    }}}
+    
+    The sender is the object that changed.  The key is the property that
+    changes.  The value property is currently reserved and unused.  The rev
+    is the last property revision of the object when it changed, which you can
+    use to detect if the key value has really changed or not.
+    
+    If you pass a "context" parameter, the context will be passed before the
+    revision like so:
+    
+    {{{
+      fooDidChange: function(sender, key, value, context, rev);
+    }}}
+    
+    Usually you will not need the value, context or revision parameters at 
+    the end.  In this case, it is common to write observer methods that take
+    only a sender and key value as parameters or, if you aren't interested in
+    any of these values, to write an observer that has no parameters at all.
+    
+    @param key {String} the key to observer
+    @param target {Object} the target object to invoke
+    @param method {String|Function} the method to invoke.
+    @param context {Object} optional context
+    @returns {SC.Object} self
+  */
+  addObserver: function(key, target, method, context) {
+    
+    var kvoKey, chain, chains, observers;
+    
+    // normalize.  if a function is passed to target, make it the method.
+    if (method === undefined) {
+      method = target; target = this ;
+    }
+    if (!target) target = this ;
+    
+    if (typeof method === "string") method = target[method] ;
+    if (!method) throw "You must pass a method to addObserver()" ;
+
+    // Normalize key...
+    key = key.toString() ;
+    if (key.indexOf('.') >= 0) {
+      
+      // create the chain and save it for later so we can tear it down if 
+      // needed.
+      chain = SC._ChainObserver.createChain(this, key, target, method, context);
+      chain.masterTarget = target;  
+      chain.masterMethod = method ;
+      
+      // Save in set for chain observers.
+      this._kvo_for(SC.keyFor('_kvo_chains', key)).push(chain);
+      
+    // Create observers if needed...
+    } else {
+      
+      // Special case to support reduced properties.  If the property 
+      // key begins with '@' and its value is unknown, then try to get its
+      // value.  This will configure the dependent keys if needed.
+      if ((this[key] === undefined) && (key.indexOf('@') === 0)) {
+        this.get(key) ;
+      }
+
+      if (target === this) target = null ; // use null for observers only.
+      kvoKey = SC.keyFor('_kvo_observers', key);
+      this._kvo_for(kvoKey, SC.ObserverSet).add(target, method, context);
+      this._kvo_for('_kvo_observed_keys', SC.CoreSet).add(key) ;
+    }
+
+    if (this.didAddObserver) this.didAddObserver(key, target, method);
+    return this;
+  },
+
+  /**
+    Remove an observer you have previously registered on this object.  Pass
+    the same key, target, and method you passed to addObserver() and your 
+    target will no longer receive notifications.
+    
+    @returns {SC.Observable} reciever
+  */
+  removeObserver: function(key, target, method) {
+    
+    var kvoKey, chains, chain, observers, idx ;
+    
+    // normalize.  if a function is passed to target, make it the method.
+    if (method === undefined) {
+      method = target; target = this ;
+    }
+    if (!target) target = this ;
+    
+    if (typeof method === "string") method = target[method] ;
+    if (!method) throw "You must pass a method to removeObserver()" ;
+
+    // if the key contains a '.', this is a chained observer.
+    key = key.toString() ;
+    if (key.indexOf('.') >= 0) {
+      
+      // try to find matching chains
+      kvoKey = SC.keyFor('_kvo_chains', key);
+      if (chains = this[kvoKey]) {
+        
+        // if chains have not been cloned yet, do so now.
+        chains = this._kvo_for(kvoKey) ;
+        
+        // remove any chains
+        idx = chains.length;
+        while(--idx >= 0) {
+          chain = chains[idx];
+          if (chain && (chain.masterTarget===target) && (chain.masterMethod===method)) {
+            chains[idx] = chain.destroyChain() ;
+          }
+        }
+      }
+      
+    // otherwise, just like a normal observer.
+    } else {
+      if (target === this) target = null ; // use null for observers only.
+      kvoKey = SC.keyFor('_kvo_observers', key) ;
+      if (observers = this[kvoKey]) {
+        // if observers have not been cloned yet, do so now
+        observers = this._kvo_for(kvoKey) ;
+        observers.remove(target, method) ;
+        if (observers.targets <= 0) {
+          this._kvo_for('_kvo_observed_keys', SC.CoreSet).remove(key);
+        }
+      }
+    }
+
+    if (this.didRemoveObserver) this.didRemoveObserver(key, target, method);
+    return this;
+  },
+  
+  /**
+    Returns YES if the object currently has observers registered for a 
+    particular key.  You can use this method to potentially defer performing
+    an expensive action until someone begins observing a particular property
+    on the object.
+    
+    @param {String} key key to check
+    @returns {Boolean}
+  */
+  hasObserverFor: function(key) {
+    SC.Observers.flush(this) ; // hookup as many observers as possible.
+    
+    var observers = this[SC.keyFor('_kvo_observers', key)],
+        locals    = this[SC.keyFor('_kvo_local', key)],
+        members ;
+
+    if (locals && locals.length>0) return YES ;
+    if (observers && observers.getMembers().length>0) return YES ;
+    return NO ;
+  },
+
+  /**
+    This method will register any observers and computed properties saved on
+    the object.  Normally you do not need to call this method youself.  It
+    is invoked automatically just before property notifications are sent and
+    from the init() method of SC.Object.  You may choose to call this
+    from your own initialization method if you are using SC.Observable in
+    a non-SC.Object-based object.
+    
+    This method looks for several private variables, which you can setup,
+    to initialize:
+    
+      - _observers: this should contain an array of key names for observers
+        you need to configure.
+        
+      - _bindings: this should contain an array of key names that configure
+        bindings.
+        
+      - _properties: this should contain an array of key names for computed
+        properties.
+        
+    @returns {Object} this
+  */
+  initObservable: function() {
+    if (this._observableInited) return ;
+    this._observableInited = YES ;
+    
+    var loc, keys, key, value, observer, propertyPaths, propertyPathsLength,
+        len, ploc, path, dotIndex, root, propertyKey, keysLen;
+    
+    // Loop through observer functions and register them
+    if (keys = this._observers) {
+      len = keys.length ;
+      for(loc=0;loc<len;loc++) {
+        key = keys[loc]; observer = this[key] ;
+        propertyPaths = observer.propertyPaths ;
+        propertyPathsLength = (propertyPaths) ? propertyPaths.length : 0 ;
+        for(ploc=0;ploc<propertyPathsLength;ploc++) {
+          path = propertyPaths[ploc] ;
+          dotIndex = path.indexOf('.') ;
+          // handle most common case, observing a local property
+          if (dotIndex < 0) {
+            this.addObserver(path, this, observer) ;
+
+          // next most common case, use a chained observer
+          } else if (path.indexOf('*') === 0) {
+            this.addObserver(path.slice(1), this, observer) ;
+            
+          // otherwise register the observer in the observers queue.  This 
+          // will add the observer now or later when the named path becomes
+          // available.
+          } else {
+            root = null ;
+            
+            // handle special cases for observers that look to the local root
+            if (dotIndex === 0) {
+              root = this; path = path.slice(1) ;
+            } else if (dotIndex===4 && path.slice(0,5) === 'this.') {
+              root = this; path = path.slice(5) ;
+            } else if (dotIndex<0 && path.length===4 && path === 'this') {
+              root = this; path = '';
+            }
+            
+            SC.Observers.addObserver(path, this, observer, root); 
+          }
+        }
+      }
+    }
+
+    // Add Bindings
+    this.bindings = []; // will be filled in by the bind() method.
+    if (keys = this._bindings) {
+      for(loc=0, keysLen = keys.length; loc < keysLen;loc++) {
+        // get propertyKey
+        key = keys[loc] ; value = this[key] ;
+        propertyKey = key.slice(0,-7) ; // contentBinding => content
+        this[key] = this.bind(propertyKey, value) ;
+      }
+    }
+
+    // Add Properties
+    if (keys = this._properties) {
+      for(loc=0, keysLen = keys.length; loc<keysLen;loc++) {
+        key = keys[loc];
+        if (value = this[key]) {
+
+          // activate cacheable only if needed for perf reasons
+          if (value.isCacheable) this._kvo_cacheable = YES; 
+
+          // register dependent keys
+          if (value.dependentKeys && (value.dependentKeys.length>0)) {
+            this.registerDependentKey(key, value.dependentKeys) ;
+          }
+        }
+      }
+    }
+    
+  },
+  
+  // ..........................................
+  // NOTIFICATION
+  // 
+
+  /**
+    Returns an array with all of the observers registered for the specified
+    key.  This is intended for debugging purposes only.  You generally do not
+    want to rely on this method for production code.
+    
+    @params key {String} the key to evaluate
+    @returns {Array} array of Observer objects, describing the observer.
+  */
+  observersForKey: function(key) {
+    var observers = this._kvo_for('_kvo_observers', key) ;
+    return observers.getMembers() || [] ;
+  },
+  
+  // this private method actually notifies the observers for any keys in the
+  // observer queue.  If you pass a key it will be added to the queue.
+  _notifyPropertyObservers: function(key) {
+
+    if (!this._observableInited) this.initObservable() ;
+    
+    SC.Observers.flush(this) ; // hookup as many observers as possible.
+
+    var log = SC.LOG_OBSERVERS && !(this.LOG_OBSERVING===NO),
+        observers, changes, dependents, starObservers, idx, keys, rev,
+        members, membersLength, member, memberLoc, target, method, loc, func,
+        context, spaces, cache ;
+
+    if (log) {
+      spaces = SC.KVO_SPACES = (SC.KVO_SPACES || '') + '  ';
+      console.log('%@%@: notifying observers after change to key "%@"'.fmt(spaces, this, key));
+    }
+    
+    // Get any starObservers -- they will be notified of all changes.
+    starObservers =  this['_kvo_observers_*'] ;
+    
+    // prevent notifications from being sent until complete
+    this._kvo_changeLevel = (this._kvo_changeLevel || 0) + 1; 
+
+    // keep sending notifications as long as there are changes
+    while(((changes = this._kvo_changes) && (changes.length > 0)) || key) {
+      
+      // increment revision
+      rev = ++this.propertyRevision ;
+      
+      // save the current set of changes and swap out the kvo_changes so that
+      // any set() calls by observers will be saved in a new set.
+      if (!changes) changes = SC.CoreSet.create() ;
+      this._kvo_changes = null ;
+
+      // Add the passed key to the changes set.  If a '*' was passed, then
+      // add all keys in the observers to the set...
+      // once finished, clear the key so the loop will end.
+      if (key === '*') {
+        changes.add('*') ;
+        changes.addEach(this._kvo_for('_kvo_observed_keys', SC.CoreSet));
+
+      } else if (key) changes.add(key) ;
+
+      // Now go through the set and add all dependent keys...
+      if (dependents = this._kvo_dependents) {
+
+        // NOTE: each time we loop, we check the changes length, this
+        // way any dependent keys added to the set will also be evaluated...
+        for(idx=0;idx<changes.length;idx++) {
+          key = changes[idx] ;
+          keys = dependents[key] ;
+          
+          // for each dependent key, add to set of changes.  Also, if key
+          // value is a cacheable property, clear the cached value...
+          if (keys && (loc = keys.length)) {
+            if (log) {
+              console.log("%@...including dependent keys for %@: %@".fmt(spaces, key, keys));
+            }
+            cache = this._kvo_cache;
+            if (!cache) cache = this._kvo_cache = {};
+            while(--loc >= 0) {
+              changes.add(key = keys[loc]);
+              if (func = this[key]) {
+                this[func.cacheKey] = undefined;
+                cache[func.cacheKey] = cache[func.lastSetValueKey] = undefined;
+              } // if (func=)
+            } // while (--loc)
+          } // if (keys && 
+        } // for(idx...
+      } // if (dependents...)
+
+      // now iterate through all changed keys and notify observers.
+      while(changes.length > 0) {
+        key = changes.pop() ; // the changed key
+
+        // find any observers and notify them...
+        observers = this[SC.keyFor('_kvo_observers', key)];
+        if (observers) {
+          members = observers.getMembers() ;
+          membersLength = members.length ;
+          for(memberLoc=0;memberLoc < membersLength; memberLoc++) {
+            member = members[memberLoc] ;
+            if (member[3] === rev) continue ; // skip notified items.
+
+            target = member[0] || this; 
+            method = member[1] ; 
+            context = member[2];
+            member[3] = rev;
+            
+            if (log) console.log('%@...firing observer on %@ for key "%@"'.fmt(spaces, target, key));
+            if (context !== undefined) {
+              method.call(target, this, key, null, context, rev);
+            } else {
+              method.call(target, this, key, null, rev) ;
+            }
+          }
+        }
+
+        // look for local observers.  Local observers are added by SC.Object
+        // as an optimization to avoid having to add observers for every 
+        // instance when you are just observing your local object.
+        members = this[SC.keyFor('_kvo_local', key)];
+        if (members) {
+          membersLength = members.length ;
+          for(memberLoc=0;memberLoc<membersLength;memberLoc++) {
+            member = members[memberLoc];
+            method = this[member] ; // try to find observer function
+            if (method) {
+              if (log) console.log('%@...firing local observer %@.%@ for key "%@"'.fmt(spaces, this, member, key));
+              method.call(this, this, key, null, rev);
+            }
+          }
+        }
+        
+        // if there are starObservers, do the same thing for them
+        if (starObservers && key !== '*') {          
+          members = starObservers.getMembers() ;
+          membersLength = members.length ;
+          for(memberLoc=0;memberLoc < membersLength; memberLoc++) {
+            member = members[memberLoc] ;
+            target = member[0] || this; 
+            method = member[1] ;
+            context = member[2] ;
+            
+            if (log) console.log('%@...firing * observer on %@ for key "%@"'.fmt(spaces, target, key));
+            if (context !== undefined) {
+              method.call(target, this, key, null, context, rev);
+            } else {
+              method.call(target, this, key, null, rev) ;
+            }
+          }
+        }
+
+        // if there is a default property observer, call that also
+        if (this.propertyObserver) {
+          if (log) console.log('%@...firing %@.propertyObserver for key "%@"'.fmt(spaces, this, key));
+          this.propertyObserver(this, key, null, rev);
+        }
+      } // while(changes.length>0)
+
+      // changes set should be empty. release it for reuse
+      if (changes) changes.destroy() ;
+      
+      // key is no longer needed; clear it to avoid infinite loops
+      key = null ; 
+      
+    } // while (changes)
+    
+    // done with loop, reduce change level so that future sets can resume
+    this._kvo_changeLevel = (this._kvo_changeLevel || 1) - 1; 
+    
+    if (log) SC.KVO_SPACES = spaces.slice(0, -2);
+    
+    return YES ; // finished successfully
+  },
+
+  // ..........................................
+  // BINDINGS
+  // 
+    
+  /**  
+    Manually add a new binding to an object.  This is the same as doing
+    the more familiar propertyBinding: 'property.path' approach.
+    
+    @param {String} toKey the key to bind to
+    @param {Object} target target or property path to bind from
+    @param {String|Function} method method for target to bind from
+    @returns {SC.Binding} new binding instance
+  */
+  bind: function(toKey, target, method) {
+
+    var binding , pathType;
+
+    // normalize...
+    if (method !== undefined) target = [target, method];
+
+    // if a string or array (i.e. tuple) is passed, convert this into a
+    // binding.  If a binding default was provided, use that.
+    pathType = typeof target;
+    
+    if (pathType === "string" || (pathType === "object" && (target instanceof Array))) {
+      binding = this[toKey + 'BindingDefault'] || SC.Binding;
+      binding = binding.beget().from(target) ;
+    } else binding = target ;
+
+    // finish configuring the binding and then connect it.
+    binding = binding.to(toKey, this).connect() ;
+    this.bindings.push(binding) ;
+    
+    return binding ;
+  },
+  
+  /**  
+    didChangeFor makes it easy for you to verify that you haven't seen any
+    changed values.  You need to use this if your method observes multiple
+    properties.  To use this, call it like this:
+  
+    if (this.didChangeFor('render','height','width')) {
+       // DO SOMETHING HERE IF CHANGED.
+    }
+  */  
+  didChangeFor: function(context) { 
+    var valueCache, revisionCache, seenValues, seenRevisions, ret,
+        currentRevision, idx, key, value;
+    context = SC.hashFor(context) ; // get a hash key we can use in caches.
+    
+    // setup caches...
+    valueCache = this._kvo_didChange_valueCache ;
+    if (!valueCache) valueCache = this._kvo_didChange_valueCache = {};
+    revisionCache = this._kvo_didChange_revisionCache;
+    if (!revisionCache) revisionCache=this._kvo_didChange_revisionCache={};
+
+    // get the cache of values and revisions already seen in this context
+    seenValues = valueCache[context] || {} ;
+    seenRevisions = revisionCache[context] || {} ;
+    
+    // prepare too loop!
+    ret = false ;
+    currentRevision = this._kvo_revision || 0  ;
+    idx = arguments.length ;
+    while(--idx >= 1) {  // NB: loop only to 1 to ignore context arg.
+      key = arguments[idx];
+      
+      // has the kvo revision changed since the last time we did this?
+      if (seenRevisions[key] != currentRevision) {
+        // yes, check the value with the last seen value
+        value = this.get(key) ;
+        if (seenValues[key] !== value) {
+          ret = true ; // did change!
+          seenValues[key] = value;
+        }
+      }
+      seenRevisions[key] = currentRevision;
+    }
+    
+    valueCache[context] = seenValues ;
+    revisionCache[context] = seenRevisions ;
+    return ret ;
+  },
+
+
+
+  /**
+    Sets the property only if the passed value is different from the
+    current value.  Depending on how expensive a get() is on this property,
+    this may be more efficient.
+    
+    @param key {String} the key to change
+    @param value {Object} the value to change
+    @returns {SC.Observable}
+  */
+  setIfChanged: function(key, value) {
+    return (this.get(key) !== value) ? this.set(key, value) : this ;
+  },
+  
+  /**  
+    Navigates the property path, returning the value at that point.
+    
+    If any object in the path is undefined, returns undefined.
+  */
+  getPath: function(path) {
+    var tuple = SC.tupleForPropertyPath(path, this) ;
+    if (tuple === null || tuple[0] === null) return undefined ;
+    return tuple[0].get(tuple[1]) ;
+  },
+  
+  /**
+    Navigates the property path, finally setting the value.
+    
+    @param path {String} the property path to set
+    @param value {Object} the value to set
+    @returns {SC.Observable}
+  */
+  setPath: function(path, value) {
+    if (path.indexOf('.') >= 0) {
+      var tuple = SC.tupleForPropertyPath(path, this) ;
+      if (!tuple || !tuple[0]) return null ;
+      tuple[0].set(tuple[1], value) ;
+    } else this.set(path, value) ; // shortcut
+    return this;
+  },
+
+  /**
+    Navigates the property path, finally setting the value but only if 
+    the value does not match the current value.  This will avoid sending
+    unecessary change notifications.
+    
+    @param path {String} the property path to set
+    @param value {Object} the value to set
+    @returns {Object} this
+  */
+  setPathIfChanged: function(path, value) {
+    if (path.indexOf('.') >= 0) {
+      var tuple = SC.tupleForPropertyPath(path, this) ;
+      if (!tuple || !tuple[0]) return null ;
+      if (tuple[0].get(tuple[1]) !== value) {
+        tuple[0].set(tuple[1], value) ;
+      }
+    } else this.setIfChanged(path, value) ; // shortcut
+    return this;
+  },
+  
+  /** 
+    Convenience method to get an array of properties.
+    
+    Pass in multiple property keys or an array of property keys.  This
+    method uses getPath() so you can also pass key paths.
+
+    @returns {Array} Values of property keys.
+  */
+  getEach: function() {
+    var keys = SC.A(arguments),
+        ret = [], idx, idxLen;
+    for(idx=0, idxLen = keys.length; idx < idxLen;idx++) {
+      ret[ret.length] = this.getPath(keys[idx]);
+    }
+    return ret ;
+  },
+  
+  
+  /**  
+    Increments the value of a property.
+    
+    @param key {String} property name
+    @param increment {Number} the amount to increment (optional)
+    @returns {Number} new value of property
+  */
+  incrementProperty: function(key,increment) {
+    if (!increment) increment = 1;
+    this.set(key,(this.get(key) || 0)+increment); 
+    return this.get(key) ;
+  },
+
+  /**  
+    Decrements the value of a property.
+    
+    @param key {String} property name
+    @param increment {Number} the amount to decrement (optional)
+    @returns {Number} new value of property
+  */
+  decrementProperty: function(key,increment) {
+    if (!increment) increment = 1;
+    this.set(key,(this.get(key) || 0) - increment) ;
+    return this.get(key) ;
+  },
+
+  /**  
+    Inverts a property.  Property should be a bool.
+    
+    @param key {String} property name
+    @param value {Object} optional parameter for "true" value
+    @param alt {Object} optional parameter for "false" value
+    @returns {Object} new value
+  */
+  toggleProperty: function(key,value,alt) { 
+    if (value === undefined) value = true ;
+    if (alt === undefined) alt = false ;
+    value = (this.get(key) == value) ? alt : value ;
+    this.set(key,value);
+    return this.get(key) ;
+  },
+
+  /**
+    Convenience method to call propertyWillChange/propertyDidChange.
+    
+    Sometimes you need to notify observers that a property has changed value 
+    without actually changing this value.  In those cases, you can use this 
+    method as a convenience instead of calling propertyWillChange() and 
+    propertyDidChange().
+    
+    @param key {String} The property key that has just changed.
+    @param value {Object} The new value of the key.  May be null.
+    @returns {SC.Observable}
+  */
+  notifyPropertyChange: function(key, value) {
+    this.propertyWillChange(key) ;
+    this.propertyDidChange(key, value) ;
+    return this; 
+  },
+  
+  /**  
+    Notifies all of observers of a property changes.
+    
+    Sometimes when you make a major update to your object, it is cheaper to
+    simply notify all observers that their property might have changed than
+    to figure out specifically which properties actually did change.
+    
+    In those cases, you can simply call this method to notify all property
+    observers immediately.  Note that this ignores property groups.
+    
+    @returns {SC.Observable}
+  */
+  allPropertiesDidChange: function() {
+    this._kvo_cache = null; //clear cached props
+    this._notifyPropertyObservers('*') ;
+    return this ;
+  },
+
+  addProbe: function(key) { this.addObserver(key,SC.logChange); },
+  removeProbe: function(key) { this.removeObserver(key,SC.logChange); },
+
+  /**
+    Logs the named properties to the console.
+    
+    @param {String...} propertyNames one or more property names
+  */
+  logProperty: function() {
+    var props = SC.$A(arguments),
+        prop, propsLen, idx;
+    for(idx=0, propsLen = props.length; idx<propsLen; idx++) {
+      prop = props[idx] ;
+      console.log('%@:%@: '.fmt(SC.guidFor(this), prop), this.get(prop)) ;
+    }
+  },
+
+  propertyRevision: 1
+    
+} ;
+
+/** @private used by addProbe/removeProbe */
+SC.logChange = function logChange(target, key, value) {
+  console.log("CHANGE: %@[%@] =>".fmt(target, key), target.get(key));
+};
+
+/**
+  Retrieves a property from an object, using get() if the
+  object implements SC.Observable.
+
+  @param  {Object}  object  the object to query
+  @param  {String}  key the property to retrieve
+*/
+SC.mixin(SC, {
+  get: function(object, key) {
+    if (!object) return undefined;
+    if (key === undefined) return this[object];
+    if (object.get) return object.get(key);
+    return object[key];
+  }
+});
+
+// Make all Array's observable
+SC.mixin(Array.prototype, SC.Observable) ;