@cesium/engine 2.1.0 → 2.3.0

package/Source/Core/Resource.js

@@ -36,184 +36,6 @@ const xhrBlobSupported = (function () {
   }
 })();
 
-/**
- * Parses a query string and returns the object equivalent.
- *
- * @param {Uri} uri The Uri with a query object.
- * @param {Resource} resource The Resource that will be assigned queryParameters.
- * @param {boolean} merge If true, we'll merge with the resource's existing queryParameters. Otherwise they will be replaced.
- * @param {boolean} preserveQueryParameters If true duplicate parameters will be concatenated into an array. If false, keys in uri will take precedence.
- *
- * @private
- */
-function parseQuery(uri, resource, merge, preserveQueryParameters) {
-  const queryString = uri.query();
-  if (queryString.length === 0) {
-    return {};
-  }
-
-  let query;
-  // Special case we run into where the querystring is just a string, not key/value pairs
-  if (queryString.indexOf("=") === -1) {
-    const result = {};
-    result[queryString] = undefined;
-    query = result;
-  } else {
-    query = queryToObject(queryString);
-  }
-
-  if (merge) {
-    resource._queryParameters = combineQueryParameters(
-      query,
-      resource._queryParameters,
-      preserveQueryParameters
-    );
-  } else {
-    resource._queryParameters = query;
-  }
-  uri.search("");
-}
-
-/**
- * Converts a query object into a string.
- *
- * @param {Uri} uri The Uri object that will have the query object set.
- * @param {Resource} resource The resource that has queryParameters
- *
- * @private
- */
-function stringifyQuery(uri, resource) {
-  const queryObject = resource._queryParameters;
-
-  const keys = Object.keys(queryObject);
-
-  // We have 1 key with an undefined value, so this is just a string, not key/value pairs
-  if (keys.length === 1 && !defined(queryObject[keys[0]])) {
-    uri.search(keys[0]);
-  } else {
-    uri.search(objectToQuery(queryObject));
-  }
-}
-
-/**
- * Clones a value if it is defined, otherwise returns the default value
- *
- * @param {*} [val] The value to clone.
- * @param {*} [defaultVal] The default value.
- *
- * @returns {*} A clone of val or the defaultVal.
- *
- * @private
- */
-function defaultClone(val, defaultVal) {
-  if (!defined(val)) {
-    return defaultVal;
-  }
-
-  return defined(val.clone) ? val.clone() : clone(val);
-}
-
-/**
- * Checks to make sure the Resource isn't already being requested.
- *
- * @param {Request} request The request to check.
- *
- * @private
- */
-function checkAndResetRequest(request) {
-  if (
-    request.state === RequestState.ISSUED ||
-    request.state === RequestState.ACTIVE
-  ) {
-    throw new RuntimeError("The Resource is already being fetched.");
-  }
-
-  request.state = RequestState.UNISSUED;
-  request.deferred = undefined;
-}
-
-/**
- * This combines a map of query parameters.
- *
- * @param {object} q1 The first map of query parameters. Values in this map will take precedence if preserveQueryParameters is false.
- * @param {object} q2 The second map of query parameters.
- * @param {boolean} preserveQueryParameters If true duplicate parameters will be concatenated into an array. If false, keys in q1 will take precedence.
- *
- * @returns {object} The combined map of query parameters.
- *
- * @example
- * const q1 = {
- *   a: 1,
- *   b: 2
- * };
- * const q2 = {
- *   a: 3,
- *   c: 4
- * };
- * const q3 = {
- *   b: [5, 6],
- *   d: 7
- * }
- *
- * // Returns
- * // {
- * //   a: [1, 3],
- * //   b: 2,
- * //   c: 4
- * // };
- * combineQueryParameters(q1, q2, true);
- *
- * // Returns
- * // {
- * //   a: 1,
- * //   b: 2,
- * //   c: 4
- * // };
- * combineQueryParameters(q1, q2, false);
- *
- * // Returns
- * // {
- * //   a: 1,
- * //   b: [2, 5, 6],
- * //   d: 7
- * // };
- * combineQueryParameters(q1, q3, true);
- *
- * // Returns
- * // {
- * //   a: 1,
- * //   b: 2,
- * //   d: 7
- * // };
- * combineQueryParameters(q1, q3, false);
- *
- * @private
- */
-function combineQueryParameters(q1, q2, preserveQueryParameters) {
-  if (!preserveQueryParameters) {
-    return combine(q1, q2);
-  }
-
-  const result = clone(q1, true);
-  for (const param in q2) {
-    if (q2.hasOwnProperty(param)) {
-      let value = result[param];
-      const q2Value = q2[param];
-      if (defined(value)) {
-        if (!Array.isArray(value)) {
-          value = result[param] = [value];
-        }
-
-        result[param] = value.concat(q2Value);
-      } else {
-        result[param] = Array.isArray(q2Value) ? q2Value.slice() : q2Value;
-      }
-    }
-  }
-
-  return result;
-}
-
 /**
  * @typedef {object} Resource.ConstructorOptions
  *
@@ -227,6 +49,7 @@ function combineQueryParameters(q1, q2, preserveQueryParameters) {
  * @property {Resource.RetryCallback} [retryCallback] The Function to call when a request for this resource fails. If it returns true, the request will be retried.
  * @property {number} [retryAttempts=0] The number of times the retryCallback should be called before giving up.
  * @property {Request} [request] A Request object that will be used. Intended for internal use only.
+ * @property {boolean} [parseUrl=true] If true, parse the url for query parameters; otherwise store the url without change
  */
 
 /**
@@ -319,13 +142,26 @@ function Resource(options) {
   this.retryAttempts = defaultValue(options.retryAttempts, 0);
   this._retryCount = 0;
 
-  const uri = new Uri(options.url);
-  parseQuery(uri, this, true, true);
-
-  // Remove the fragment as it's not sent with a request
-  uri.fragment("");
+  const parseUrl = defaultValue(options.parseUrl, true);
+  if (parseUrl) {
+    this.parseUrl(options.url, true, true);
+  } else {
+    this._url = options.url;
+  }
+}
 
-  this._url = uri.toString();
+/**
+ * Clones a value if it is defined, otherwise returns the default value
+ *
+ * @param {object} [value] The value to clone.
+ * @param {object} [defaultValue] The default value.
+ *
+ * @returns {object} A clone of value or the defaultValue.
+ *
+ * @private
+ */
+function defaultClone(value, defaultValue) {
+  return defined(value) ? clone(value) : defaultValue;
 }
 
 /**
@@ -471,14 +307,7 @@ Object.defineProperties(Resource.prototype, {
       return this.getUrlComponent(true, true);
     },
     set: function (value) {
-      const uri = new Uri(value);
-
-      parseQuery(uri, this, false);
-
-      // Remove the fragment as it's not sent with a request
-      uri.fragment("");
-
-      this._url = uri.toString();
+      this.parseUrl(value, false, false);
     },
   },
 
@@ -555,6 +384,138 @@ Resource.prototype.toString = function () {
   return this.getUrlComponent(true, true);
 };
 
+/**
+ * Parse a url string, and store its info
+ *
+ * @param {string} url The input url string.
+ * @param {boolean} merge If true, we'll merge with the resource's existing queryParameters. Otherwise they will be replaced.
+ * @param {boolean} preserveQuery If true duplicate parameters will be concatenated into an array. If false, keys in url will take precedence.
+ * @param {string} [baseUrl] If supplied, and input url is a relative url, it will be made absolute relative to baseUrl
+ *
+ * @private
+ */
+Resource.prototype.parseUrl = function (url, merge, preserveQuery, baseUrl) {
+  let uri = new Uri(url);
+  const query = parseQueryString(uri.query());
+
+  this._queryParameters = merge
+    ? combineQueryParameters(query, this.queryParameters, preserveQuery)
+    : query;
+
+  // Remove unneeded info from the Uri
+  uri.search("");
+  uri.fragment("");
+
+  if (defined(baseUrl) && uri.scheme() === "") {
+    uri = uri.absoluteTo(getAbsoluteUri(baseUrl));
+  }
+
+  this._url = uri.toString();
+};
+
+/**
+ * Parses a query string and returns the object equivalent.
+ *
+ * @param {string} queryString The query string
+ * @returns {object}
+ *
+ * @private
+ */
+function parseQueryString(queryString) {
+  if (queryString.length === 0) {
+    return {};
+  }
+
+  // Special case where the querystring is just a string, not key/value pairs
+  if (queryString.indexOf("=") === -1) {
+    return { [queryString]: undefined };
+  }
+
+  return queryToObject(queryString);
+}
+
+/**
+ * This combines a map of query parameters.
+ *
+ * @param {object} q1 The first map of query parameters. Values in this map will take precedence if preserveQueryParameters is false.
+ * @param {object} q2 The second map of query parameters.
+ * @param {boolean} preserveQueryParameters If true duplicate parameters will be concatenated into an array. If false, keys in q1 will take precedence.
+ *
+ * @returns {object} The combined map of query parameters.
+ *
+ * @example
+ * const q1 = {
+ *   a: 1,
+ *   b: 2
+ * };
+ * const q2 = {
+ *   a: 3,
+ *   c: 4
+ * };
+ * const q3 = {
+ *   b: [5, 6],
+ *   d: 7
+ * }
+ *
+ * // Returns
+ * // {
+ * //   a: [1, 3],
+ * //   b: 2,
+ * //   c: 4
+ * // };
+ * combineQueryParameters(q1, q2, true);
+ *
+ * // Returns
+ * // {
+ * //   a: 1,
+ * //   b: 2,
+ * //   c: 4
+ * // };
+ * combineQueryParameters(q1, q2, false);
+ *
+ * // Returns
+ * // {
+ * //   a: 1,
+ * //   b: [2, 5, 6],
+ * //   d: 7
+ * // };
+ * combineQueryParameters(q1, q3, true);
+ *
+ * // Returns
+ * // {
+ * //   a: 1,
+ * //   b: 2,
+ * //   d: 7
+ * // };
+ * combineQueryParameters(q1, q3, false);
+ *
+ * @private
+ */
+function combineQueryParameters(q1, q2, preserveQueryParameters) {
+  if (!preserveQueryParameters) {
+    return combine(q1, q2);
+  }
+
+  const result = clone(q1, true);
+  for (const param in q2) {
+    if (q2.hasOwnProperty(param)) {
+      let value = result[param];
+      const q2Value = q2[param];
+      if (defined(value)) {
+        if (!Array.isArray(value)) {
+          value = result[param] = [value];
+        }
+
+        result[param] = value.concat(q2Value);
+      } else {
+        result[param] = Array.isArray(q2Value) ? q2Value.slice() : q2Value;
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Returns the url, optional with the query string and processed by a proxy.
  *
@@ -568,32 +529,56 @@ Resource.prototype.getUrlComponent = function (query, proxy) {
     return this._url;
   }
 
-  const uri = new Uri(this._url);
-
+  let url = this._url;
   if (query) {
-    stringifyQuery(uri, this);
+    url = `${url}${stringifyQuery(this.queryParameters)}`;
   }
 
-  // objectToQuery escapes the placeholders.  Undo that.
-  let url = uri.toString().replace(/%7B/g, "{").replace(/%7D/g, "}");
+  // Restore the placeholders, which may have been escaped in objectToQuery or elsewhere
+  url = url.replace(/%7B/g, "{").replace(/%7D/g, "}");
 
   const templateValues = this._templateValues;
-  url = url.replace(/{(.*?)}/g, function (match, key) {
-    const replacement = templateValues[key];
-    if (defined(replacement)) {
-      // use the replacement value from templateValues if there is one...
-      return encodeURIComponent(replacement);
-    }
-    // otherwise leave it unchanged
-    return match;
-  });
+  if (Object.keys(templateValues).length > 0) {
+    url = url.replace(/{(.*?)}/g, function (match, key) {
+      const replacement = templateValues[key];
+      if (defined(replacement)) {
+        // use the replacement value from templateValues if there is one...
+        return encodeURIComponent(replacement);
+      }
+      // otherwise leave it unchanged
+      return match;
+    });
+  }
 
   if (proxy && defined(this.proxy)) {
     url = this.proxy.getURL(url);
   }
+
   return url;
 };
 
+/**
+ * Converts a query object into a string.
+ *
+ * @param {object} queryObject The object with query parameters
+ * @returns {string}
+ *
+ * @private
+ */
+function stringifyQuery(queryObject) {
+  const keys = Object.keys(queryObject);
+
+  if (keys.length === 0) {
+    return "";
+  }
+  if (keys.length === 1 && !defined(queryObject[keys[0]])) {
+    // We have 1 key with an undefined value, so this is just a string, not key/value pairs
+    return `?${keys[0]}`;
+  }
+
+  return `?${objectToQuery(queryObject)}`;
+}
+
 /**
  * Combines the specified object and the existing query parameters. This allows you to add many parameters at once,
  *  as opposed to adding them one at a time to the queryParameters property. If a value is already set, it will be replaced with the new value.
@@ -667,30 +652,14 @@ Resource.prototype.getDerivedResource = function (options) {
   resource._retryCount = 0;
 
   if (defined(options.url)) {
-    const uri = new Uri(options.url);
-
-    const preserveQueryParameters = defaultValue(
-      options.preserveQueryParameters,
-      false
-    );
-    parseQuery(uri, resource, true, preserveQueryParameters);
-
-    // Remove the fragment as it's not sent with a request
-    uri.fragment("");
-
-    if (uri.scheme() !== "") {
-      resource._url = uri.toString();
-    } else {
-      resource._url = uri
-        .absoluteTo(new Uri(getAbsoluteUri(this._url)))
-        .toString();
-    }
+    const preserveQuery = defaultValue(options.preserveQueryParameters, false);
+    resource.parseUrl(options.url, true, preserveQuery, this._url);
   }
 
   if (defined(options.queryParameters)) {
     resource._queryParameters = combine(
       options.queryParameters,
-      resource._queryParameters
+      resource.queryParameters
     );
   }
   if (defined(options.templateValues)) {
@@ -721,7 +690,7 @@ Resource.prototype.getDerivedResource = function (options) {
 /**
  * Called when a resource fails to load. This will call the retryCallback function if defined until retryAttempts is reached.
  *
- * @param {Error} [error] The error that was encountered.
+ * @param {RequestErrorEvent} [error] The error that was encountered.
  *
  * @returns {Promise<boolean>} A promise to a boolean, that if true will cause the resource request to be retried.
  *
@@ -753,8 +722,16 @@ Resource.prototype.retryOnError = function (error) {
  */
 Resource.prototype.clone = function (result) {
   if (!defined(result)) {
-    result = new Resource({
+    return new Resource({
       url: this._url,
+      queryParameters: this.queryParameters,
+      templateValues: this.templateValues,
+      headers: this.headers,
+      proxy: this.proxy,
+      retryCallback: this.retryCallback,
+      retryAttempts: this.retryAttempts,
+      request: this.request.clone(),
+      parseUrl: false,
     });
   }
 
@@ -1301,7 +1278,8 @@ function fetchJsonp(resource, callbackParameterName, functionName) {
   resource.setQueryParameters(callbackQuery);
 
   const request = resource.request;
-  request.url = resource.url;
+  const url = resource.url;
+  request.url = url;
   request.requestFunction = function () {
     const deferred = defer();
 
@@ -1316,11 +1294,7 @@ function fetchJsonp(resource, callbackParameterName, functionName) {
       }
     };
 
-    Resource._Implementations.loadAndExecuteScript(
-      resource.url,
-      functionName,
-      deferred
-    );
+    Resource._Implementations.loadAndExecuteScript(url, functionName, deferred);
     return deferred.promise;
   };
 
@@ -1376,7 +1350,8 @@ Resource.prototype._makeRequest = function (options) {
   checkAndResetRequest(resource.request);
 
   const request = resource.request;
-  request.url = resource.url;
+  const url = resource.url;
+  request.url = url;
 
   request.requestFunction = function () {
     const responseType = options.responseType;
@@ -1386,7 +1361,7 @@ Resource.prototype._makeRequest = function (options) {
     const data = options.data;
     const deferred = defer();
     const xhr = Resource._Implementations.loadWithXhr(
-      resource.url,
+      url,
       responseType,
       method,
       data,
@@ -1433,6 +1408,25 @@ Resource.prototype._makeRequest = function (options) {
     });
 };
 
+/**
+ * Checks to make sure the Resource isn't already being requested.
+ *
+ * @param {Request} request The request to check.
+ *
+ * @private
+ */
+function checkAndResetRequest(request) {
+  if (
+    request.state === RequestState.ISSUED ||
+    request.state === RequestState.ACTIVE
+  ) {
+    throw new RuntimeError("The Resource is already being fetched.");
+  }
+
+  request.state = RequestState.UNISSUED;
+  request.deferred = undefined;
+}
+
 const dataUriRegex = /^data:(.*?)(;base64)?,(.*)$/;
 
 function decodeDataUriText(isBase64, data) {
@@ -2301,7 +2295,7 @@ Resource.DEFAULT = Object.freeze(
  * @callback Resource.RetryCallback
  *
  * @param {Resource} [resource] The resource that failed to load.
- * @param {Error} [error] The error that occurred during the loading of the resource.
+ * @param {RequestErrorEvent} [error] The error that occurred during the loading of the resource.
  * @returns {boolean|Promise<boolean>} If true or a promise that resolved to true, the resource will be retried. Otherwise the failure will be returned.
  */
 export default Resource;

package/Source/Core/TerrainProvider.js

@@ -22,7 +22,7 @@ function TerrainProvider() {
 
 Object.defineProperties(TerrainProvider.prototype, {
   /**
-   * Gets an event that is raised when the terrain provider encounters an asynchronous error..  By subscribing
+   * Gets an event that is raised when the terrain provider encounters an asynchronous error.  By subscribing
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
    * are passed an instance of {@link TileProviderError}.
    * @memberof TerrainProvider.prototype
@@ -35,8 +35,7 @@ Object.defineProperties(TerrainProvider.prototype, {
 
   /**
    * Gets the credit to display when this terrain provider is active.  Typically this is used to credit
-   * the source of the terrain. This function should
-   * not be called before {@link TerrainProvider#ready} returns true.
+   * the source of the terrain.
    * @memberof TerrainProvider.prototype
    * @type {Credit}
    * @readonly
@@ -46,8 +45,7 @@ Object.defineProperties(TerrainProvider.prototype, {
   },
 
   /**
-   * Gets the tiling scheme used by the provider.  This function should
-   * not be called before {@link TerrainProvider#ready} returns true.
+   * Gets the tiling scheme used by the provider.
    * @memberof TerrainProvider.prototype
    * @type {TilingScheme}
    * @readonly
@@ -61,6 +59,7 @@ Object.defineProperties(TerrainProvider.prototype, {
    * @memberof TerrainProvider.prototype
    * @type {boolean}
    * @readonly
+   * @deprecated
    */
   ready: {
     get: DeveloperError.throwInstantiationError,
@@ -71,6 +70,7 @@ Object.defineProperties(TerrainProvider.prototype, {
    * @memberof TerrainProvider.prototype
    * @type {Promise<boolean>}
    * @readonly
+   * @deprecated
    */
   readyPromise: {
     get: DeveloperError.throwInstantiationError,
@@ -79,8 +79,7 @@ Object.defineProperties(TerrainProvider.prototype, {
   /**
    * Gets a value indicating whether or not the provider includes a water mask.  The water mask
    * indicates which areas of the globe are water rather than land, so they can be rendered
-   * as a reflective surface with animated waves.  This function should not be
-   * called before {@link TerrainProvider#ready} returns true.
+   * as a reflective surface with animated waves.
    * @memberof TerrainProvider.prototype
    * @type {boolean}
    * @readonly
@@ -91,7 +90,6 @@ Object.defineProperties(TerrainProvider.prototype, {
 
   /**
    * Gets a value indicating whether or not the requested tiles include vertex normals.
-   * This function should not be called before {@link TerrainProvider#ready} returns true.
    * @memberof TerrainProvider.prototype
    * @type {boolean}
    * @readonly
@@ -102,8 +100,7 @@ Object.defineProperties(TerrainProvider.prototype, {
 
   /**
    * Gets an object that can be used to determine availability of terrain from this provider, such as
-   * at points and in rectangles.  This function should not be called before
-   * {@link TerrainProvider#ready} returns true.  This property may be undefined if availability
+   * at points and in rectangles. This property may be undefined if availability
    * information is not available.
    * @memberof TerrainProvider.prototype
    * @type {TileAvailability}
@@ -399,8 +396,7 @@ TerrainProvider.getEstimatedLevelZeroGeometricErrorForAHeightmap = function (
 };
 
 /**
- * Requests the geometry for a given tile.  This function should not be called before
- * {@link TerrainProvider#ready} returns true.  The result must include terrain data and
+ * Requests the geometry for a given tile. The result must include terrain data and
  * may optionally include a water mask and an indication of which child tiles are available.
  * @function
  *
@@ -417,8 +413,7 @@ TerrainProvider.prototype.requestTileGeometry =
   DeveloperError.throwInstantiationError;
 
 /**
- * Gets the maximum geometric error allowed in a tile at a given level.  This function should not be
- * called before {@link TerrainProvider#ready} returns true.
+ * Gets the maximum geometric error allowed in a tile at a given level.
  * @function
  *
  * @param {number} level The tile level for which to get the maximum geometric error.

package/Source/Core/TileProviderError.js

@@ -92,14 +92,14 @@ function TileProviderError(
  * @param {TileProviderError} previousError The error instance returned by this function the last
  *        time it was called for this error, or undefined if this is the first time this error has
  *        occurred.
- * @param {ImageryProvider|TerrainProvider} provider The imagery or terrain provider that encountered the error.
- * @param {Event} event The event to raise to inform listeners of the error.
- * @param {string} message The message describing the error.
- * @param {number} x The X coordinate of the tile that experienced the error, or undefined if the
+ * @param {ImageryProvider|TerrainProvider} [provider] The imagery or terrain provider that encountered the error.
+ * @param {Event} [event] The event to raise to inform listeners of the error.
+ * @param {string} [message] The message describing the error.
+ * @param {number} [x] The X coordinate of the tile that experienced the error, or undefined if the
  *        error is not specific to a particular tile.
- * @param {number} y The Y coordinate of the tile that experienced the error, or undefined if the
+ * @param {number} [y] The Y coordinate of the tile that experienced the error, or undefined if the
  *        error is not specific to a particular tile.
- * @param {number} level The level-of-detail of the tile that experienced the error, or undefined if the
+ * @param {number} [level] The level-of-detail of the tile that experienced the error, or undefined if the
  *        error is not specific to a particular tile.
  * @param {Error} [errorDetails] The error or exception that occurred, if any.
  * @returns {TileProviderError} The error instance that was passed to the event listeners and that
@@ -138,9 +138,9 @@ TileProviderError.reportError = function (
     ++error.timesRetried;
   }
 
-  if (event.numberOfListeners > 0) {
+  if (defined(event) && event.numberOfListeners > 0) {
     event.raiseEvent(error);
-  } else {
+  } else if (defined(provider)) {
     console.log(
       `An error occurred in "${provider.constructor.name}": ${formatError(
         message