]> dev.renevier.net Git - syp.git/blob - openlayers/lib/OpenLayers/Layer/HTTPRequest.js
web interface to add co-administrators
[syp.git] / 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 });