Add CallbackProperty for lazy evaluation

CHANGES.md

@@ -12,13 +12,15 @@ Change Log
 * Added `stroke-width` support to the GeoJSON simple-style implementation.
 * Added support for touch events on Internet Explorer 11 using the [Pointer Events API](http://www.w3.org/TR/pointerevents/).
 * Added the ability to specify global GeoJSON default styling.  See the [documentation](http://cesiumjs.org/Cesium/Build/Documentation/GeoJsonDataSource.html) for details.
+* Added `CallbackProperty` to support lazy property evaluation as well as make custom properties easier to create.
 * Added an options parameter to `GeoJsonDataSource.load`, `GeoJsonDataSource.loadUrl`, and `GeoJsonDataSource.fromUrl` to allow for basic per-instance styling. [Sandcastle example](http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=GeoJSON%20and%20TopoJSON.html&label=Showcases).
 * Added `tileMatrixLabels` option to `WebMapTileServiceImageryProvider`.
 * Fixed a bug in `PolylineGeometry` that would cause the geometry to be split across the IDL for 3D only scenes. [#1197](https://github.com/AnalyticalGraphicsInc/cesium/issues/1197)
 * Added `modelMatrix` and `cull` options to `Primitive` constructor.
 * The `translation` parameter to `Matrix4.fromRotationTranslation` now defaults to `Cartesian3.ZERO`.
 * Improved point visualization performance for all DataSources.
 * Fixed `ModelNode.matrix` when a node is targeted for animation.
+* Improved GeoJSON loading performance.
 
 ### 1.3 - 2014-11-03
 

Source/DataSources/CallbackProperty.js

@@ -0,0 +1,116 @@
+/*global define*/
+define([
+        '../Core/defined',
+        '../Core/defineProperties',
+        '../Core/DeveloperError',
+        '../Core/Event'
+    ], function(
+        defined,
+        defineProperties,
+        DeveloperError,
+        Event) {
+    "use strict";
+
+    /**
+     * A {@link Property} whose value is lazily evaluated by a callback function.
+     *
+     * @alias CallbackProperty
+     * @constructor
+     *
+     * @param {CallbackProperty~Callback} callback The function to be called when the property is evaluated.
+     * @param {Boolean} isConstant <code>true</code> when the callback function returns the same value every time, <code>false</code> if the value will change.
+     */
+    var CallbackProperty = function(callback, isConstant) {
+        this._callback = undefined;
+        this._isConstant = undefined;
+        this._definitionChanged = new Event();
+        this.setCallback(callback, isConstant);
+    };
+
+    defineProperties(CallbackProperty.prototype, {
+        /**
+         * Gets a value indicating if this property is constant.
+         * @memberof CallbackProperty.prototype
+         *
+         * @type {Boolean}
+         * @readonly
+         */
+        isConstant : {
+            get : function() {
+                return this._isConstant;
+            }
+        },
+        /**
+         * Gets the event that is raised whenever the definition of this property changes.
+         * The definition is changed whenever setCallback is called.
+         * @memberof CallbackProperty.prototype
+         *
+         * @type {Event}
+         * @readonly
+         */
+        definitionChanged : {
+            get : function() {
+                return this._definitionChanged;
+            }
+        }
+    });
+
+    /**
+     * Gets the value of the property.
+     *
+     * @param {JulianDate} [time] The time for which to retrieve the value.  This parameter is unused since the value does not change with respect to time.
+     * @param {Object} [result] The object to store the value into, if omitted, a new instance is created and returned.
+     * @returns {Object} The modified result parameter or a new instance if the result parameter was not supplied or is unsupported.
+     */
+    CallbackProperty.prototype.getValue = function(time, result) {
+        return this._callback(time, result);
+    };
+
+    /**
+     * Sets the callback to be used.
+     *
+     * @param {CallbackProperty~Callback} callback The function to be called when the property is evaluated.
+     * @param {Boolean} isConstant <code>true</code> when the callback function returns the same value every time, <code>false</code> if the value will change.
+     */
+    CallbackProperty.prototype.setCallback = function(callback, isConstant) {
+        //>>includeStart('debug', pragmas.debug);
+        if (!defined(callback)) {
+            throw new DeveloperError('callback is required.');
+        }
+        if (!defined(isConstant)) {
+            throw new DeveloperError('isConstant is required.');
+        }
+        //>>includeEnd('debug');
+
+        var changed = this._callback !== callback || this._isConstant !== isConstant;
+
+        this._callback = callback;
+        this._isConstant = isConstant;
+
+        if (changed) {
+            this._definitionChanged.raiseEvent(this);
+        }
+    };
+
+    /**
+     * Compares this property to the provided property and returns
+     * <code>true</code> if they are equal, <code>false</code> otherwise.
+     *
+     * @param {Property} [other] The other property.
+     * @returns {Boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
+     */
+    CallbackProperty.prototype.equals = function(other) {
+        return this === other || (other instanceof CallbackProperty && this._callback === other._callback && this._isConstant === other._isConstant);
+    };
+
+    /**
+     * A function that returns the value of the property.
+     * @callback CallbackProperty~Callback
+     *
+     * @param {JulianDate} [time] The time for which to retrieve the value.
+     * @param {Object} [result] The object to store the value into, if omitted, a new instance is created and returned.
+     * @returns {Object} The modified result parameter or a new instance if the result parameter was not supplied or is unsupported.
+     */
+
+    return CallbackProperty;
+});

Source/DataSources/GeoJsonDataSource.js

@@ -22,6 +22,7 @@ define([
         './ConstantProperty',
         './DataSource',
         './EntityCollection',
+        './CallbackProperty',
         './PolygonGraphics',
         './PolylineGraphics'
     ], function(
@@ -47,6 +48,7 @@ define([
         ConstantProperty,
         DataSource,
         EntityCollection,
+        CallbackProperty,
         PolygonGraphics,
         PolylineGraphics) {
     "use strict";
@@ -104,6 +106,16 @@ define([
         return html;
     }
 
+    function createDescriptionCallback(properties, nameProperty) {
+        var description;
+        return function(time, result) {
+            if (!defined(description)) {
+                description = describe(properties, nameProperty);
+            }
+            return description;
+        };
+    }
+
     //GeoJSON specifies only the Feature object has a usable id property
     //But since "multi" geometries create multiple entity,
     //we can't use it for them either.
@@ -169,9 +181,10 @@ define([
 
             var description = properties.description;
             if (!defined(description)) {
-                description = describe(properties, nameProperty);
+                entity.description = new CallbackProperty(createDescriptionCallback(properties, nameProperty), true);
+            } else {
+                entity.description = new ConstantProperty(description);
             }
-            entity.description = new ConstantProperty(description);
         }
         return entity;
     }

Specs/DataSources/CallbackPropertySpec.js

@@ -0,0 +1,81 @@
+/*global defineSuite*/
+defineSuite([
+        'DataSources/CallbackProperty',
+        'Core/Cartesian3',
+        'Core/JulianDate'
+    ], function(
+        CallbackProperty,
+        Cartesian3,
+        JulianDate) {
+    "use strict";
+    /*global jasmine,describe,xdescribe,it,xit,expect,beforeEach,afterEach,beforeAll,afterAll,spyOn,runs,waits,waitsFor*/
+
+    var time = JulianDate.now();
+
+    it('callback received proper parameters', function() {
+        var result = {};
+        var callback = jasmine.createSpy('callback');
+        var property = new CallbackProperty(callback, true);
+        property.getValue(time, result);
+        expect(callback).toHaveBeenCalledWith(time, result);
+    });
+
+    it('getValue returns callback result', function() {
+        var result = {};
+        var callback = function(time, result) {
+            return result;
+        };
+        var property = new CallbackProperty(callback, true);
+        expect(property.getValue(time, result)).toBe(result);
+    });
+
+    it('isConstant returns correct value', function() {
+        var result = {};
+        var property = new CallbackProperty(function() {
+        }, true);
+        expect(property.isConstant).toBe(true);
+        property.setCallback(function() {
+        }, false);
+        expect(property.isConstant).toBe(false);
+    });
+
+    it('setCallback raises definitionChanged event', function() {
+        var property = new CallbackProperty(function() {
+        }, true);
+        var listener = jasmine.createSpy('listener');
+        property.definitionChanged.addEventListener(listener);
+        property.setCallback(function() {
+        }, false);
+        expect(listener).toHaveBeenCalledWith(property);
+    });
+
+    it('constructor throws with undefined isConstant', function() {
+        expect(function() {
+            return new CallbackProperty(function() {
+            }, undefined);
+        }).toThrowDeveloperError();
+    });
+
+    it('constructor throws with undefined callback', function() {
+        expect(function() {
+            return new CallbackProperty(undefined, true);
+        }).toThrowDeveloperError();
+    });
+
+    it('equals works', function() {
+        var callback = function() {
+        };
+        var left = new CallbackProperty(callback, true);
+        var right = new CallbackProperty(callback, true);
+
+        expect(left.equals(right)).toEqual(true);
+
+        right.setCallback(callback, false);
+        expect(left.equals(right)).toEqual(false);
+
+        right.setCallback(function() {
+            return undefined;
+        }, true);
+        expect(left.equals(right)).toEqual(false);
+    });
+});

Specs/DataSources/ConstantPositionPropertySpec.js

@@ -81,7 +81,7 @@ defineSuite([
         expect(expected).toEqual(PositionProperty.convertToReferenceFrame(time, value, ReferenceFrame.INERTIAL, ReferenceFrame.FIXED));
     });
 
-    it('setValue rasies definitionChanged event', function() {
+    it('setValue raises definitionChanged event', function() {
         var property = new ConstantPositionProperty();
         var listener = jasmine.createSpy('listener');
         property.definitionChanged.addEventListener(listener);

Specs/DataSources/ConstantPropertySpec.js

@@ -27,7 +27,7 @@ defineSuite([
         expect(result).toEqual(value);
     });
 
-    it('setValue rasies definitionChanged event', function() {
+    it('setValue raises definitionChanged event', function() {
         var property = new ConstantProperty();
         var listener = jasmine.createSpy('listener');
         property.definitionChanged.addEventListener(listener);

Specs/DataSources/PositionPropertyArraySpec.js

@@ -31,7 +31,7 @@ defineSuite([
         expect(property.getValue(time)).toEqual(expected);
     });
 
-    it('setValue rasies definitionChanged event', function() {
+    it('setValue raises definitionChanged event', function() {
         var property = new PositionPropertyArray();
         var listener = jasmine.createSpy('listener');
         property.definitionChanged.addEventListener(listener);

Specs/DataSources/PropertyArraySpec.js

@@ -27,7 +27,7 @@ defineSuite([
         expect(property.getValue(time)).toEqual(expected);
     });
 
-    it('setValue rasies definitionChanged event', function() {
+    it('setValue raises definitionChanged event', function() {
         var property = new PropertyArray();
         var listener = jasmine.createSpy('listener');
         property.definitionChanged.addEventListener(listener);