Merge pull request #2138 from Aiosa/cache-key

Change Tile.cacheKey strategy

src/tile.js

@@ -52,10 +52,11 @@
  * @param {OpenSeadragon.Rect} sourceBounds The portion of the tile to use as the source of the
  *      drawing operation, in pixels. Note that this only works when drawing with canvas; when drawing
  *      with HTML the entire tile is always used.
- * @param {String} postData HTTP POST data  (usually but not necessarily in k=v&k2=v2... form,
+ * @param {String} postData HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
  *      see TileSrouce::getPostData) or null
+ * @param {String} cacheKey key to act as a tile cache, must be unique for tiles with unique image data
  */
-$.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, ajaxHeaders, sourceBounds, postData) {
+$.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, ajaxHeaders, sourceBounds, postData, cacheKey) {
     /**
      * The zoom level this tile belongs to.
      * @member {Number} level
@@ -100,8 +101,8 @@ $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, aja
      */
     this.url     = url;
     /**
-     * Post parameters for this tile. Either it is an URL-encoded string
-     * in k1=v1&k2=v2... format or null
+     * Post parameters for this tile. For example, it can be an URL-encoded string
+     * in k1=v1&k2=v2... format, or a JSON, or a FormData instance... or null if no POST request used
      * @member {String} postData HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
      *      see TileSrouce::getPostData) or null
      * @memberof OpenSeadragon.Tile#
@@ -131,11 +132,13 @@ $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, aja
      * @member {String} cacheKey
      * @memberof OpenSeadragon.Tile#
      */
-    if (this.ajaxHeaders) {
-        this.cacheKey = this.url + "+" + JSON.stringify(this.ajaxHeaders);
-    } else {
-        this.cacheKey = this.url;
+    if (cacheKey === undefined) {
+        $.console.error("Tile constructor needs 'cacheKey' variable: creation tile cache" +
+            " in Tile class is deprecated. TileSource.prototype.getTileHashKey will be used.");
+        cacheKey = $.TileSource.prototype.getTileHashKey(level, x, y, url, ajaxHeaders, postData);
     }
+    this.cacheKey = cacheKey;
+
     /**
      * Is this tile loaded?
      * @member {Boolean} loaded

src/tiledimage.js

@@ -1530,7 +1530,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
                 this.loadTilesWithAjax,
                 ajaxHeaders,
                 sourceBounds,
-                post
+                post,
+                tileSource.getTileHashKey(level, xMod, yMod, url, ajaxHeaders, post)
             );
 
             if (this.getFlip()) {

src/tilesource.js

@@ -639,10 +639,14 @@ $.TileSource.prototype = {
      *   let result = new FormData();
      *   result.append("data", myData);
      *   return result;
-
-     * @param level
-     * @param x
-     * @param y
+     *
+     * IMPORTANT: in case you move all the logic on image fetching
+     * to post data, you must re-define 'getTileHashKey(...)' to
+     * stay unique for different tile images.
+     *
+     * @param {Number} level
+     * @param {Number} x
+     * @param {Number} y
      * @return {* || null} post data to send with tile configuration request
      */
     getTilePostData: function( level, x, y ) {
@@ -666,6 +670,29 @@ $.TileSource.prototype = {
         return {};
     },
 
+    /**
+     * The tile cache object is uniquely determined by this key and used to lookup
+     * the image data in cache: keys should be different if images are different.
+     *
+     * In case a tile has context2D property defined (TileSource.prototype.getContext2D)
+     * or its context2D is set manually; the cache is not used and this function
+     * is irrelevant.
+     * Note: default behaviour does not take into account post data.
+     * @param {Number} level tile level it was fetched with
+     * @param {Number} x x-coordinate in the pyramid level
+     * @param {Number} y y-coordinate in the pyramid level
+     * @param {String} url the tile was fetched with
+     * @param {Object} ajaxHeaders the tile was fetched with
+     * @param {*} postData data the tile was fetched with (type depends on getTilePostData(..) return type)
+     */
+    getTileHashKey: function(level, x, y, url, ajaxHeaders, postData) {
+        if (ajaxHeaders) {
+            return url + "+" + JSON.stringify(ajaxHeaders);
+        } else {
+            return url;
+        }
+    },
+
     /**
      * @function
      * @param {Number} level