Source: DataSources/CompositeEntityCollection.js

  1. /*global define*/
  2. define([
  3.         '../Core/createGuid',
  4.         '../Core/defined',
  5.         '../Core/defineProperties',
  6.         '../Core/DeveloperError',
  7.         '../Core/Math',
  8.         './Entity',
  9.         './EntityCollection'
  10.     ], function(
  11.         createGuid,
  12.         defined,
  13.         defineProperties,
  14.         DeveloperError,
  15.         CesiumMath,
  16.         Entity,
  17.         EntityCollection) {
  18.     'use strict';
  20.     var entityOptionsScratch = {
  21.         id : undefined
  22.     };
  23.     var entityIdScratch = new Array(2);
  25.     function clean(entity) {
  26.         var propertyNames = entity.propertyNames;
  27.         var propertyNamesLength = propertyNames.length;
  28.         for (var i = 0; i < propertyNamesLength; i++) {
  29.             entity[propertyNames[i]] = undefined;
  30.         }
  31.     }
  33.     function subscribeToEntity(that, eventHash, collectionId, entity) {
  34.         entityIdScratch[0] = collectionId;
  35.         entityIdScratch[1] = entity.id;
  36.         eventHash[JSON.stringify(entityIdScratch)] = entity.definitionChanged.addEventListener(CompositeEntityCollection.prototype._onDefinitionChanged, that);
  37.     }
  39.     function unsubscribeFromEntity(that, eventHash, collectionId, entity) {
  40.         entityIdScratch[0] = collectionId;
  41.         entityIdScratch[1] = entity.id;
  42.         var id = JSON.stringify(entityIdScratch);
  43.         eventHash[id]();
  44.         eventHash[id] = undefined;
  45.     }
  47.     function recomposite(that) {
  48.         that._shouldRecomposite = true;
  49.         if (that._suspendCount !== 0) {
  50.             return;
  51.         }
  53.         var collections = that._collections;
  54.         var collectionsLength = collections.length;
  56.         var collectionsCopy = that._collectionsCopy;
  57.         var collectionsCopyLength = collectionsCopy.length;
  59.         var i;
  60.         var entity;
  61.         var entities;
  62.         var iEntities;
  63.         var collection;
  64.         var composite = that._composite;
  65.         var newEntities = new EntityCollection(that);
  66.         var eventHash = that._eventHash;
  67.         var collectionId;
  69.         for (i = 0; i < collectionsCopyLength; i++) {
  70.             collection = collectionsCopy[i];
  71.             collection.collectionChanged.removeEventListener(CompositeEntityCollection.prototype._onCollectionChanged, that);
  72.             entities = collection.values;
  73.             collectionId = collection.id;
  74.             for (iEntities = entities.length - 1; iEntities > -1; iEntities--) {
  75.                 entity = entities[iEntities];
  76.                 unsubscribeFromEntity(that, eventHash, collectionId, entity);
  77.             }
  78.         }
  80.         for (i = collectionsLength - 1; i >= 0; i--) {
  81.             collection = collections[i];
  82.             collection.collectionChanged.addEventListener(CompositeEntityCollection.prototype._onCollectionChanged, that);
  84.             //Merge all of the existing entities.
  85.             entities = collection.values;
  86.             collectionId = collection.id;
  87.             for (iEntities = entities.length - 1; iEntities > -1; iEntities--) {
  88.                 entity = entities[iEntities];
  89.                 subscribeToEntity(that, eventHash, collectionId, entity);
  91.                 var compositeEntity = newEntities.getById(entity.id);
  92.                 if (!defined(compositeEntity)) {
  93.                     compositeEntity = composite.getById(entity.id);
  94.                     if (!defined(compositeEntity)) {
  95.                         entityOptionsScratch.id = entity.id;
  96.                         compositeEntity = new Entity(entityOptionsScratch);
  97.                     } else {
  98.                         clean(compositeEntity);
  99.                     }
  100.                     newEntities.add(compositeEntity);
  101.                 }
  102.                 compositeEntity.merge(entity);
  103.             }
  104.         }
  105.         that._collectionsCopy = collections.slice(0);
  107.         composite.suspendEvents();
  108.         composite.removeAll();
  109.         var newEntitiesArray = newEntities.values;
  110.         for (i = 0; i < newEntitiesArray.length; i++) {
  111.             composite.add(newEntitiesArray[i]);
  112.         }
  113.         composite.resumeEvents();
  114.     }
  116.     /**
  117.      * Non-destructively composites multiple {@link EntityCollection} instances into a single collection.
  118.      * If a Entity with the same ID exists in multiple collections, it is non-destructively
  119.      * merged into a single new entity instance.  If an entity has the same property in multiple
  120.      * collections, the property of the Entity in the last collection of the list it
  121.      * belongs to is used.  CompositeEntityCollection can be used almost anywhere that a
  122.      * EntityCollection is used.
  123.      *
  124.      * @alias CompositeEntityCollection
  125.      * @constructor
  126.      *
  127.      * @param {EntityCollection[]} [collections] The initial list of EntityCollection instances to merge.
  128.      * @param {DataSource|CompositeEntityCollection} [owner] The data source (or composite entity collection) which created this collection.
  129.      */
  130.     function CompositeEntityCollection(collections, owner) {
  131.         this._owner = owner;
  132.         this._composite = new EntityCollection(this);
  133.         this._suspendCount = 0;
  134.         this._collections = defined(collections) ? collections.slice() : [];
  135.         this._collectionsCopy = [];
  136.         this._id = createGuid();
  137.         this._eventHash = {};
  138.         recomposite(this);
  139.         this._shouldRecomposite = false;
  140.     }
  142.     defineProperties(CompositeEntityCollection.prototype, {
  143.         /**
  144.          * Gets the event that is fired when entities are added or removed from the collection.
  145.          * The generated event is a {@link EntityCollection.collectionChangedEventCallback}.
  146.          * @memberof CompositeEntityCollection.prototype
  147.          * @readonly
  148.          * @type {Event}
  149.          */
  150.         collectionChanged : {
  151.             get : function() {
  152.                 return this._composite._collectionChanged;
  153.             }
  154.         },
  155.         /**
  156.          * Gets a globally unique identifier for this collection.
  157.          * @memberof CompositeEntityCollection.prototype
  158.          * @readonly
  159.          * @type {String}
  160.          */
  161.         id : {
  162.             get : function() {
  163.                 return this._id;
  164.             }
  165.         },
  166.         /**
  167.          * Gets the array of Entity instances in the collection.
  168.          * This array should not be modified directly.
  169.          * @memberof CompositeEntityCollection.prototype
  170.          * @readonly
  171.          * @type {Entity[]}
  172.          */
  173.         values : {
  174.             get : function() {
  175.                 return this._composite.values;
  176.             }
  177.         },
  178.         /**
  179.          * Gets the owner of this composite entity collection, ie. the data source or composite entity collection which created it.
  180.          * @memberof CompositeEntityCollection.prototype
  181.          * @readonly
  182.          * @type {DataSource|CompositeEntityCollection}
  183.          */
  184.         owner : {
  185.             get : function() {
  186.                 return this._owner;
  187.             }
  188.         }
  189.     });
  191.     /**
  192.      * Adds a collection to the composite.
  193.      *
  194.      * @param {EntityCollection} collection the collection to add.
  195.      * @param {Number} [index] the index to add the collection at.  If omitted, the collection will
  196.      *                         added on top of all existing collections.
  197.      *
  198.      * @exception {DeveloperError} index, if supplied, must be greater than or equal to zero and less than or equal to the number of collections.
  199.      */
  200.     CompositeEntityCollection.prototype.addCollection = function(collection, index) {
  201.         var hasIndex = defined(index);
  202.         //>>includeStart('debug', pragmas.debug);
  203.         if (!defined(collection)) {
  204.             throw new DeveloperError('collection is required.');
  205.         }
  206.         if (hasIndex) {
  207.             if (index < 0) {
  208.                 throw new DeveloperError('index must be greater than or equal to zero.');
  209.             } else if (index > this._collections.length) {
  210.                 throw new DeveloperError('index must be less than or equal to the number of collections.');
  211.             }
  212.         }
  213.         //>>includeEnd('debug');
  215.         if (!hasIndex) {
  216.             index = this._collections.length;
  217.             this._collections.push(collection);
  218.         } else {
  219.             this._collections.splice(index, 0, collection);
  220.         }
  222.         recomposite(this);
  223.     };
  225.     /**
  226.      * Removes a collection from this composite, if present.
  227.      *
  228.      * @param {EntityCollection} collection The collection to remove.
  229.      * @returns {Boolean} true if the collection was in the composite and was removed,
  230.      *                    false if the collection was not in the composite.
  231.      */
  232.     CompositeEntityCollection.prototype.removeCollection = function(collection) {
  233.         var index = this._collections.indexOf(collection);
  234.         if (index !== -1) {
  235.             this._collections.splice(index, 1);
  236.             recomposite(this);
  237.             return true;
  238.         }
  239.         return false;
  240.     };
  242.     /**
  243.      * Removes all collections from this composite.
  244.      */
  245.     CompositeEntityCollection.prototype.removeAllCollections = function() {
  246.         this._collections.length = 0;
  247.         recomposite(this);
  248.     };
  250.     /**
  251.      * Checks to see if the composite contains a given collection.
  252.      *
  253.      * @param {EntityCollection} collection the collection to check for.
  254.      * @returns {Boolean} true if the composite contains the collection, false otherwise.
  255.      */
  256.     CompositeEntityCollection.prototype.containsCollection = function(collection) {
  257.         return this._collections.indexOf(collection) !== -1;
  258.     };
  260.     /**
  261.      * Returns true if the provided entity is in this collection, false otherwise.
  262.      *
  263.      * @param {Entity} entity The entity.
  264.      * @returns {Boolean} true if the provided entity is in this collection, false otherwise.
  265.      */
  266.     CompositeEntityCollection.prototype.contains = function(entity) {
  267.         return this._composite.contains(entity);
  268.     };
  270.     /**
  271.      * Determines the index of a given collection in the composite.
  272.      *
  273.      * @param {EntityCollection} collection The collection to find the index of.
  274.      * @returns {Number} The index of the collection in the composite, or -1 if the collection does not exist in the composite.
  275.      */
  276.     CompositeEntityCollection.prototype.indexOfCollection = function(collection) {
  277.         return this._collections.indexOf(collection);
  278.     };
  280.     /**
  281.      * Gets a collection by index from the composite.
  282.      *
  283.      * @param {Number} index the index to retrieve.
  284.      */
  285.     CompositeEntityCollection.prototype.getCollection = function(index) {
  286.         //>>includeStart('debug', pragmas.debug);
  287.         if (!defined(index)) {
  288.             throw new DeveloperError('index is required.', 'index');
  289.         }
  290.         //>>includeEnd('debug');
  292.         return this._collections[index];
  293.     };
  295.     /**
  296.      * Gets the number of collections in this composite.
  297.      */
  298.     CompositeEntityCollection.prototype.getCollectionsLength = function() {
  299.         return this._collections.length;
  300.     };
  302.     function getCollectionIndex(collections, collection) {
  303.         //>>includeStart('debug', pragmas.debug);
  304.         if (!defined(collection)) {
  305.             throw new DeveloperError('collection is required.');
  306.         }
  307.         //>>includeEnd('debug');
  309.         var index = collections.indexOf(collection);
  311.         //>>includeStart('debug', pragmas.debug);
  312.         if (index === -1) {
  313.             throw new DeveloperError('collection is not in this composite.');
  314.         }
  315.         //>>includeEnd('debug');
  317.         return index;
  318.     }
  320.     function swapCollections(composite, i, j) {
  321.         var arr = composite._collections;
  322.         i = CesiumMath.clamp(i, 0, arr.length - 1);
  323.         j = CesiumMath.clamp(j, 0, arr.length - 1);
  325.         if (i === j) {
  326.             return;
  327.         }
  329.         var temp = arr[i];
  330.         arr[i] = arr[j];
  331.         arr[j] = temp;
  333.         recomposite(composite);
  334.     }
  336.     /**
  337.      * Raises a collection up one position in the composite.
  338.      *
  339.      * @param {EntityCollection} collection the collection to move.
  340.      *
  341.      * @exception {DeveloperError} collection is not in this composite.
  342.      */
  343.     CompositeEntityCollection.prototype.raiseCollection = function(collection) {
  344.         var index = getCollectionIndex(this._collections, collection);
  345.         swapCollections(this, index, index + 1);
  346.     };
  348.     /**
  349.      * Lowers a collection down one position in the composite.
  350.      *
  351.      * @param {EntityCollection} collection the collection to move.
  352.      *
  353.      * @exception {DeveloperError} collection is not in this composite.
  354.      */
  355.     CompositeEntityCollection.prototype.lowerCollection = function(collection) {
  356.         var index = getCollectionIndex(this._collections, collection);
  357.         swapCollections(this, index, index - 1);
  358.     };
  360.     /**
  361.      * Raises a collection to the top of the composite.
  362.      *
  363.      * @param {EntityCollection} collection the collection to move.
  364.      *
  365.      * @exception {DeveloperError} collection is not in this composite.
  366.      */
  367.     CompositeEntityCollection.prototype.raiseCollectionToTop = function(collection) {
  368.         var index = getCollectionIndex(this._collections, collection);
  369.         if (index === this._collections.length - 1) {
  370.             return;
  371.         }
  372.         this._collections.splice(index, 1);
  373.         this._collections.push(collection);
  375.         recomposite(this);
  376.     };
  378.     /**
  379.      * Lowers a collection to the bottom of the composite.
  380.      *
  381.      * @param {EntityCollection} collection the collection to move.
  382.      *
  383.      * @exception {DeveloperError} collection is not in this composite.
  384.      */
  385.     CompositeEntityCollection.prototype.lowerCollectionToBottom = function(collection) {
  386.         var index = getCollectionIndex(this._collections, collection);
  387.         if (index === 0) {
  388.             return;
  389.         }
  390.         this._collections.splice(index, 1);
  391.         this._collections.splice(0, 0, collection);
  393.         recomposite(this);
  394.     };
  396.     /**
  397.      * Prevents {@link EntityCollection#collectionChanged} events from being raised
  398.      * until a corresponding call is made to {@link EntityCollection#resumeEvents}, at which
  399.      * point a single event will be raised that covers all suspended operations.
  400.      * This allows for many items to be added and removed efficiently.
  401.      * While events are suspended, recompositing of the collections will
  402.      * also be suspended, as this can be a costly operation.
  403.      * This function can be safely called multiple times as long as there
  404.      * are corresponding calls to {@link EntityCollection#resumeEvents}.
  405.      */
  406.     CompositeEntityCollection.prototype.suspendEvents = function() {
  407.         this._suspendCount++;
  408.         this._composite.suspendEvents();
  409.     };
  411.     /**
  412.      * Resumes raising {@link EntityCollection#collectionChanged} events immediately
  413.      * when an item is added or removed.  Any modifications made while while events were suspended
  414.      * will be triggered as a single event when this function is called.  This function also ensures
  415.      * the collection is recomposited if events are also resumed.
  416.      * This function is reference counted and can safely be called multiple times as long as there
  417.      * are corresponding calls to {@link EntityCollection#resumeEvents}.
  418.      *
  419.      * @exception {DeveloperError} resumeEvents can not be called before suspendEvents.
  420.      */
  421.     CompositeEntityCollection.prototype.resumeEvents = function() {
  422.         //>>includeStart('debug', pragmas.debug);
  423.         if (this._suspendCount === 0) {
  424.             throw new DeveloperError('resumeEvents can not be called before suspendEvents.');
  425.         }
  426.         //>>includeEnd('debug');
  428.         this._suspendCount--;
  429.         // recomposite before triggering events (but only if required for performance) that might depend on a composited collection
  430.         if (this._shouldRecomposite && this._suspendCount === 0) {
  431.             recomposite(this);
  432.             this._shouldRecomposite = false;
  433.         }
  435.         this._composite.resumeEvents();
  436.     };
  438.     /**
  439.      * Computes the maximum availability of the entities in the collection.
  440.      * If the collection contains a mix of infinitely available data and non-infinite data,
  441.      * It will return the interval pertaining to the non-infinite data only.  If all
  442.      * data is infinite, an infinite interval will be returned.
  443.      *
  444.      * @returns {TimeInterval} The availability of entities in the collection.
  445.      */
  446.     CompositeEntityCollection.prototype.computeAvailability = function() {
  447.         return this._composite.computeAvailability();
  448.     };
  450.     /**
  451.      * Gets an entity with the specified id.
  452.      *
  453.      * @param {Object} id The id of the entity to retrieve.
  454.      * @returns {Entity} The entity with the provided id or undefined if the id did not exist in the collection.
  455.      */
  456.     CompositeEntityCollection.prototype.getById = function(id) {
  457.         return this._composite.getById(id);
  458.     };
  460.     CompositeEntityCollection.prototype._onCollectionChanged = function(collection, added, removed) {
  461.         var collections = this._collectionsCopy;
  462.         var collectionsLength = collections.length;
  463.         var composite = this._composite;
  464.         composite.suspendEvents();
  466.         var i;
  467.         var q;
  468.         var entity;
  469.         var compositeEntity;
  470.         var removedLength = removed.length;
  471.         var eventHash = this._eventHash;
  472.         var collectionId = collection.id;
  473.         for (i = 0; i < removedLength; i++) {
  474.             var removedEntity = removed[i];
  475.             unsubscribeFromEntity(this, eventHash, collectionId, removedEntity);
  477.             var removedId = removedEntity.id;
  478.             //Check if the removed entity exists in any of the remaining collections
  479.             //If so, we clean and remerge it.
  480.             for (q = collectionsLength - 1; q >= 0; q--) {
  481.                 entity = collections[q].getById(removedId);
  482.                 if (defined(entity)) {
  483.                     if (!defined(compositeEntity)) {
  484.                         compositeEntity = composite.getById(removedId);
  485.                         clean(compositeEntity);
  486.                     }
  487.                     compositeEntity.merge(entity);
  488.                 }
  489.             }
  490.             //We never retrieved the compositeEntity, which means it no longer
  491.             //exists in any of the collections, remove it from the composite.
  492.             if (!defined(compositeEntity)) {
  493.                 composite.removeById(removedId);
  494.             }
  495.             compositeEntity = undefined;
  496.         }
  498.         var addedLength = added.length;
  499.         for (i = 0; i < addedLength; i++) {
  500.             var addedEntity = added[i];
  501.             subscribeToEntity(this, eventHash, collectionId, addedEntity);
  503.             var addedId = addedEntity.id;
  504.             //We know the added entity exists in at least one collection,
  505.             //but we need to check all collections and re-merge in order
  506.             //to maintain the priority of properties.
  507.             for (q = collectionsLength - 1; q >= 0; q--) {
  508.                 entity = collections[q].getById(addedId);
  509.                 if (defined(entity)) {
  510.                     if (!defined(compositeEntity)) {
  511.                         compositeEntity = composite.getById(addedId);
  512.                         if (!defined(compositeEntity)) {
  513.                             entityOptionsScratch.id = addedId;
  514.                             compositeEntity = new Entity(entityOptionsScratch);
  515.                             composite.add(compositeEntity);
  516.                         } else {
  517.                             clean(compositeEntity);
  518.                         }
  519.                     }
  520.                     compositeEntity.merge(entity);
  521.                 }
  522.             }
  523.             compositeEntity = undefined;
  524.         }
  526.         composite.resumeEvents();
  527.     };
  529.     CompositeEntityCollection.prototype._onDefinitionChanged = function(entity, propertyName, newValue, oldValue) {
  530.         var collections = this._collections;
  531.         var composite = this._composite;
  533.         var collectionsLength = collections.length;
  534.         var id = entity.id;
  535.         var compositeEntity = composite.getById(id);
  536.         var compositeProperty = compositeEntity[propertyName];
  537.         var newProperty = !defined(compositeProperty);
  539.         var firstTime = true;
  540.         for (var q = collectionsLength - 1; q >= 0; q--) {
  541.             var innerEntity = collections[q].getById(entity.id);
  542.             if (defined(innerEntity)) {
  543.                 var property = innerEntity[propertyName];
  544.                 if (defined(property)) {
  545.                     if (firstTime) {
  546.                         firstTime = false;
  547.                         //We only want to clone if the property is also mergeable.
  548.                         //This ensures that leaf properties are referenced and not copied,
  549.                         //which is the entire point of compositing.
  550.                         if (defined(property.merge) && defined(property.clone)) {
  551.                             compositeProperty = property.clone(compositeProperty);
  552.                         } else {
  553.                             compositeProperty = property;
  554.                             break;
  555.                         }
  556.                     }
  557.                     compositeProperty.merge(property);
  558.                 }
  559.             }
  560.         }
  562.         if (newProperty && compositeEntity.propertyNames.indexOf(propertyName) === -1) {
  563.             compositeEntity.addProperty(propertyName);
  564.         }
  566.         compositeEntity[propertyName] = compositeProperty;
  567.     };
  569.     return CompositeEntityCollection;
  570. });