CompositeEntityCollection.js

/*global define*/
define([
        '../Core/createGuid',
        '../Core/defined',
        '../Core/defineProperties',
        '../Core/DeveloperError',
        '../Core/Math',
        './Entity',
        './EntityCollection'
    ], function(
        createGuid,
        defined,
        defineProperties,
        DeveloperError,
        CesiumMath,
        Entity,
        EntityCollection) {
    'use strict';

    var entityOptionsScratch = {
        id : undefined
    };
    var entityIdScratch = new Array(2);

    function clean(entity) {
        var propertyNames = entity.propertyNames;
        var propertyNamesLength = propertyNames.length;
        for (var i = 0; i < propertyNamesLength; i++) {
            entity[propertyNames[i]] = undefined;
        }
    }

    function subscribeToEntity(that, eventHash, collectionId, entity) {
        entityIdScratch[0] = collectionId;
        entityIdScratch[1] = entity.id;
        eventHash[JSON.stringify(entityIdScratch)] = entity.definitionChanged.addEventListener(CompositeEntityCollection.prototype._onDefinitionChanged, that);
    }

    function unsubscribeFromEntity(that, eventHash, collectionId, entity) {
        entityIdScratch[0] = collectionId;
        entityIdScratch[1] = entity.id;
        var id = JSON.stringify(entityIdScratch);
        eventHash[id]();
        eventHash[id] = undefined;
    }

    function recomposite(that) {
        that._shouldRecomposite = true;
        if (that._suspendCount !== 0) {
            return;
        }

        var collections = that._collections;
        var collectionsLength = collections.length;

        var collectionsCopy = that._collectionsCopy;
        var collectionsCopyLength = collectionsCopy.length;

        var i;
        var entity;
        var entities;
        var iEntities;
        var collection;
        var composite = that._composite;
        var newEntities = new EntityCollection(that);
        var eventHash = that._eventHash;
        var collectionId;

        for (i = 0; i < collectionsCopyLength; i++) {
            collection = collectionsCopy[i];
            collection.collectionChanged.removeEventListener(CompositeEntityCollection.prototype._onCollectionChanged, that);
            entities = collection.values;
            collectionId = collection.id;
            for (iEntities = entities.length - 1; iEntities > -1; iEntities--) {
                entity = entities[iEntities];
                unsubscribeFromEntity(that, eventHash, collectionId, entity);
            }
        }

        for (i = collectionsLength - 1; i >= 0; i--) {
            collection = collections[i];
            collection.collectionChanged.addEventListener(CompositeEntityCollection.prototype._onCollectionChanged, that);

            //Merge all of the existing entities.
            entities = collection.values;
            collectionId = collection.id;
            for (iEntities = entities.length - 1; iEntities > -1; iEntities--) {
                entity = entities[iEntities];
                subscribeToEntity(that, eventHash, collectionId, entity);

                var compositeEntity = newEntities.getById(entity.id);
                if (!defined(compositeEntity)) {
                    compositeEntity = composite.getById(entity.id);
                    if (!defined(compositeEntity)) {
                        entityOptionsScratch.id = entity.id;
                        compositeEntity = new Entity(entityOptionsScratch);
                    } else {
                        clean(compositeEntity);
                    }
                    newEntities.add(compositeEntity);
                }
                compositeEntity.merge(entity);
            }
        }
        that._collectionsCopy = collections.slice(0);

        composite.suspendEvents();
        composite.removeAll();
        var newEntitiesArray = newEntities.values;
        for (i = 0; i < newEntitiesArray.length; i++) {
            composite.add(newEntitiesArray[i]);
        }
        composite.resumeEvents();
    }

    /**
     * Non-destructively composites multiple {@link EntityCollection} instances into a single collection.
     * If a Entity with the same ID exists in multiple collections, it is non-destructively
     * merged into a single new entity instance.  If an entity has the same property in multiple
     * collections, the property of the Entity in the last collection of the list it
     * belongs to is used.  CompositeEntityCollection can be used almost anywhere that a
     * EntityCollection is used.
     *
     * @alias CompositeEntityCollection
     * @constructor
     *
     * @param {EntityCollection[]} [collections] The initial list of EntityCollection instances to merge.
     * @param {DataSource|CompositeEntityCollection} [owner] The data source (or composite entity collection) which created this collection.
     */
    function CompositeEntityCollection(collections, owner) {
        this._owner = owner;
        this._composite = new EntityCollection(this);
        this._suspendCount = 0;
        this._collections = defined(collections) ? collections.slice() : [];
        this._collectionsCopy = [];
        this._id = createGuid();
        this._eventHash = {};
        recomposite(this);
        this._shouldRecomposite = false;
    }

    defineProperties(CompositeEntityCollection.prototype, {
        /**
         * Gets the event that is fired when entities are added or removed from the collection.
         * The generated event is a {@link EntityCollection.collectionChangedEventCallback}.
         * @memberof CompositeEntityCollection.prototype
         * @readonly
         * @type {Event}
         */
        collectionChanged : {
            get : function() {
                return this._composite._collectionChanged;
            }
        },
        /**
         * Gets a globally unique identifier for this collection.
         * @memberof CompositeEntityCollection.prototype
         * @readonly
         * @type {String}
         */
        id : {
            get : function() {
                return this._id;
            }
        },
        /**
         * Gets the array of Entity instances in the collection.
         * This array should not be modified directly.
         * @memberof CompositeEntityCollection.prototype
         * @readonly
         * @type {Entity[]}
         */
        values : {
            get : function() {
                return this._composite.values;
            }
        },
        /**
         * Gets the owner of this composite entity collection, ie. the data source or composite entity collection which created it.
         * @memberof CompositeEntityCollection.prototype
         * @readonly
         * @type {DataSource|CompositeEntityCollection}
         */
        owner : {
            get : function() {
                return this._owner;
            }
        }
    });

    /**
     * Adds a collection to the composite.
     *
     * @param {EntityCollection} collection the collection to add.
     * @param {Number} [index] the index to add the collection at.  If omitted, the collection will
     *                         added on top of all existing collections.
     *
     * @exception {DeveloperError} index, if supplied, must be greater than or equal to zero and less than or equal to the number of collections.
     */
    CompositeEntityCollection.prototype.addCollection = function(collection, index) {
        var hasIndex = defined(index);
        //>>includeStart('debug', pragmas.debug);
        if (!defined(collection)) {
            throw new DeveloperError('collection is required.');
        }
        if (hasIndex) {
            if (index < 0) {
                throw new DeveloperError('index must be greater than or equal to zero.');
            } else if (index > this._collections.length) {
                throw new DeveloperError('index must be less than or equal to the number of collections.');
            }
        }
        //>>includeEnd('debug');

        if (!hasIndex) {
            index = this._collections.length;
            this._collections.push(collection);
        } else {
            this._collections.splice(index, 0, collection);
        }

        recomposite(this);
    };

    /**
     * Removes a collection from this composite, if present.
     *
     * @param {EntityCollection} collection The collection to remove.
     * @returns {Boolean} true if the collection was in the composite and was removed,
     *                    false if the collection was not in the composite.
     */
    CompositeEntityCollection.prototype.removeCollection = function(collection) {
        var index = this._collections.indexOf(collection);
        if (index !== -1) {
            this._collections.splice(index, 1);
            recomposite(this);
            return true;
        }
        return false;
    };

    /**
     * Removes all collections from this composite.
     */
    CompositeEntityCollection.prototype.removeAllCollections = function() {
        this._collections.length = 0;
        recomposite(this);
    };

    /**
     * Checks to see if the composite contains a given collection.
     *
     * @param {EntityCollection} collection the collection to check for.
     * @returns {Boolean} true if the composite contains the collection, false otherwise.
     */
    CompositeEntityCollection.prototype.containsCollection = function(collection) {
        return this._collections.indexOf(collection) !== -1;
    };

    /**
     * Returns true if the provided entity is in this collection, false otherwise.
     *
     * @param {Entity} entity The entity.
     * @returns {Boolean} true if the provided entity is in this collection, false otherwise.
     */
    CompositeEntityCollection.prototype.contains = function(entity) {
        return this._composite.contains(entity);
    };

    /**
     * Determines the index of a given collection in the composite.
     *
     * @param {EntityCollection} collection The collection to find the index of.
     * @returns {Number} The index of the collection in the composite, or -1 if the collection does not exist in the composite.
     */
    CompositeEntityCollection.prototype.indexOfCollection = function(collection) {
        return this._collections.indexOf(collection);
    };

    /**
     * Gets a collection by index from the composite.
     *
     * @param {Number} index the index to retrieve.
     */
    CompositeEntityCollection.prototype.getCollection = function(index) {
        //>>includeStart('debug', pragmas.debug);
        if (!defined(index)) {
            throw new DeveloperError('index is required.', 'index');
        }
        //>>includeEnd('debug');

        return this._collections[index];
    };

    /**
     * Gets the number of collections in this composite.
     */
    CompositeEntityCollection.prototype.getCollectionsLength = function() {
        return this._collections.length;
    };

    function getCollectionIndex(collections, collection) {
        //>>includeStart('debug', pragmas.debug);
        if (!defined(collection)) {
            throw new DeveloperError('collection is required.');
        }
        //>>includeEnd('debug');

        var index = collections.indexOf(collection);

        //>>includeStart('debug', pragmas.debug);
        if (index === -1) {
            throw new DeveloperError('collection is not in this composite.');
        }
        //>>includeEnd('debug');

        return index;
    }

    function swapCollections(composite, i, j) {
        var arr = composite._collections;
        i = CesiumMath.clamp(i, 0, arr.length - 1);
        j = CesiumMath.clamp(j, 0, arr.length - 1);

        if (i === j) {
            return;
        }

        var temp = arr[i];
        arr[i] = arr[j];
        arr[j] = temp;

        recomposite(composite);
    }

    /**
     * Raises a collection up one position in the composite.
     *
     * @param {EntityCollection} collection the collection to move.
     *
     * @exception {DeveloperError} collection is not in this composite.
     */
    CompositeEntityCollection.prototype.raiseCollection = function(collection) {
        var index = getCollectionIndex(this._collections, collection);
        swapCollections(this, index, index + 1);
    };

    /**
     * Lowers a collection down one position in the composite.
     *
     * @param {EntityCollection} collection the collection to move.
     *
     * @exception {DeveloperError} collection is not in this composite.
     */
    CompositeEntityCollection.prototype.lowerCollection = function(collection) {
        var index = getCollectionIndex(this._collections, collection);
        swapCollections(this, index, index - 1);
    };

    /**
     * Raises a collection to the top of the composite.
     *
     * @param {EntityCollection} collection the collection to move.
     *
     * @exception {DeveloperError} collection is not in this composite.
     */
    CompositeEntityCollection.prototype.raiseCollectionToTop = function(collection) {
        var index = getCollectionIndex(this._collections, collection);
        if (index === this._collections.length - 1) {
            return;
        }
        this._collections.splice(index, 1);
        this._collections.push(collection);

        recomposite(this);
    };

    /**
     * Lowers a collection to the bottom of the composite.
     *
     * @param {EntityCollection} collection the collection to move.
     *
     * @exception {DeveloperError} collection is not in this composite.
     */
    CompositeEntityCollection.prototype.lowerCollectionToBottom = function(collection) {
        var index = getCollectionIndex(this._collections, collection);
        if (index === 0) {
            return;
        }
        this._collections.splice(index, 1);
        this._collections.splice(0, 0, collection);

        recomposite(this);
    };

    /**
     * Prevents {@link EntityCollection#collectionChanged} events from being raised
     * until a corresponding call is made to {@link EntityCollection#resumeEvents}, at which
     * point a single event will be raised that covers all suspended operations.
     * This allows for many items to be added and removed efficiently.
     * While events are suspended, recompositing of the collections will
     * also be suspended, as this can be a costly operation.
     * This function can be safely called multiple times as long as there
     * are corresponding calls to {@link EntityCollection#resumeEvents}.
     */
    CompositeEntityCollection.prototype.suspendEvents = function() {
        this._suspendCount++;
        this._composite.suspendEvents();
    };

    /**
     * Resumes raising {@link EntityCollection#collectionChanged} events immediately
     * when an item is added or removed.  Any modifications made while while events were suspended
     * will be triggered as a single event when this function is called.  This function also ensures
     * the collection is recomposited if events are also resumed.
     * This function is reference counted and can safely be called multiple times as long as there
     * are corresponding calls to {@link EntityCollection#resumeEvents}.
     *
     * @exception {DeveloperError} resumeEvents can not be called before suspendEvents.
     */
    CompositeEntityCollection.prototype.resumeEvents = function() {
        //>>includeStart('debug', pragmas.debug);
        if (this._suspendCount === 0) {
            throw new DeveloperError('resumeEvents can not be called before suspendEvents.');
        }
        //>>includeEnd('debug');

        this._suspendCount--;
        // recomposite before triggering events (but only if required for performance) that might depend on a composited collection
        if (this._shouldRecomposite && this._suspendCount === 0) {
            recomposite(this);
            this._shouldRecomposite = false;
        }

        this._composite.resumeEvents();
    };

    /**
     * Computes the maximum availability of the entities in the collection.
     * If the collection contains a mix of infinitely available data and non-infinite data,
     * It will return the interval pertaining to the non-infinite data only.  If all
     * data is infinite, an infinite interval will be returned.
     *
     * @returns {TimeInterval} The availability of entities in the collection.
     */
    CompositeEntityCollection.prototype.computeAvailability = function() {
        return this._composite.computeAvailability();
    };

    /**
     * Gets an entity with the specified id.
     *
     * @param {Object} id The id of the entity to retrieve.
     * @returns {Entity} The entity with the provided id or undefined if the id did not exist in the collection.
     */
    CompositeEntityCollection.prototype.getById = function(id) {
        return this._composite.getById(id);
    };

    CompositeEntityCollection.prototype._onCollectionChanged = function(collection, added, removed) {
        var collections = this._collectionsCopy;
        var collectionsLength = collections.length;
        var composite = this._composite;
        composite.suspendEvents();

        var i;
        var q;
        var entity;
        var compositeEntity;
        var removedLength = removed.length;
        var eventHash = this._eventHash;
        var collectionId = collection.id;
        for (i = 0; i < removedLength; i++) {
            var removedEntity = removed[i];
            unsubscribeFromEntity(this, eventHash, collectionId, removedEntity);

            var removedId = removedEntity.id;
            //Check if the removed entity exists in any of the remaining collections
            //If so, we clean and remerge it.
            for (q = collectionsLength - 1; q >= 0; q--) {
                entity = collections[q].getById(removedId);
                if (defined(entity)) {
                    if (!defined(compositeEntity)) {
                        compositeEntity = composite.getById(removedId);
                        clean(compositeEntity);
                    }
                    compositeEntity.merge(entity);
                }
            }
            //We never retrieved the compositeEntity, which means it no longer
            //exists in any of the collections, remove it from the composite.
            if (!defined(compositeEntity)) {
                composite.removeById(removedId);
            }
            compositeEntity = undefined;
        }

        var addedLength = added.length;
        for (i = 0; i < addedLength; i++) {
            var addedEntity = added[i];
            subscribeToEntity(this, eventHash, collectionId, addedEntity);

            var addedId = addedEntity.id;
            //We know the added entity exists in at least one collection,
            //but we need to check all collections and re-merge in order
            //to maintain the priority of properties.
            for (q = collectionsLength - 1; q >= 0; q--) {
                entity = collections[q].getById(addedId);
                if (defined(entity)) {
                    if (!defined(compositeEntity)) {
                        compositeEntity = composite.getById(addedId);
                        if (!defined(compositeEntity)) {
                            entityOptionsScratch.id = addedId;
                            compositeEntity = new Entity(entityOptionsScratch);
                            composite.add(compositeEntity);
                        } else {
                            clean(compositeEntity);
                        }
                    }
                    compositeEntity.merge(entity);
                }
            }
            compositeEntity = undefined;
        }

        composite.resumeEvents();
    };

    CompositeEntityCollection.prototype._onDefinitionChanged = function(entity, propertyName, newValue, oldValue) {
        var collections = this._collections;
        var composite = this._composite;

        var collectionsLength = collections.length;
        var id = entity.id;
        var compositeEntity = composite.getById(id);
        var compositeProperty = compositeEntity[propertyName];
        var newProperty = !defined(compositeProperty);

        var firstTime = true;
        for (var q = collectionsLength - 1; q >= 0; q--) {
            var innerEntity = collections[q].getById(entity.id);
            if (defined(innerEntity)) {
                var property = innerEntity[propertyName];
                if (defined(property)) {
                    if (firstTime) {
                        firstTime = false;
                        //We only want to clone if the property is also mergeable.
                        //This ensures that leaf properties are referenced and not copied,
                        //which is the entire point of compositing.
                        if (defined(property.merge) && defined(property.clone)) {
                            compositeProperty = property.clone(compositeProperty);
                        } else {
                            compositeProperty = property;
                            break;
                        }
                    }
                    compositeProperty.merge(property);
                }
            }
        }

        if (newProperty && compositeEntity.propertyNames.indexOf(propertyName) === -1) {
            compositeEntity.addProperty(propertyName);
        }

        compositeEntity[propertyName] = compositeProperty;
    };

    return CompositeEntityCollection;
});