KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > http > client > URL


1 /*
2  * Copyright 2006 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */

16 package com.google.gwt.http.client;
17
18 /**
19  * Utility class for the encoding and decoding URLs in their entirety or by
20  * their individual components.
21  *
22  * <h3>Required Module</h3>
23  * Modules that use this class should inherit
24  * <code>com.google.gwt.http.HTTP</code>.
25  *
26  * {@gwt.include com/google/gwt/examples/http/InheritsExample.gwt.xml}
27  */

28 public final class URL {
29
30   /**
31    * Returns a string where all URL escape sequences have been converted back to
32    * their original character representations.
33    *
34    * @param encodedURL string containing encoded URL encoded sequences
35    * @return string with no encoded URL encoded sequences
36    *
37    * @throws NullPointerException if encodedURL is <code>null</code>
38    */

39   public static String JavaDoc decode(String JavaDoc encodedURL) {
40     StringValidator.throwIfNull("encodedURL", encodedURL);
41     return decodeImpl(encodedURL);
42   }
43
44   /**
45    * Returns a string where all URL component escape sequences have been
46    * converted back to their original character representations.
47    *
48    * @param encodedURLComponent string containing encoded URL component
49    * sequences
50    * @return string with no encoded URL component encoded sequences
51    *
52    * @throws NullPointerException if encodedURLComponent is <code>null</code>
53    */

54   public static String JavaDoc decodeComponent(String JavaDoc encodedURLComponent) {
55     StringValidator.throwIfNull("encodedURLComponent",
56         encodedURLComponent);
57     return decodeComponentImpl(encodedURLComponent);
58   }
59
60   /**
61    * Returns a string where all characters that are not valid for a complete URL
62    * have been escaped. The escaping of a character is done by converting it
63    * into its UTF-8 encoding and then encoding each of the resulting bytes as a
64    * %xx hexadecimal escape sequence.
65    *
66    * <p>
67    * The following character sets are <em>not</em> escaped by this method:
68    * <ul>
69    * <li>ASCII digits or letters</li>
70    * <li>ASCII punctuation characters:
71    *
72    * <pre>
73    * - _ . ! ~ * ' ( )
74    * </pre>
75    *
76    * </li>
77    * <li>URL component delimiter characters:
78    *
79    * <pre>
80    * ; / ? : &amp; = + $ , #
81    * </pre>
82    *
83    * </li>
84    * </ul>
85    * </p>
86    *
87    * @param decodedURL a string containing URL characters that may require
88    * encoding
89    * @return a string with all invalid URL characters escaped
90    *
91    * @throws NullPointerException if decodedURL is <code>null</code>
92    */

93   public static String JavaDoc encode(String JavaDoc decodedURL) {
94     StringValidator.throwIfNull("decodedURL", decodedURL);
95     return encodeImpl(decodedURL);
96   }
97
98   /**
99    * Returns a string where all characters that are not valid for a URL
100    * component have been escaped. The escaping of a character is done by
101    * converting it into its UTF-8 encoding and then encoding each of the
102    * resulting bytes as a %xx hexadecimal escape sequence.
103    *
104    * <p>
105    * The following character sets are <em>not</em> escaped by this method:
106    * <ul>
107    * <li>ASCII digits or letters</li>
108    * <li>ASCII punctuation characters: <pre>- _ . ! ~ * ' ( )</pre></li>
109    * </ul>
110    * </p>
111    *
112    * <p>
113    * Notice that this method <em>does</em> encode the URL component delimiter
114    * characters:<blockquote>
115    *
116    * <pre>
117    * ; / ? : &amp; = + $ , #
118    * </pre>
119    *
120    * </blockquote>
121    * </p>
122    *
123    * @param decodedURLComponent a string containing invalid URL characters
124    * @return a string with all invalid URL characters escaped
125    *
126    * @throws NullPointerException if decodedURLComponent is <code>null</code>
127    */

128   public static String JavaDoc encodeComponent(String JavaDoc decodedURLComponent) {
129     StringValidator.throwIfNull("decodedURLComponent",
130         decodedURLComponent);
131     return encodeComponentImpl(decodedURLComponent);
132   }
133
134   /*
135    * Note: this method will convert the space character escape short form, '+',
136    * into a space.
137    */

138   private static native String JavaDoc decodeComponentImpl(String JavaDoc encodedURLComponent) /*-{
139     var regexp = /\+/g;
140     return decodeURIComponent(encodedURLComponent.replace(regexp, "%20"));
141   }-*/
;
142
143   private static native String JavaDoc decodeImpl(String JavaDoc encodedURL) /*-{
144     return decodeURI(encodedURL);
145   }-*/
;
146
147   /*
148    * Note: this method will convert any the space character into its escape
149    * short form, '+' rather than %20.
150    */

151   private static native String JavaDoc encodeComponentImpl(String JavaDoc decodedURLComponent) /*-{
152     var regexp = /%20/g;
153     return encodeURIComponent(decodedURLComponent).replace(regexp, "+");
154    }-*/
;
155
156   private static native String JavaDoc encodeImpl(String JavaDoc decodedURL) /*-{
157     return encodeURI(decodedURL);
158   }-*/
;
159
160   private URL() {
161   }
162 }
163
Popular Tags