openlayers/lib/OpenLayers/Layer/HTTPRequest.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
   2  * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
   3  * full text of the license. */
   4
   5
   6 /**
   7  * @requires OpenLayers/Layer.js
   8  */
   9
  10 /**
  11  * Class: OpenLayers.Layer.HTTPRequest
  12  *
  13  * Inherits from:
  14  *  - <OpenLayers.Layer>
  15  */
  16 OpenLayers.Layer.HTTPRequest = OpenLayers.Class(OpenLayers.Layer, {
  17
  18     /**
  19      * Constant: URL_HASH_FACTOR
  20      * {Float} Used to hash URL param strings for multi-WMS server selection.
  21      *         Set to the Golden Ratio per Knuth's recommendation.
  22      */
  23     URL_HASH_FACTOR: (Math.sqrt(5) - 1) / 2,
  24
  25     /**
  26      * Property: url
  27      * {Array(String) or String} This is either an array of url strings or
  28      *                           a single url string.
  29      */
  30     url: null,
  31
  32     /**
  33      * Property: params
  34      * {Object} Hashtable of key/value parameters
  35      */
  36     params: null,
  37
  38     /**
  39      * APIProperty: reproject
  40      * *Deprecated*. See http://trac.openlayers.org/wiki/SpatialMercator
  41      * for information on the replacement for this functionality.
  42      * {Boolean} Whether layer should reproject itself based on base layer
  43      *           locations. This allows reprojection onto commercial layers.
  44      *           Default is false: Most layers can't reproject, but layers
  45      *           which can create non-square geographic pixels can, like WMS.
  46      *
  47      */
  48     reproject: false,
  49
  50     /**
  51      * Constructor: OpenLayers.Layer.HTTPRequest
  52      *
  53      * Parameters:
  54      * name - {String}
  55      * url - {Array(String) or String}
  56      * params - {Object}
  57      * options - {Object} Hashtable of extra options to tag onto the layer
  58      */
  59     initialize: function(name, url, params, options) {
  60         var newArguments = arguments;
  61         newArguments = [name, options];
  62         OpenLayers.Layer.prototype.initialize.apply(this, newArguments);
  63         this.url = url;
  64         this.params = OpenLayers.Util.extend( {}, params);
  65     },
  66
  67     /**
  68      * APIMethod: destroy
  69      */
  70     destroy: function() {
  71         this.url = null;
  72         this.params = null;
  73         OpenLayers.Layer.prototype.destroy.apply(this, arguments);
  74     },
  75
  76     /**
  77      * APIMethod: clone
  78      *
  79      * Parameters:
  80      * obj - {Object}
  81      *
  82      * Returns:
  83      * {<OpenLayers.Layer.HTTPRequest>} An exact clone of this
  84      *                                  <OpenLayers.Layer.HTTPRequest>
  85      */
  86     clone: function (obj) {
  87
  88         if (obj == null) {
  89             obj = new OpenLayers.Layer.HTTPRequest(this.name,
  90                                                    this.url,
  91                                                    this.params,
  92                                                    this.options);
  93         }
  94
  95         //get all additions from superclasses
  96         obj = OpenLayers.Layer.prototype.clone.apply(this, [obj]);
  97
  98         // copy/set any non-init, non-simple values here
  99
 100         return obj;
 101     },
 102
 103     /**
 104      * APIMethod: setUrl
 105      *
 106      * Parameters:
 107      * newUrl - {String}
 108      */
 109     setUrl: function(newUrl) {
 110         this.url = newUrl;
 111     },
 112
 113     /**
 114      * APIMethod: mergeNewParams
 115      *
 116      * Parameters:
 117      * newParams - {Object}
 118      *
 119      * Returns:
 120      * redrawn: {Boolean} whether the layer was actually redrawn.
 121      */
 122     mergeNewParams:function(newParams) {
 123         this.params = OpenLayers.Util.extend(this.params, newParams);
 124         return this.redraw();
 125     },
 126
 127     /**
 128      * APIMethod: redraw
 129      * Redraws the layer.  Returns true if the layer was redrawn, false if not.
 130      *
 131      * Parameters:
 132      * force - {Boolean} Force redraw by adding random parameter.
 133      *
 134      * Returns:
 135      * {Boolean} The layer was redrawn.
 136      */
 137     redraw: function(force) {
 138         if (force) {
 139             return this.mergeNewParams({"_olSalt": Math.random()});
 140         } else {
 141             return OpenLayers.Layer.prototype.redraw.apply(this, []);
 142         }
 143     },
 144
 145     /**
 146      * Method: selectUrl
 147      * selectUrl() implements the standard floating-point multiplicative
 148      *     hash function described by Knuth, and hashes the contents of the
 149      *     given param string into a float between 0 and 1. This float is then
 150      *     scaled to the size of the provided urls array, and used to select
 151      *     a URL.
 152      *
 153      * Parameters:
 154      * paramString - {String}
 155      * urls - {Array(String)}
 156      *
 157      * Returns:
 158      * {String} An entry from the urls array, deterministically selected based
 159      *          on the paramString.
 160      */
 161     selectUrl: function(paramString, urls) {
 162         var product = 1;
 163         for (var i=0, len=paramString.length; i<len; i++) {
 164             product *= paramString.charCodeAt(i) * this.URL_HASH_FACTOR;
 165             product -= Math.floor(product);
 166         }
 167         return urls[Math.floor(product * urls.length)];
 168     },
 169
 170     /**
 171      * Method: getFullRequestString
 172      * Combine url with layer's params and these newParams.
 173      *
 174      *    does checking on the serverPath variable, allowing for cases when it
 175      *     is supplied with trailing ? or &, as well as cases where not.
 176      *
 177      *    return in formatted string like this:
 178      *        "server?key1=value1&key2=value2&key3=value3"
 179      *
 180      * WARNING: The altUrl parameter is deprecated and will be removed in 3.0.
 181      *
 182      * Parameters:
 183      * newParams - {Object}
 184      * altUrl - {String} Use this as the url instead of the layer's url
 185      *
 186      * Returns:
 187      * {String}
 188      */
 189     getFullRequestString:function(newParams, altUrl) {
 190
 191         // if not altUrl passed in, use layer's url
 192         var url = altUrl || this.url;
 193
 194         // create a new params hashtable with all the layer params and the
 195         // new params together. then convert to string
 196         var allParams = OpenLayers.Util.extend({}, this.params);
 197         allParams = OpenLayers.Util.extend(allParams, newParams);
 198         var paramsString = OpenLayers.Util.getParameterString(allParams);
 199
 200         // if url is not a string, it should be an array of strings,
 201         // in which case we will deterministically select one of them in
 202         // order to evenly distribute requests to different urls.
 203         //
 204         if (url instanceof Array) {
 205             url = this.selectUrl(paramsString, url);
 206         }
 207
 208         // ignore parameters that are already in the url search string
 209         var urlParams =
 210             OpenLayers.Util.upperCaseObject(OpenLayers.Util.getParameters(url));
 211         for(var key in allParams) {
 212             if(key.toUpperCase() in urlParams) {
 213                 delete allParams[key];
 214             }
 215         }
 216         paramsString = OpenLayers.Util.getParameterString(allParams);
 217
 218         // requestString always starts with url
 219         var requestString = url;
 220
 221         if (paramsString != "") {
 222             var lastServerChar = url.charAt(url.length - 1);
 223             if ((lastServerChar == "&") || (lastServerChar == "?")) {
 224                 requestString += paramsString;
 225             } else {
 226                 if (url.indexOf('?') == -1) {
 227                     //serverPath has no ? -- add one
 228                     requestString += '?' + paramsString;
 229                 } else {
 230                     //serverPath contains ?, so must already have
 231                     // paramsString at the end
 232                     requestString += '&' + paramsString;
 233                 }
 234             }
 235         }
 236         return requestString;
 237     },
 238
 239     CLASS_NAME: "OpenLayers.Layer.HTTPRequest"
 240 });