001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js.user;
021 
022 import js.*;
023 import js.core.*;
024 
025 /**
026  * <p>An <b>opaque</b> class representing JavaScript client-side objects of the global 
027  * {@link JsClient#Location} class.</p>
028  * {@link JsWindow#location} property of the {@link JsWindow} object refers to a 
029  * {@link JsLocation} object that represents the web address (the "location") of the 
030  * document currently displayed in that window. The {@link #href} property contains the 
031  * complete URL of that document, and the other properties of the {@link JsLocation} 
032  * object each describe a portion of that URL. These properties are much like the URL 
033  * properties of the {@link JsHTMLLinkElement} object. When a {@link JsLocation} object 
034  * is converted to a string, the value of the {@link #href} property is returned.</p>
035  * <p>While the {@link JsHTMLLinkElement} object represents a hyperlink in a document, 
036  * the {@link JsLocation} object represents the URL, or location, currently displayed 
037  * by the browser. However, the {@link JsLocation} object does more than that: it also 
038  * controls the location displayed by the browser. If you assign a string containing a 
039  * URL to the {@link JsLocation} object or to its {@link #href} property, the web browser 
040  * responds by loading the newly specified URL and displaying the document it refers to.</p>
041  * <p>Instead of setting {@link #href} to replace the current URL with a completely new 
042  * one, you can modify just a portion of the current URL by assigning strings to the 
043  * other properties of the {@link JsLocation} object. This creates a new URL with one 
044  * new portion, which the browser loads and displays. For example, if you set the {@link #hash} 
045  * property of the {@link JsLocation} object, you can cause the browser to move to a 
046  * named location within the current document. Similarly, if you set the {@link #search} 
047  * property, you can cause the browser to reload the current URL with a new query string 
048  * appended.</p>
049  * <p>In addition to its URL properties, the {@link JsLocation} object also defines two 
050  * methods. The {@link #reload()} method reloads the current document. The {@link #replace(Object)} 
051  * method loads a new document without creating a new history entry for it; the new 
052  * document replaces the current one in the browser's history list.</p>
053  *
054  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
055  * @see JsHTMLLinkElement
056  * @see JsHTMLDocument#URL
057  *
058  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be
059  * generated into the target codes. Re-compilers must exit with error on the operations of
060  * accessing that kind of class objects.
061  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored
062  * and <tt>instanceof</tt> to it always <tt>true</tt>.
063  */
064 public class JsLocation extends JsClient.Location.Prototype
065 {
066     /**
067      * <p>An <b>internal</b> class containing membership data for its enclosing
068      * opaque class.</p>
069      * <p>This class is only used inside of <b>opaque</b> or <b>internal</b> classes or
070      * class members.</p>
071      *
072      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
073      * 
074      * @javascript Re-compilers must report error on resolving an <b>internal</b> class.
075      */
076     protected static abstract class Members extends JsClient.Location.Prototype.Members
077     {
078         /**
079          * <p>An <b>internal</b> static field defining a member ID of the field name and
080          * used internally to define a member of the same name.</p>
081          * @since 1.0
082          * @see JsLocation#hash
083          * @see JsLocation.Member#hash
084          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
085          */
086         public final static Mid hash     = id("hash"    );
087         /**
088          * <p>An <b>internal</b> static field defining a member ID of the field name and
089          * used internally to define a member of the same name.</p>
090          * @since 1.0
091          * @see JsLocation#host
092          * @see JsLocation.Member#host
093          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
094          */
095         public final static Mid host     = id("host"    );
096         /**
097          * <p>An <b>internal</b> static field defining a member ID of the field name and
098          * used internally to define a member of the same name.</p>
099          * @since 1.0
100          * @see JsLocation#hostName
101          * @see JsLocation.Member#hostName
102          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
103          */
104         public final static Mid hostName = id("hostName");
105         /**
106          * <p>An <b>internal</b> static field defining a member ID of the field name and
107          * used internally to define a member of the same name.</p>
108          * @since 1.0
109          * @see JsLocation#href
110          * @see JsLocation.Member#href
111          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
112          */
113         public final static Mid href     = id("href"    );
114         /**
115          * <p>An <b>internal</b> static field defining a member ID of the field name and
116          * used internally to define a member of the same name.</p>
117          * @since 1.0
118          * @see JsLocation#pathname
119          * @see JsLocation.Member#pathname
120          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
121          */
122         public final static Mid pathname = id("pathname");
123         /**
124          * <p>An <b>internal</b> static field defining a member ID of the field name and
125          * used internally to define a member of the same name.</p>
126          * @since 1.0
127          * @see JsLocation#port
128          * @see JsLocation.Member#port
129          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
130          */
131         public final static Mid port     = id("port"    );
132         /**
133          * <p>An <b>internal</b> static field defining a member ID of the field name and
134          * used internally to define a member of the same name.</p>
135          * @since 1.0
136          * @see JsLocation#protocol
137          * @see JsLocation.Member#protocol
138          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
139          */
140         public final static Mid protocol = id("protocol");
141         /**
142          * <p>An <b>internal</b> static field defining a member ID of the field name and
143          * used internally to define a member of the same name.</p>
144          * @since 1.0
145          * @see JsLocation#search
146          * @see JsLocation.Member#search
147          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
148          */
149         public final static Mid search   = id("search"  );
150     }
151     /**
152      * <p>An <b>opaque</b> class representing members of its enclosing <b>opaque</b> type.</p>
153      * <p>Note that, this class is <b>opaque</b> but its constructors are all <b>internal</b>. 
154      * This class and the subclasses of this class are used to declare either <b>opaque</b> 
155      * <tt>public</tt> instance fields of the opaque type {@link js.Var.Member} or the 
156      * <b>opaque</b> <tt>public</tt> static fields of other <b>opaque</b> types while their 
157      * constructors are used to define the fields inside <b>opaque</b> classes. Under 
158      * either circumstance, the field names must be exactly same as the member names, as 
159      * the <b>opaque</b> fields of <b>opaque</b> types are resolved by re-compilers directly 
160      * based on the field names.</p>
161      *
162      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
163      * 
164      * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be created
165      * in the target codes. Re-compilers must exit with error on operations accessing that kind 
166      * of class objects.
167      * Re-compilers must resolve an <b>opaque</b> instance field declared by this class in
168      * {@link js.Var.Member} or its subclasses to the JavaScript identifier: 
169      * <pre>q.m</pre>
170      * where <tt>m</tt> is the identifier of the field name and <tt>q</tt> is the identifier
171      * resolved from the instance of the enclosing member. Re-compilers must resolve an 
172      * <b>opaque</b> static field declared by this class in <b>opaque</b> types other than 
173      * {@link js.Var.Member} and its subclasses to the JavaScript identifier: 
174      * <pre>m</pre>
175      * where <tt>m</tt> is the identifier of the field name. And re-compilers must report
176      * error on the access to <b>opaque</b> fields declared by this class under any other 
177      * circumstances.
178      */
179     public static class Member extends JsClient.Location.Prototype.Member
180     {
181         /**
182          * <p>Internally constructs a member based on a qualifying member.</p>
183          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
184          * or <b>internal</b> classes or class members.</p>
185          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
186          * <b>opaque</b>. This constructor is used to define <b>opaque</b> instance fields 
187          * declared in the declaring class of this constructor itself or its subclasses. 
188          * Under this circumstance, the field names must be exactly same as the member 
189          * names, as the <b>opaque</b> instance fields of the <b>opaque</b> type 
190          * {@link js.Var.Member} or its subclasses are resolved by re-compilers directly
191          * to their names appending to the name resolved from the specified qualifying 
192          * member with a dot in between.</p>
193          * @param q A qualifying member
194          * @param mid The ID of the member to construct
195          * @since 1.0
196          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
197          */
198         public Member(JsObject.Member q, Mid mid) {
199             super(q, mid);
200         }
201         /**
202          * <p>Internally constructs a member without a qualifying member.</p>
203          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
204          * or <b>internal</b> classes or class members.</p>
205          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
206          * <b>opaque</b>. This constructor is used to define <b>opaque</b> static fields, 
207          * declared in <b>opaque</b> types other than the declaring class of this constructor 
208          * itself and its subclasses. Under this circumstance, the field names must be
209          * exactly same as the member names, as the <b>opaque</b> static fields of <b>opaque</b>
210          * types are generally resolved by re-compilers directly to identifiers of their names.</p>
211          * @param mid The ID of the member to construct
212          * @since 1.0
213          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
214          */
215         public Member(Mid mid) {
216             super(mid);
217         }
218         @Override
219         /**
220          * <p>Evaluates the property, represented by the current member instance, of the
221          * argument object.</p>
222          * @param o The argument object
223          * @return The value of the current member based on the object argument.
224          * @since 1.0
225          * @javascript Re-compilers must convert the instance invocation of this method into
226          * the JavaScript expression: 
227          * <pre>o.m</pre>
228          * where <tt>m</tt> is the identifier name resolved from the current member
229          * instance of the invocation.
230          */
231         public JsLocation with(ObjectLike o) {
232             return new JsLocation(super.with(o));
233         }
234         /**
235          * <p>Evaluates a property, represented by the current member instance, of the
236          * JavaScript global object, that is, evaluates the member to a global identifier.</p>
237          * @return The value of the current member based on the JavaScript global object.
238          * @since 1.0
239          * @javascript Re-compilers must convert the instance invocation of this method into
240          * the JavaScript expression: 
241          * <pre>m</pre>
242          * where <tt>m</tt> is the identifier name resolved from the current member
243          * instance of the invocation.
244          */
245         public JsLocation with() {
246             return with(Js.win());
247         }
248         /**
249          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
250          * name of this field, qualified by the current member instance of the field, and 
251          * to access the property of the name on an object.</p>
252          * <p>The property, identified by this member, of a {@link JsLocation} object 
253          * refers to a read/write string that specifies the anchor portion of the URL, 
254          * including the leading hash (#) mark. This portion of the document URL 
255          * specifies the name of an anchor within the document.</p> 
256          * @since 1.0
257          * @javascript Re-compilers must resolve the member of this instance field to the
258          * identifier of the field name appending to the identifier resolved from its 
259          * qualifying member with a dot in between.
260          */
261         public final Value.String.Member hash     = new Value.String.Member(this, Members.hash    );
262         /**
263          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
264          * name of this field, qualified by the current member instance of the field, and 
265          * to access the property of the name on an object.</p>
266          * <p>The property, identified by this member, of a {@link JsLocation} object 
267          * refers to a read/write string that specifies the hostname and port portions 
268          * of the URL.</p> 
269          * @since 1.0
270          * @javascript Re-compilers must resolve the member of this instance field to the
271          * identifier of the field name appending to the identifier resolved from its 
272          * qualifying member with a dot in between.
273          */
274         public final Value.String.Member host     = new Value.String.Member(this, Members.host    );
275         /**
276          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
277          * name of this field, qualified by the current member instance of the field, and 
278          * to access the property of the name on an object.</p>
279          * <p>The property, identified by this member, of a {@link JsLocation} object 
280          * refers to a read/write string that specifies the hostname portion of the URL.</p> 
281          * @since 1.0
282          * @javascript Re-compilers must resolve the member of this instance field to the
283          * identifier of the field name appending to the identifier resolved from its 
284          * qualifying member with a dot in between.
285          */
286         public final Value.String.Member hostName = new Value.String.Member(this, Members.hostName);
287         /**
288          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
289          * name of this field, qualified by the current member instance of the field, and 
290          * to access the property of the name on an object.</p>
291          * <p>The property, identified by this member, of a {@link JsLocation} object 
292          * refers to a read/write string that specifies the complete text of the 
293          * document's URL, unlike other {@link JsLocation} properties that specify only 
294          * portions of the URL. Setting this property to a new URL causes the browser 
295          * to read and display the contents of the new URL.</p> 
296          * @since 1.0
297          * @javascript Re-compilers must resolve the member of this instance field to the
298          * identifier of the field name appending to the identifier resolved from its 
299          * qualifying member with a dot in between.
300          */
301         public final Value.String.Member href     = new Value.String.Member(this, Members.href    );
302         /**
303          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
304          * name of this field, qualified by the current member instance of the field, and 
305          * to access the property of the name on an object.</p>
306          * <p>The property, identified by this member, of a {@link JsLocation} object 
307          * refers to a read/write string that specifies .</p> 
308          * @since 1.0
309          * @javascript Re-compilers must resolve the member of this instance field to the
310          * identifier of the field name appending to the identifier resolved from its 
311          * qualifying member with a dot in between.
312          */
313         public final Value.String.Member pathname = new Value.String.Member(this, Members.pathname);
314         /**
315          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
316          * name of this field, qualified by the current member instance of the field, and 
317          * to access the property of the name on an object.</p>
318          * <p>The property, identified by this member, of a {@link JsLocation} object 
319          * refers to a read/write string that specifies the port portion of the URL.</p> 
320          * @since 1.0
321          * @javascript Re-compilers must resolve the member of this instance field to the
322          * identifier of the field name appending to the identifier resolved from its 
323          * qualifying member with a dot in between.
324          */
325         public final Value.String.Member port     = new Value.String.Member(this, Members.port    );
326         /**
327          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
328          * name of this field, qualified by the current member instance of the field, and 
329          * to access the property of the name on an object.</p>
330          * <p>The property, identified by this member, of a {@link JsLocation} object 
331          * refers to a read/write string that specifies the protocol portion of a URL, 
332          * including the trailing colon.</p> 
333          * @since 1.0
334          * @javascript Re-compilers must resolve the member of this instance field to the
335          * identifier of the field name appending to the identifier resolved from its 
336          * qualifying member with a dot in between.
337          */
338         public final Value.String.Member protocol = new Value.String.Member(this, Members.protocol);
339         /**
340          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
341          * name of this field, qualified by the current member instance of the field, and 
342          * to access the property of the name on an object.</p>
343          * <p>The property, identified by this member, of a {@link JsLocation} object 
344          * refers to a read/write string that specifies the query portion of a URL, 
345          * including the leading question mark.</p> 
346          * @since 1.0
347          * @javascript Re-compilers must resolve the member of this instance field to the
348          * identifier of the field name appending to the identifier resolved from its 
349          * qualifying member with a dot in between.
350          */
351         public final Value.String.Member search   = new Value.String.Member(this, Members.search  );
352     }
353 
354     /**
355      * <p>Casts an <b>opaque</b> object to the current <b>opaque</b> type by wrapping it
356      * with the wrapping constructor.</p>
357      * @param var The argument of an <b>opaque</b> object.
358      * @since 1.0
359      * @javascript Re-compilers must ignore the construction operation of this constructor,
360      * that is, replacing it with its only argument.
361      */
362     public JsLocation(JsObject var) {
363         super(var);
364     }
365     /**
366      * <p>An <b>opaque</b> static field defining a member that is named by the field name
367      * without a qualifying member and to access the property of the name on an object.</p>
368      * <p>The property, identified by this member, of a {@link JsLocation} object 
369      * refers to a read/write string that specifies the anchor portion of the URL, 
370      * including the leading hash (#) mark. This portion of the document URL 
371      * specifies the name of an anchor within the document.</p> 
372      * @since 1.0
373      * @javascript Re-compilers must resolve the member of this static field to the
374      * identifier of the field name.
375      */
376     public static final Value.String.Member hash     = new Value.String.Member(Members.hash    );
377     /**
378      * <p>An <b>opaque</b> static field defining a member that is named by the field name
379      * without a qualifying member and to access the property of the name on an object.</p>
380      * <p>The property, identified by this member, of a {@link JsLocation} object 
381      * refers to a read/write string that specifies the hostname and port portions 
382      * of the URL.</p> 
383      * @since 1.0
384      * @javascript Re-compilers must resolve the member of this static field to the
385      * identifier of the field name.
386      */
387     public static final Value.String.Member host     = new Value.String.Member(Members.host    );
388     /**
389      * <p>An <b>opaque</b> static field defining a member that is named by the field name
390      * without a qualifying member and to access the property of the name on an object.</p>
391      * <p>The property, identified by this member, of a {@link JsLocation} object 
392      * refers to a read/write string that specifies the hostname portion of the URL.</p> 
393      * @since 1.0
394      * @javascript Re-compilers must resolve the member of this static field to the
395      * identifier of the field name.
396      */
397     public static final Value.String.Member hostName = new Value.String.Member(Members.hostName);
398     /**
399      * <p>An <b>opaque</b> static field defining a member that is named by the field name
400      * without a qualifying member and to access the property of the name on an object.</p>
401      * <p>The property, identified by this member, of a {@link JsLocation} object 
402      * refers to a read/write string that specifies the complete text of the 
403      * document's URL, unlike other {@link JsLocation} properties that specify only 
404      * portions of the URL. Setting this property to a new URL causes the browser 
405      * to read and display the contents of the new URL.</p> 
406      * @since 1.0
407      * @javascript Re-compilers must resolve the member of this static field to the
408      * identifier of the field name.
409      */
410     public static final Value.String.Member href     = new Value.String.Member(Members.href    );
411     /**
412      * <p>An <b>opaque</b> static field defining a member that is named by the field name
413      * without a qualifying member and to access the property of the name on an object.</p>
414      * <p>The property, identified by this member, of a {@link JsLocation} object 
415      * refers to a read/write string that specifies .</p> 
416      * @since 1.0
417      * @javascript Re-compilers must resolve the member of this static field to the
418      * identifier of the field name.
419      */
420     public static final Value.String.Member pathname = new Value.String.Member(Members.pathname);
421     /**
422      * <p>An <b>opaque</b> static field defining a member that is named by the field name
423      * without a qualifying member and to access the property of the name on an object.</p>
424      * <p>The property, identified by this member, of a {@link JsLocation} object 
425      * refers to a read/write string that specifies the port portion of the URL.</p> 
426      * @since 1.0
427      * @javascript Re-compilers must resolve the member of this static field to the
428      * identifier of the field name.
429      */
430     public static final Value.String.Member port     = new Value.String.Member(Members.port    );
431     /**
432      * <p>An <b>opaque</b> static field defining a member that is named by the field name
433      * without a qualifying member and to access the property of the name on an object.</p>
434      * <p>The property, identified by this member, of a {@link JsLocation} object 
435      * refers to a read/write string that specifies the protocol portion of a URL, 
436      * including the trailing colon.</p> 
437      * @since 1.0
438      * @javascript Re-compilers must resolve the member of this static field to the
439      * identifier of the field name.
440      */
441     public static final Value.String.Member protocol = new Value.String.Member(Members.protocol);
442     /**
443      * <p>An <b>opaque</b> static field defining a member that is named by the field name
444      * without a qualifying member and to access the property of the name on an object.</p>
445      * <p>The property, identified by this member, of a {@link JsLocation} object 
446      * refers to a read/write string that specifies the query portion of a URL, 
447      * including the leading question mark.</p> 
448      * @since 1.0
449      * @javascript Re-compilers must resolve the member of this static field to the
450      * identifier of the field name.
451      */
452     public static final Value.String.Member search   = new Value.String.Member(Members.search  );
453 
454     @Override
455     /**
456      * <p>Returns the primitive value associated with the current instance, if there is one.
457      * This invocation simply returns the instance itself for the current instance is an 
458      * object and there is no primitive value for it.</p>
459      * @return The current object itself.
460      * @since 1.0
461      * @javascript Re-compilers must convert the instance invocation of this method directly
462      * into a JavaScript invocation on its current object instance without changing the 
463      * method name, but expanding variable arguments, if any, into comma-separated values. 
464      */
465     public JsLocation valueOf() {
466         return new JsLocation((JsObject)var().valueOf());
467     }
468 
469     /**
470      * <p>Reloads the current document from the cache or the server.</p>
471      * <p>This method of the {@link JsLocation} object reloads the document that is 
472      * currently displayed in the window of the {@link JsLocation} object. It uses the 
473      * <tt>If-Modified-Since</tt> HTTP header to determine whether the document has 
474      * changed on the web server. If the document has changed, the method reloads the 
475      * document from the server, and if not, it reloads the document from the cache. 
476      * This is the same action that occurs when the user clicks on the browser's 
477      * <tt>Reload</tt> button.</p>
478      * @since 1.0
479      * @javascript Re-compilers must convert the instance invocation of this method directly
480      * into a JavaScript invocation on its current object instance without changing the 
481      * method name, but expanding variable arguments, if any, into comma-separated values. 
482      */
483     public void reload() {
484         call(reload);
485     }
486     /**
487      * <p>Reloads the current document from the cache or the server.</p>
488      * <p>This method of the {@link JsLocation} object reloads the document that is 
489      * currently displayed in the window of the {@link JsLocation} object. When called 
490      * with no arguments or with the argument <tt>false</tt>, it uses the <tt>If-Modified-Since</tt> 
491      * HTTP header to determine whether the document has changed on the web server. If 
492      * the document has changed, the method reloads the document from the server, and 
493      * if not, it reloads the document from the cache. This is the same action that 
494      * occurs when the user clicks on the browser's <tt>Reload</tt> button.</p>
495      * <p>When this method is called with the argument <tt>true</tt>, it always bypasses 
496      * the cache and reloads the document from the server, regardless of the last-modified 
497      * time of the document. This is the same action that occurs when the user <tt>Shift-clicks</tt> 
498      * on the browser's <tt>Reload</tt> button.</p>
499      * @param force An optional boolean argument that specifies whether the document 
500      * should be reloaded even if the server reports that it has not been modified since 
501      * it was last loaded. If this argument is <tt>false</tt> or undefined, the method 
502      * reloads the full page only if it has changed since last loaded.
503      * @since 1.0
504      * @javascript Re-compilers must convert the instance invocation of this method directly
505      * into a JavaScript invocation on its current object instance without changing the 
506      * method name, but expanding variable arguments, if any, into comma-separated values. 
507      */
508     public void reload(Object force) {
509         call(reload, force);
510     }
511     /**
512      * <p>Replaces the current document with a new one without generating a new entry in 
513      * the browser's session history.</p>
514      * <p>This method of the {@link JsLocation} object loads and displays a new document. 
515      * Loading a document in this way is different from simply setting {@link JsLocation#href} 
516      * in one important respect: this method does not generate a new entry in the 
517      * {@link JsHistory} object. When you use this method, the new URL overwrites the 
518      * current entry in the {@link JsHistory} object. After calling the method, the 
519      * browser's <tt>Back</tt> button does not return you to the previous URL; it 
520      * returns you to the URL before that one.</p>
521      * @param url A string that specifies the URL of the new document that is to replace 
522      * the current one. 
523      * @since 1.0
524      * @javascript Re-compilers must convert the instance invocation of this method directly
525      * into a JavaScript invocation on its current object instance without changing the 
526      * method name, but expanding variable arguments, if any, into comma-separated values. 
527      */
528     public void replace(Object url) {
529         call(replace, url);
530     }
531 }