DataSourceCollection.js 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334
  1. import defaultValue from '../Core/defaultValue.js';
  2. import defined from '../Core/defined.js';
  3. import defineProperties from '../Core/defineProperties.js';
  4. import destroyObject from '../Core/destroyObject.js';
  5. import DeveloperError from '../Core/DeveloperError.js';
  6. import Event from '../Core/Event.js';
  7. import CesiumMath from '../Core/Math.js';
  8. import when from '../ThirdParty/when.js';
  9. /**
  10. * A collection of {@link DataSource} instances.
  11. * @alias DataSourceCollection
  12. * @constructor
  13. */
  14. function DataSourceCollection() {
  15. this._dataSources = [];
  16. this._dataSourceAdded = new Event();
  17. this._dataSourceRemoved = new Event();
  18. this._dataSourceMoved = new Event();
  19. }
  20. defineProperties(DataSourceCollection.prototype, {
  21. /**
  22. * Gets the number of data sources in this collection.
  23. * @memberof DataSourceCollection.prototype
  24. * @type {Number}
  25. * @readonly
  26. */
  27. length : {
  28. get : function() {
  29. return this._dataSources.length;
  30. }
  31. },
  32. /**
  33. * An event that is raised when a data source is added to the collection.
  34. * Event handlers are passed the data source that was added.
  35. * @memberof DataSourceCollection.prototype
  36. * @type {Event}
  37. * @readonly
  38. */
  39. dataSourceAdded : {
  40. get : function() {
  41. return this._dataSourceAdded;
  42. }
  43. },
  44. /**
  45. * An event that is raised when a data source is removed from the collection.
  46. * Event handlers are passed the data source that was removed.
  47. * @memberof DataSourceCollection.prototype
  48. * @type {Event}
  49. * @readonly
  50. */
  51. dataSourceRemoved : {
  52. get : function() {
  53. return this._dataSourceRemoved;
  54. }
  55. },
  56. /**
  57. * An event that is raised when a data source changes position in the collection. Event handlers are passed the data source
  58. * that was moved, its new index after the move, and its old index prior to the move.
  59. * @memberof DataSourceCollection.prototype
  60. * @type {Event}
  61. * @readonly
  62. */
  63. dataSourceMoved : {
  64. get : function() {
  65. return this._dataSourceMoved;
  66. }
  67. }
  68. });
  69. /**
  70. * Adds a data source to the collection.
  71. *
  72. * @param {DataSource|Promise.<DataSource>} dataSource A data source or a promise to a data source to add to the collection.
  73. * When passing a promise, the data source will not actually be added
  74. * to the collection until the promise resolves successfully.
  75. * @returns {Promise.<DataSource>} A Promise that resolves once the data source has been added to the collection.
  76. */
  77. DataSourceCollection.prototype.add = function(dataSource) {
  78. //>>includeStart('debug', pragmas.debug);
  79. if (!defined(dataSource)) {
  80. throw new DeveloperError('dataSource is required.');
  81. }
  82. //>>includeEnd('debug');
  83. var that = this;
  84. var dataSources = this._dataSources;
  85. return when(dataSource, function(value) {
  86. //Only add the data source if removeAll has not been called
  87. //Since it was added.
  88. if (dataSources === that._dataSources) {
  89. that._dataSources.push(value);
  90. that._dataSourceAdded.raiseEvent(that, value);
  91. }
  92. return value;
  93. });
  94. };
  95. /**
  96. * Removes a data source from this collection, if present.
  97. *
  98. * @param {DataSource} dataSource The data source to remove.
  99. * @param {Boolean} [destroy=false] Whether to destroy the data source in addition to removing it.
  100. * @returns {Boolean} true if the data source was in the collection and was removed,
  101. * false if the data source was not in the collection.
  102. */
  103. DataSourceCollection.prototype.remove = function(dataSource, destroy) {
  104. destroy = defaultValue(destroy, false);
  105. var index = this._dataSources.indexOf(dataSource);
  106. if (index !== -1) {
  107. this._dataSources.splice(index, 1);
  108. this._dataSourceRemoved.raiseEvent(this, dataSource);
  109. if (destroy && typeof dataSource.destroy === 'function') {
  110. dataSource.destroy();
  111. }
  112. return true;
  113. }
  114. return false;
  115. };
  116. /**
  117. * Removes all data sources from this collection.
  118. *
  119. * @param {Boolean} [destroy=false] whether to destroy the data sources in addition to removing them.
  120. */
  121. DataSourceCollection.prototype.removeAll = function(destroy) {
  122. destroy = defaultValue(destroy, false);
  123. var dataSources = this._dataSources;
  124. for (var i = 0, len = dataSources.length; i < len; ++i) {
  125. var dataSource = dataSources[i];
  126. this._dataSourceRemoved.raiseEvent(this, dataSource);
  127. if (destroy && typeof dataSource.destroy === 'function') {
  128. dataSource.destroy();
  129. }
  130. }
  131. this._dataSources = [];
  132. };
  133. /**
  134. * Checks to see if the collection contains a given data source.
  135. *
  136. * @param {DataSource} dataSource The data source to check for.
  137. * @returns {Boolean} true if the collection contains the data source, false otherwise.
  138. */
  139. DataSourceCollection.prototype.contains = function(dataSource) {
  140. return this.indexOf(dataSource) !== -1;
  141. };
  142. /**
  143. * Determines the index of a given data source in the collection.
  144. *
  145. * @param {DataSource} dataSource The data source to find the index of.
  146. * @returns {Number} The index of the data source in the collection, or -1 if the data source does not exist in the collection.
  147. */
  148. DataSourceCollection.prototype.indexOf = function(dataSource) {
  149. return this._dataSources.indexOf(dataSource);
  150. };
  151. /**
  152. * Gets a data source by index from the collection.
  153. *
  154. * @param {Number} index the index to retrieve.
  155. * @returns {DataSource} The data source at the specified index.
  156. */
  157. DataSourceCollection.prototype.get = function(index) {
  158. //>>includeStart('debug', pragmas.debug);
  159. if (!defined(index)) {
  160. throw new DeveloperError('index is required.');
  161. }
  162. //>>includeEnd('debug');
  163. return this._dataSources[index];
  164. };
  165. /**
  166. * Gets a data source by name from the collection.
  167. *
  168. * @param {String} name The name to retrieve.
  169. * @returns {DataSource[]} A list of all data sources matching the provided name.
  170. */
  171. DataSourceCollection.prototype.getByName = function(name) {
  172. //>>includeStart('debug', pragmas.debug);
  173. if (!defined(name)) {
  174. throw new DeveloperError('name is required.');
  175. }
  176. //>>includeEnd('debug');
  177. return this._dataSources.filter(function(dataSource) {
  178. return dataSource.name === name;
  179. });
  180. };
  181. function getIndex(dataSources, dataSource) {
  182. //>>includeStart('debug', pragmas.debug);
  183. if (!defined(dataSource)) {
  184. throw new DeveloperError('dataSource is required.');
  185. }
  186. //>>includeEnd('debug');
  187. var index = dataSources.indexOf(dataSource);
  188. //>>includeStart('debug', pragmas.debug);
  189. if (index === -1) {
  190. throw new DeveloperError('dataSource is not in this collection.');
  191. }
  192. //>>includeEnd('debug');
  193. return index;
  194. }
  195. function swapDataSources(collection, i, j) {
  196. var arr = collection._dataSources;
  197. var length = arr.length - 1;
  198. i = CesiumMath.clamp(i, 0, length);
  199. j = CesiumMath.clamp(j, 0, length);
  200. if (i === j) {
  201. return;
  202. }
  203. var temp = arr[i];
  204. arr[i] = arr[j];
  205. arr[j] = temp;
  206. collection.dataSourceMoved.raiseEvent(temp, j, i);
  207. }
  208. /**
  209. * Raises a data source up one position in the collection.
  210. *
  211. * @param {DataSource} dataSource The data source to move.
  212. *
  213. * @exception {DeveloperError} dataSource is not in this collection.
  214. * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
  215. */
  216. DataSourceCollection.prototype.raise = function(dataSource) {
  217. var index = getIndex(this._dataSources, dataSource);
  218. swapDataSources(this, index, index + 1);
  219. };
  220. /**
  221. * Lowers a data source down one position in the collection.
  222. *
  223. * @param {DataSource} dataSource The data source to move.
  224. *
  225. * @exception {DeveloperError} dataSource is not in this collection.
  226. * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
  227. */
  228. DataSourceCollection.prototype.lower = function(dataSource) {
  229. var index = getIndex(this._dataSources, dataSource);
  230. swapDataSources(this, index, index - 1);
  231. };
  232. /**
  233. * Raises a data source to the top of the collection.
  234. *
  235. * @param {DataSource} dataSource The data source to move.
  236. *
  237. * @exception {DeveloperError} dataSource is not in this collection.
  238. * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
  239. */
  240. DataSourceCollection.prototype.raiseToTop = function(dataSource) {
  241. var index = getIndex(this._dataSources, dataSource);
  242. if (index === this._dataSources.length - 1) {
  243. return;
  244. }
  245. this._dataSources.splice(index, 1);
  246. this._dataSources.push(dataSource);
  247. this.dataSourceMoved.raiseEvent(dataSource, this._dataSources.length - 1, index);
  248. };
  249. /**
  250. * Lowers a data source to the bottom of the collection.
  251. *
  252. * @param {DataSource} dataSource The data source to move.
  253. *
  254. * @exception {DeveloperError} dataSource is not in this collection.
  255. * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
  256. */
  257. DataSourceCollection.prototype.lowerToBottom = function(dataSource) {
  258. var index = getIndex(this._dataSources, dataSource);
  259. if (index === 0) {
  260. return;
  261. }
  262. this._dataSources.splice(index, 1);
  263. this._dataSources.splice(0, 0, dataSource);
  264. this.dataSourceMoved.raiseEvent(dataSource, 0, index);
  265. };
  266. /**
  267. * Returns true if this object was destroyed; otherwise, false.
  268. * If this object was destroyed, it should not be used; calling any function other than
  269. * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
  270. *
  271. * @returns {Boolean} true if this object was destroyed; otherwise, false.
  272. *
  273. * @see DataSourceCollection#destroy
  274. */
  275. DataSourceCollection.prototype.isDestroyed = function() {
  276. return false;
  277. };
  278. /**
  279. * Destroys the resources held by all data sources in this collection. Explicitly destroying this
  280. * object allows for deterministic release of WebGL resources, instead of relying on the garbage
  281. * collector. Once this object is destroyed, it should not be used; calling any function other than
  282. * <code>isDestroyed</code> will result in a {@link DeveloperError} exception. Therefore,
  283. * assign the return value (<code>undefined</code>) to the object as done in the example.
  284. *
  285. * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
  286. *
  287. *
  288. * @example
  289. * dataSourceCollection = dataSourceCollection && dataSourceCollection.destroy();
  290. *
  291. * @see DataSourceCollection#isDestroyed
  292. */
  293. DataSourceCollection.prototype.destroy = function() {
  294. this.removeAll(true);
  295. return destroyObject(this);
  296. };
  297. export default DataSourceCollection;