001: /*
002: * Copyright 2006 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.http.client;
017:
018: /**
019: * Utility class for the encoding and decoding URLs in their entirety or by
020: * their individual components.
021: *
022: * <h3>Required Module</h3>
023: * Modules that use this class should inherit
024: * <code>com.google.gwt.http.HTTP</code>.
025: *
026: * {@gwt.include com/google/gwt/examples/http/InheritsExample.gwt.xml}
027: */
028: public final class URL {
029:
030: /**
031: * Returns a string where all URL escape sequences have been converted back to
032: * their original character representations.
033: *
034: * @param encodedURL string containing encoded URL encoded sequences
035: * @return string with no encoded URL encoded sequences
036: *
037: * @throws NullPointerException if encodedURL is <code>null</code>
038: */
039: public static String decode(String encodedURL) {
040: StringValidator.throwIfNull("encodedURL", encodedURL);
041: return decodeImpl(encodedURL);
042: }
043:
044: /**
045: * Returns a string where all URL component escape sequences have been
046: * converted back to their original character representations.
047: *
048: * @param encodedURLComponent string containing encoded URL component
049: * sequences
050: * @return string with no encoded URL component encoded sequences
051: *
052: * @throws NullPointerException if encodedURLComponent is <code>null</code>
053: */
054: public static String decodeComponent(String encodedURLComponent) {
055: StringValidator.throwIfNull("encodedURLComponent",
056: encodedURLComponent);
057: return decodeComponentImpl(encodedURLComponent);
058: }
059:
060: /**
061: * Returns a string where all characters that are not valid for a complete URL
062: * have been escaped. The escaping of a character is done by converting it
063: * into its UTF-8 encoding and then encoding each of the resulting bytes as a
064: * %xx hexadecimal escape sequence.
065: *
066: * <p>
067: * The following character sets are <em>not</em> escaped by this method:
068: * <ul>
069: * <li>ASCII digits or letters</li>
070: * <li>ASCII punctuation characters:
071: *
072: * <pre>
073: * - _ . ! ~ * ' ( )
074: * </pre>
075: *
076: * </li>
077: * <li>URL component delimiter characters:
078: *
079: * <pre>
080: * ; / ? : & = + $ , #
081: * </pre>
082: *
083: * </li>
084: * </ul>
085: * </p>
086: *
087: * @param decodedURL a string containing URL characters that may require
088: * encoding
089: * @return a string with all invalid URL characters escaped
090: *
091: * @throws NullPointerException if decodedURL is <code>null</code>
092: */
093: public static String encode(String decodedURL) {
094: StringValidator.throwIfNull("decodedURL", decodedURL);
095: return encodeImpl(decodedURL);
096: }
097:
098: /**
099: * 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: * ; / ? : & = + $ , #
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 encodeComponent(String 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 decodeComponentImpl(
139: String encodedURLComponent) /*-{
140: var regexp = /\+/g;
141: return decodeURIComponent(encodedURLComponent.replace(regexp, "%20"));
142: }-*/;
143:
144: private static native String decodeImpl(String encodedURL) /*-{
145: return decodeURI(encodedURL);
146: }-*/;
147:
148: /*
149: * Note: this method will convert any the space character into its escape
150: * short form, '+' rather than %20.
151: */
152: private static native String encodeComponentImpl(
153: String decodedURLComponent) /*-{
154: var regexp = /%20/g;
155: return encodeURIComponent(decodedURLComponent).replace(regexp, "+");
156: }-*/;
157:
158: private static native String encodeImpl(String decodedURL) /*-{
159: return encodeURI(decodedURL);
160: }-*/;
161:
162: private URL() {
163: }
164: }
|