atg.core.net
Class URLUtils

java.lang.Object
  atg.core.net.URLUtils

public class URLUtils
extends java.lang.Object

Utility class of static methods of useful URL related utilities.
Supersedes java.net.URLDecoder and java.net.URLEncoder. The URL escaping/unescaping functions use the ISO-8859-1 encoding for conversion between characters and bytes.

If you need a customized set of reserved (unescaped) ASCII characters, or a UTF-8 character encoding, then use a URLEscaper. This static implementation delegates to a URLEscaperISO88591 object (with the slight performance overhead for dispatching and data access in a non-static implementation).

See Also:

URLDecoder, URLEncoder, URLEscaper

Field Summary

static java.lang.String

CLASS_VERSION Class version string

Constructor Summary

URLUtils()

Method Summary

static void	escapeAndAppendUrl(java.lang.StringBuffer sb, char[] str) URL encode the contents of a character array and append them to the provided StringBuffer.
static void	escapeAndAppendUrlString(java.lang.StringBuffer pDestBuffer, java.lang.String pStr) URL encode the contents of the String and append them to the provided StringBuffer.
static java.lang.String	escapeUrlString(java.lang.String pStr) Return the passed in String as a URL escaped String.
static java.lang.String	escapeUrlString(java.lang.StringBuffer pStrBuf)
static char	hex2Char(char x, char y) Takes two ASCII characters, x and y, which represent a two-digit hexadecimal number (%xy), and returns the unsigned byte value in the range 0-255.
static boolean	isRelative(java.lang.String pUrl) Returns true if the URL is relative
static java.util.Hashtable	parsePostData(int len, java.io.InputStream in) Parses posted data sent from the client to the server, and builds a HashTable object with key-value pairs.
static java.util.Hashtable	parseQuery(char[] str) Parses a query string passed from the client to the server and builds a HashTable object with key-value pairs.
static java.util.Hashtable	parseQueryString(java.lang.String queryString) Parses a query string passed from the client to the server and builds a HashTable object with key-value pairs.
static java.lang.String	removeRelativePaths(java.lang.String pURL) Takes the an absolute URI that may have "../" in it and removes the "../" entries (by removing it and the directory above it in the path as well).
static void	resolvePureRelativePath(java.lang.StringBuffer pResultBuffer, java.lang.String pPath, java.lang.String pWorkingDirectory) Resolves a pure relative path against a working directory, handling ".." references.
static java.lang.String	resolvePureRelativePath(java.lang.String pPath, java.lang.String pWorkingDirectory) Resolves a pure relative path against a working directory, handling ".." references.
static java.lang.String	stripURIArgs(java.lang.String pURI) Strip off any arguments etc found in the URI.
static int	unescapeUrl(char[] str) Utility wrapper.
static int	unescapeUrl(char[] str, int len) Utility method for converting from a MIME format called x-www-form-urlencoded.
static java.lang.String	unescapeUrlString(java.lang.String pString) Utility method for converting from a MIME format called x-www-form-urlencoded to a String.
static java.lang.String	URIDirectory(java.lang.String pURI) Returns the directory part of a URI (everything up to the filename), which will begin and end with the "/" character.
static java.lang.String	URIFilename(java.lang.String pURI) Returns the filename part of a URI

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

Constructor Detail

URLUtils

public URLUtils()

Method Detail

isRelative

public static boolean isRelative(java.lang.String pUrl)

Returns true if the URL is relative

URIDirectory

public static java.lang.String URIDirectory(java.lang.String pURI)

Returns the directory part of a URI (everything up to the filename), which will begin and end with the "/" character.

URIFilename

public static java.lang.String URIFilename(java.lang.String pURI)

Returns the filename part of a URI

stripURIArgs

public static java.lang.String stripURIArgs(java.lang.String pURI)

Strip off any arguments etc found in the URI. This is done by looking for ';', '?', and '#' and truncating the URI to all that comes before the first instance of either character.

resolvePureRelativePath

public static java.lang.String resolvePureRelativePath(java.lang.String pPath,
                                                       java.lang.String pWorkingDirectory)
                                                throws java.lang.IllegalArgumentException

Resolves a pure relative path against a working directory, handling ".." references. Returns the String or null if the path could not be resolved.

Parameters:

pPath - The pure relative path (i.e. does not start with "/") to be resolved.

pWorkingDirectory - The working directory to resolve against, which should begin and end with the "/" character.

Throws:

java.lang.IllegalArgumentException

resolvePureRelativePath

public static void resolvePureRelativePath(java.lang.StringBuffer pResultBuffer,
                                           java.lang.String pPath,
                                           java.lang.String pWorkingDirectory)
                                    throws java.lang.IllegalArgumentException

Resolves a pure relative path against a working directory, handling ".." references. Returns the String or null if the path could not be resolved.

Parameters:

pPath - The pure relative path (i.e. does not start with "/") to be resolved.

pWorkingDirectory - The working directory to resolve against, which should begin and end with the "/" character.

Throws:

java.lang.IllegalArgumentException

removeRelativePaths

public static java.lang.String removeRelativePaths(java.lang.String pURL)
                                            throws java.lang.IllegalArgumentException

Takes the an absolute URI that may have "../" in it and removes the "../" entries (by removing it and the directory above it in the path as well).

Throws:

java.lang.IllegalArgumentException - if the path name has too many ../'s in it.

unescapeUrlString

public static java.lang.String unescapeUrlString(java.lang.String pString)

Utility method for converting from a MIME format called x-www-form-urlencoded to a String. Optimized version of java.net.URLDecoder#decode.

To convert to a String, each character is examined in turn:

• The ASCII characters 'a' through 'z', 'A' through 'Z', and '0' through '9', and unreserved delimiters /-_.*!~'() remain the same.
• The plus sign '+' is converted into a space character ' '.
• The remaining characters should be represented by 3-character strings which begin with the percent sign "%xy", where xy is the two-digit hexadecimal representation of a byte value. The conversion of hex escapes to byte values follows hex2Char usage. The conversion of byte values to Unicode characters uses the ISO-8859-1 encoding.
• Other raw characters are are passed through unchanged (because partial escaping is used in many situations).

If the string argument is null, an empty string is returned.

Parameters:

pString - String object to be decoded

Returns:

decoded String object, never null

See Also:

hex2Char( char, char ), unescapeUrl( char[], int ), URLDecoder.decode( String )

unescapeUrl

public static int unescapeUrl(char[] str)

Utility wrapper.

See Also:

unescapeUrl( char[], int )

unescapeUrl

public static int unescapeUrl(char[] str,
                              int len)

Utility method for converting from a MIME format called x-www-form-urlencoded. Optimized version of java.net.URLDecoder#decode. This version operates on a mutable character array.

Each character is examined in turn:

• The ASCII characters 'a' through 'z', 'A' through 'Z', and '0' through '9', and unreserved delimiters -_.*!~'() remain the same.
• The plus sign '+' is converted into a space character ' '.
• The remaining characters should be represented by 3-character strings which begin with the percent sign "%xy", where xy is the two-digit hexadecimal representation of a byte value. The conversion of hex characters to byte values follows hex2Char usage. The conversion of byte values to Unicode characters uses the ISO-8859-1 encoding.
• Other raw characters are are passed through unchanged (because partial escaping is used in many situations).

Parameters:

str - character array to be unescaped, conversion occurs in place

Returns:

length of significant output in the unescaped char array,
or -1 if no change was necessary

See Also:

hex2Char( char, char ), URLDecoder.decode( String )

escapeUrlString

public static final java.lang.String escapeUrlString(java.lang.String pStr)

Return the passed in String as a URL escaped String.

Uses the ISO-8859-1 character encoding. Equivalent to an optimized version of java.net.URLEncoder#encode.

If the string argument is null, an empty string is returned.

Parameters:

pStr - the String to be translated.

Returns:

the URL encoded String, never null

See Also:

URLEncoder.encode( String )

escapeUrlString

public static final java.lang.String escapeUrlString(java.lang.StringBuffer pStrBuf)

escapeAndAppendUrlString

public static final void escapeAndAppendUrlString(java.lang.StringBuffer pDestBuffer,
                                                  java.lang.String pStr)

URL encode the contents of the String and append them to the provided StringBuffer. Uses the ISO-8859-1 character encoding.

Parameters:

pDestBuffer - the StringBuffer to which to append the result

pStr - the String to be translated

See Also:

escapeAndAppendUrl( StringBuffer, char[] )

escapeAndAppendUrl

public static void escapeAndAppendUrl(java.lang.StringBuffer sb,
                                      char[] str)

URL encode the contents of a character array and append them to the provided StringBuffer.

This algorithm is only valid only for the lower 8-bits of the character value. The Unicode range U+0000 - U+00FF is equivalent to ISO-8859-1, so it handles these characters correctly. Unicode characters above U+00FF are truncated and mapped to a single character from ISO-8859-1.

Parameters:

sb - the StringBuffer to which to append the result

str - the character array to be translated

parseQueryString

public static java.util.Hashtable parseQueryString(java.lang.String queryString)

Parses a query string passed from the client to the server and builds a HashTable object with key-value pairs. Same functionality as javax.servlet.http.HttpUtils#parseQueryString but this implementation attempts optimization by inlining character unescaping with the key-value delimiter parsing.

The query string should be in the form of a string packaged by the GET or POST method, that is, it should have key-value pairs in the form key=value, with each pair separated from the next by a '&' character.

A key can appear more than once in the query string with different values. However, the key appears only once in the hashtable, with its value being an array of strings containing the multiple values sent by the query string.

The keys and values in the hashtable are stored in their decoded form, so any '+' characters are converted to spaces ' ', and byte values in hexadecimal notation "%xy" are converted to Unicode characters using the ISO-8859-1 encoding.

Parameters:

queryString - a string containing the query to be parsed

Returns:

a HashTable object built from the parsed key-value pairs, may be emtpty, but never null

Throws:

java.lang.IllegalArgumentException - if the query string is invalid

See Also:

parseQuery( char[] ), HttpUtils.parseQueryString( String )

parseQuery

public static java.util.Hashtable parseQuery(char[] str)

Parses a query string passed from the client to the server and builds a HashTable object with key-value pairs. The query string should be in the form of a string packaged by the GET or POST method, that is, it should have key-value pairs in the form key=value, with each pair separated from the next by a '&' character.

A key can appear more than once in the query string with different values. However, the key appears only once in the hashtable, with its value being an array of strings containing the multiple values sent by the query string.

The keys and values in the hashtable are stored in their decoded form, so any '+' characters are converted to spaces ' ', and byte values in hexadecimal notation "%xy" are converted to Unicode characters using the ISO-8859-1 encoding.

Parameters:

str - character array representing a query string

Returns:

a HashTable object built from the parsed key-value pairs, may be empty, but never null

Throws:

java.lang.IllegalArgumentException - if the query string is invalid

parsePostData

public static java.util.Hashtable parsePostData(int len,
                                                java.io.InputStream in)
                                         throws java.lang.IllegalArgumentException

Parses posted data sent from the client to the server, and builds a HashTable object with key-value pairs. Same functionality as java.servlet.http.HttpUtils#parsePostData, but this implementation attempts optimization by inlining character unescaping with the key-value delimiter parsing.

The query string should be in the form of a string packaged by the GET or POST method, that is, it should have key-value pairs in the form key=value, with each pair separated from the next by a '&' character.

A key can appear more than once in the query string with different values. However, the key appears only once in the hashtable, with its value being an array of strings containing the multiple values sent by the query string.

The keys and values in the hashtable are stored in their decoded form, so any '+' characters are converted to spaces ' ', and byte values in hexadecimal notation "%xy" are converted to characters.

The conversion from bytes to characters uses the standard ISO-8859-1 encoding, which is compatible with the version in java.servlet.http.HttpUtils, and also produces the String format expected by the Dynamo character Converter interface.

The return value will be an empty hashtable if len is not a positive value, or if there was an exception reading the stream, or if the stream ended before all the data was read.

Parameters:

len - an integer specifying the length, in characters, of the data to be parsed from the ServletInputStream argument

in - the ServletInputStream object that contains the data sent from the client

Returns:

a HashTable object built from the parsed key-value pairs (never null)

Throws:

java.lang.IllegalArgumentException - if the stream argument is null

See Also:

parseQuery( char[] ), java.servlet.http.HttpUtils#parsePostData( int, ServletInputStream )

hex2Char

public static char hex2Char(char x,
                            char y)

Takes two ASCII characters, x and y, which represent a two-digit hexadecimal number (%xy), and returns the unsigned byte value in the range 0-255.

If the character input values are outside the ASCII range (0x00-0x7f), their values are masked to 7-bits before the look-up. If the (masked) input ASCII character is not a valid hex character (0-9,a-f,A-F), then it does not contribute to the result value. If both inputs are invalid, then the result will be zero.

Neither the hex input nor the byte valued output can represent the full repertoire of Unicode characters. If the byte return value is interpreted directly as a character, it will appear to be from the the ISO-8859-1 repertoire, which is equivalent to the subset of Unicode with a zero upper byte. The name hex2Char is purely for historical reasons, it should really be hex2Byte.

Parameters:

x - high order digit of hexadecimal representation

y - low order digit of hexadecimal representation

Returns:

byte value