org.apache.commons.httpclient
Class URIUtil

java.lang.Object
  |
  +--org.apache.commons.httpclient.URIUtil

public class URIUtil
extends java.lang.Object

General purpose methods for encoding URI's, as described in RFC 2396.

This class provides a number of methods useful for encoding and decoding the "%HH" format, as used in various HTTP related formats such as URIs and the x-www-form-urlencoded MIME type. It can be seen as a more flexible (and more robust) form of the core JDK URLEncoder and java.net.URLDecoder classes.

As well this class provides some useful methods for dealing with URLs

Version:
$Revision: 1.11 $ $Date: 2002/08/07 02:13:22 $
Author:
Craig R. McClanahan, Tim Tye, Remy Maucherat, Park, Sung-Gu, Rodney Waldhoff

Constructor Summary
URIUtil()
           
 
Method Summary
static java.lang.String decode(byte[] bytes)
          Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
static java.lang.String decode(byte[] bytes, boolean plusIsSpace)
          Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
static java.lang.String decode(byte[] bytes, int off, int len)
          Unescape a fragment of the given byte array, by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
static java.lang.String decode(byte[] bytes, int off, int len, boolean plusIsSpace)
          Unescape a fragment of the given byte array, by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
static java.lang.String decode(byte[] bytes, int off, int len, java.lang.String enc)
          Unescape a fragment of the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the specified encoding.
static java.lang.String decode(byte[] bytes, int off, int len, java.lang.String enc, boolean plusIsSpace)
          Unescape a fragment of the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the specified encoding.
static java.lang.String decode(byte[] bytes, java.lang.String enc)
          Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
static java.lang.String decode(byte[] bytes, java.lang.String enc, boolean plusIsSpace)
          Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
static java.lang.String decode(java.lang.String str)
          Unescape the given String, converting all %HH sequences into the UTF-8 character 0xHH.
static java.lang.String decode(java.lang.String str, boolean plusIsSpace)
          Unescape the given String, converting all %HH sequences into the UTF-8 character 0xHH.
static java.lang.String encode(byte[] bytes, java.util.BitSet safe)
          Escape the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.
static java.lang.String encode(byte[] bytes, java.util.BitSet safe, boolean spaceAsPlus)
          Escape the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.
static java.lang.String encode(byte[] bytes, int off, int len, java.util.BitSet safe)
          Escape a fragment of the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.
static java.lang.String encode(byte[] bytes, int off, int len, java.util.BitSet safe, boolean spaceAsPlus)
          Escape a fragment of the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.
static java.lang.String encode(java.lang.String str)
          Escape the given String by replacing all characters not in the default set of safe characters (unreserved()) into the sequence %HH (where HH is the hex value of the character in the default encoding).
static java.lang.String encode(java.lang.String str, java.util.BitSet safe)
          Escape the given String by replacing all characters not in the given set of safe characters into the sequence %HH (where HH is the hex value of the character in the default encoding).
static java.lang.String encode(java.lang.String str, java.util.BitSet safe, boolean spaceAsPlus)
          Escape the given String by replacing all characters not in the given set of safe characters into the sequence %HH (where HH is the hex value of the character in the default encoding).
static java.lang.String encode(java.lang.String str, java.util.BitSet safe, java.lang.String enc)
          Escape the given String, first converting the String to bytes using the specified encoding, then replacing all bytes not in the given set of safe bytes into the sequence %HH (where HH is the hex value of the byte).
static java.lang.String encode(java.lang.String str, java.util.BitSet safe, java.lang.String enc, boolean spaceAsPlus)
          Escape the given String, first converting the String to bytes using the specified encoding, then replacing all bytes not in the given set of safe bytes into the sequence %HH (where HH is the hex value of the byte).
static java.lang.String encode(java.lang.String str, boolean spaceAsPlus)
          Escape the given String by replacing all characters not in the default set of safe characters (unreserved()) into the sequence %HH (where HH is the hex value of the character in the default encoding).
static java.lang.String getPath(java.lang.String url)
          Returns the path portion of the given URL.
static java.lang.String getQueryString(java.lang.String url)
          Returns the query string for the given URL.
static java.util.BitSet pathSafe()
           
static java.util.BitSet queryStringValueSafe()
           
static java.util.BitSet unreserved()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

URIUtil

public URIUtil()
Method Detail

decode

public static final java.lang.String decode(java.lang.String str)
Unescape the given String, converting all %HH sequences into the UTF-8 character 0xHH.
Parameters:
str - the escaped String
Throws:
java.lang.IllegalArgumentException - if a '%' character is not followed by a valid 2-digit hexadecimal number

decode

public static final java.lang.String decode(java.lang.String str,
                                            boolean plusIsSpace)
Unescape the given String, converting all %HH sequences into the UTF-8 character 0xHH.

When plusIsSpace is true, '+' will be converted into ' ' (space), as is used in the x-www-form-urlencoded MIME type.

Parameters:
str - the escaped String
Throws:
java.lang.IllegalArgumentException - if a '%' character is not followed by a valid 2-digit hexadecimal number

decode

public static final java.lang.String decode(byte[] bytes)
Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
Parameters:
bytes - the escaped byte array, which may be changed by this call
Throws:
java.lang.IllegalArgumentException - if a '%' byte is not followed by a valid 2-digit hexadecimal number (as bytes)

decode

public static final java.lang.String decode(byte[] bytes,
                                            boolean plusIsSpace)
Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.

When plusIsSpace is true, '+' will be converted into ' ' (space), as is used in the x-www-form-urlencoded MIME type.

Parameters:
bytes - the escaped byte array, which may be changed by this call
Throws:
java.lang.IllegalArgumentException - if a '%' byte is not followed by a valid 2-digit hexadecimal number (as bytes)

decode

public static final java.lang.String decode(byte[] bytes,
                                            int off,
                                            int len)
Unescape a fragment of the given byte array, by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
Parameters:
bytes - the escaped byte array, which may be changed by this call
off - the index of the first byte to convert
len - the number of unescaped bytes to convert
Throws:
java.lang.IllegalArgumentException - if a '%' byte is not followed by a valid 2-digit hexadecimal number (as bytes)

decode

public static final java.lang.String decode(byte[] bytes,
                                            int off,
                                            int len,
                                            boolean plusIsSpace)
Unescape a fragment of the given byte array, by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.

When plusIsSpace is true, '+' will be converted into ' ' (space), as is used in the x-www-form-urlencoded MIME type.

Parameters:
bytes - the escaped byte array, which may be changed by this call
off - the index of the first byte to convert
len - the number of unescaped bytes to convert
Throws:
java.lang.IllegalArgumentException - if a '%' byte is not followed by a valid 2-digit hexadecimal number (as bytes)

decode

public static final java.lang.String decode(byte[] bytes,
                                            java.lang.String enc)
                                     throws java.io.UnsupportedEncodingException
Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.
Parameters:
bytes - the escaped byte array, which may be changed by this call
enc - the encoding to use
Throws:
java.lang.IllegalArgumentException - if a '%' byte is not followed by a valid 2-digit hexadecimal number (as bytes)

decode

public static final java.lang.String decode(byte[] bytes,
                                            java.lang.String enc,
                                            boolean plusIsSpace)
                                     throws java.io.UnsupportedEncodingException
Unescape the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the default encoding.

When plusIsSpace is true, '+' will be converted into ' ' (space), as is used in the x-www-form-urlencoded MIME type.

Parameters:
bytes - the escaped byte array, which may be changed by this call
enc - the encoding to use
Throws:
java.lang.IllegalArgumentException - if a '%' byte is not followed by a valid 2-digit hexadecimal number (as bytes)

decode

public static final java.lang.String decode(byte[] bytes,
                                            int off,
                                            int len,
                                            java.lang.String enc)
                                     throws java.io.UnsupportedEncodingException
Unescape a fragment of the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the specified encoding.
Parameters:
bytes - the escaped byte array
off - the index of the first byte to convert
len - the number of escaped bytes to convert
enc - the encoding to use
Throws:
java.lang.IllegalArgumentException - if a '%' character is not followed by a valid 2-digit hexadecimal number

decode

public static final java.lang.String decode(byte[] bytes,
                                            int off,
                                            int len,
                                            java.lang.String enc,
                                            boolean plusIsSpace)
                                     throws java.io.UnsupportedEncodingException
Unescape a fragment of the given byte array by first converting all '%', 'H', 'H' sequences into the byte 0xHH, and then converting the bytes into characters using the specified encoding.

When plusIsSpace is true, a '+' byte will be converted into ' ', as is used in the x-www-form-urlencoded MIME type.

Parameters:
bytes - the escaped byte array
off - the index of the first byte to convert
len - the number of escaped bytes to convert
enc - the encoding to use
Throws:
java.lang.IllegalArgumentException - if a '%' character is not followed by a valid 2-digit hexadecimal number

encode

public static final java.lang.String encode(java.lang.String str)
Escape the given String by replacing all characters not in the default set of safe characters (unreserved()) into the sequence %HH (where HH is the hex value of the character in the default encoding).
Parameters:
str - The unescaped string

encode

public static final java.lang.String encode(java.lang.String str,
                                            boolean spaceAsPlus)
Escape the given String by replacing all characters not in the default set of safe characters (unreserved()) into the sequence %HH (where HH is the hex value of the character in the default encoding).

When spaceAsPlus is true and ' ' needs to be encoded (i.e., it is not a safe byte), then it will be converted to '+', as is used in the x-www-form-urlencoded MIME type.

Parameters:
str - The unescaped string

encode

public static final java.lang.String encode(java.lang.String str,
                                            java.util.BitSet safe)
Escape the given String by replacing all characters not in the given set of safe characters into the sequence %HH (where HH is the hex value of the character in the default encoding).
Parameters:
str - The unescaped string
safe - The set of "safe" characters (not to be escaped)

encode

public static final java.lang.String encode(java.lang.String str,
                                            java.util.BitSet safe,
                                            boolean spaceAsPlus)
Escape the given String by replacing all characters not in the given set of safe characters into the sequence %HH (where HH is the hex value of the character in the default encoding).

When spaceAsPlus is true and ' ' needs to be encoded (i.e., it is not a safe byte), then it will be converted to '+', as is used in the x-www-form-urlencoded MIME type.

Parameters:
str - The unescaped string
safe - The set of "safe" characters (not to be escaped)

encode

public static final java.lang.String encode(byte[] bytes,
                                            java.util.BitSet safe)
Escape the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.
Parameters:
bytes - the unescaped bytes
safe - the set of "safe" bytes (not to be escaped)

encode

public static final java.lang.String encode(byte[] bytes,
                                            java.util.BitSet safe,
                                            boolean spaceAsPlus)
Escape the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.

When spaceAsPlus is true and ' ' needs to be encoded (i.e., it is not a safe byte), then it will be converted to '+', as is used in the x-www-form-urlencoded MIME type.

Parameters:
bytes - the unescaped bytes
safe - the set of "safe" bytes (not to be escaped)

encode

public static final java.lang.String encode(byte[] bytes,
                                            int off,
                                            int len,
                                            java.util.BitSet safe)
Escape a fragment of the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.
Parameters:
bytes - The unescaped bytes
off - the index of the first byte to convert
len - the number of unescaped bytes to convert
safe - The set of "safe" bytes (not to be escaped)

encode

public static final java.lang.String encode(byte[] bytes,
                                            int off,
                                            int len,
                                            java.util.BitSet safe,
                                            boolean spaceAsPlus)
Escape a fragment of the given byte array by first converting all bytes not in the given set of "safe" bytes to the sequence '%', 'H', 'H' (where HH is the hex value of the byte), and then converting the bytes into characters using the default encoding.

When spaceAsPlus is true and ' ' needs to be encoded (i.e., it is not a safe byte), then it will be converted to '+', as is used in the x-www-form-urlencoded MIME type.

Parameters:
bytes - The unescaped bytes
off - the index of the first byte to convert
len - the number of unescaped bytes to convert
safe - The set of "safe" bytes (not to be escaped)

encode

public static final java.lang.String encode(java.lang.String str,
                                            java.util.BitSet safe,
                                            java.lang.String enc)
Escape the given String, first converting the String to bytes using the specified encoding, then replacing all bytes not in the given set of safe bytes into the sequence %HH (where HH is the hex value of the byte).
Parameters:
str - the unescaped string
safe - the set of "safe" characters (not to be escaped)
enc - the encoding to use

encode

public static final java.lang.String encode(java.lang.String str,
                                            java.util.BitSet safe,
                                            java.lang.String enc,
                                            boolean spaceAsPlus)
Escape the given String, first converting the String to bytes using the specified encoding, then replacing all bytes not in the given set of safe bytes into the sequence %HH (where HH is the hex value of the byte).

When spaceAsPlus is true and ' ' needs to be encoded (i.e., it is not a safe byte), then it will be converted to '+', as is used in the x-www-form-urlencoded MIME type.

Parameters:
str - the unescaped string
safe - the set of "safe" characters (not to be escaped)
enc - the encoding to use

getPath

public static final java.lang.String getPath(java.lang.String url)
Returns the path portion of the given URL. If the URL contains an empty path (e.g. http://www.serverl.com) this method returns "/". This method exists in URIUtil to provide support for JDK versions prior to 1.3 when java.net.URI.getPath() was added.
Parameters:
url - - the URL
Returns:
the path portion of the URL or "/" if the URL contains an empty path

getQueryString

public static final java.lang.String getQueryString(java.lang.String url)
Returns the query string for the given URL. If the URL does not contain a query string this method returns null. This method exists in URIUtil to provide support for JDK versions prior to 1.3 when java.net.URL.getQueryString() was added.
Parameters:
url - - the URL
Returns:
the query string portion of the URL or null if the URL doesn't contain a query string

unreserved

public static final java.util.BitSet unreserved()

pathSafe

public static final java.util.BitSet pathSafe()

queryStringValueSafe

public static final java.util.BitSet queryStringValueSafe()


Copyright (c) 2001 - Apache Software Foundation