oracle.javatools.net
Class EncoderUtils

java.lang.Object
  oracle.javatools.net.EncoderUtils

public class EncoderUtils
extends java.lang.Object

Utility functions for encoding URLs for output. This class contains three classes of encoding functions:

1. Functions that encode entire URLs for final output. The UIX rendering layer automatically uses these functions, so it is generally not necessary.
   • encodeURL
   • writeURL
2. Functions that encode query parameters to be handed off to UIX Components (aka Marlin beans or UIX rendering).
   • encodeUIXQueryParameter
   • appendUIXQueryParameter
3. Functions that encode query parameters for final output. These should be used only when the parameters are not being rendered with UIX (or UIX Components, aka Marlin Beans).
   • encodeString

The major difference between these types of functions is what characters they will encode.

Category 1 (entire URLs) will perform correct NLS encodings, but cannot encode '%', '&' '=', '?', '#', and '+', as all of these characters have very specific meanings in an URL. In the case of '%' and '+' note that this means UIX will never double-encode an URL.

Category 2 (parameters for UIX) will encode only '%', '+', '&', and '#'. Note that it does not perform NLS encodings, or any disallowed URL characters (like the space character), as it relies on the UIX rendering layer to handle these where it can be performed more efficiently. Also, note that '+' and '%' are encoded, so this function should not be used on parameters that have already been URL encoded.

Finally, Category 3 (parameters for final output) encodes all characters except for '-', '_', '.', and '/'. There is no need to call these functions if you'll be using UIX (or Marlin beans) to render the URL.

EncoderUtils also includes support for manually decoding strings. This is generally not necessary, as Servlets are generally responsible for decoding parameters themselves, but developers working around buggy servlet engines may find this useful, as will developers writing their own HTTP code.

Constructor Summary

EncoderUtils()

Method Summary

static void	appendUIXQueryParameter(java.lang.StringBuffer buffer, java.lang.String text) Partially encodes a query parameter.
static java.lang.String	decodeString(java.lang.String text) URL-decodes a string, assuming the platform default encoding.
static java.lang.String	decodeString(java.lang.String text, java.lang.String encoding) URL-decodes a string.
static java.lang.String	encodeString(java.lang.String text, java.lang.String encoding) Fully encodes a string - all characters with special meanings in an URL will be '%' encoded.
static java.lang.String	encodeUIXQueryParameter(java.lang.String text) Partially encodes a query parameter.
static java.lang.String	encodeURL(java.lang.String text, java.lang.String queryEncoding, boolean useISOForBody) Encodes a string into URL-encoded format.
static void	writeQueryParameters(java.io.Writer out, java.lang.String text, java.lang.String encoding, int start) Writes a query parameter.
static void	writeURL(java.io.Writer out, java.lang.String text, java.lang.String queryEncoding, boolean useISOForBody) Writes a string into URL-encoded format out to a Writer.

Methods inherited from class java.lang.Object

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

Constructor Detail

EncoderUtils

public EncoderUtils()

Method Detail

encodeURL

public static java.lang.String encodeURL(java.lang.String text,
                                         java.lang.String queryEncoding,
                                         boolean useISOForBody)
                                  throws java.io.UnsupportedEncodingException

Encodes a string into URL-encoded format. For details on exactly how this method works, please see the writeURL(java.io.Writer, java.lang.String, java.lang.String, boolean) method.

Parameters:

text - the unencoded (or partially encoded) String

queryEncoding - the character set encoding for after the first question mark

useISOForBody - if false, text before the first question mark will be encoded with UTF-8; if true, encoded with ISO-8859-1.

Returns:

the encoded string

Throws:

java.io.UnsupportedEncodingException

writeURL

public static void writeURL(java.io.Writer out,
                            java.lang.String text,
                            java.lang.String queryEncoding,
                            boolean useISOForBody)
                     throws java.io.IOException,
                            java.io.UnsupportedEncodingException

Writes a string into URL-encoded format out to a Writer.

All characters before the start of the query string will be encoded using either UTF-8 or ISO-8859-1. The former is the ideal standard, as it allows any Unicode character to be used in the path. However, many web servers assume ISO-8859-1 instead, hence the option.

Characters after the start of the query string will be encoded using a client-defined encoding. You'll need to use the encoding that the server will expect. (HTML forms will generate query strings using the character encoding that the HTML itself was generated in.)

All characters will be encoded as needed for URLs, with the exception of the percent symbol ("%"). Because this is the character itself used for escaping, attempting to escape this character would cause this code to double-escape some strings. It also may be necessary to pre-escape some characters. In particular, a question mark ("?") is considered the start of the query string.

Parameters:

out - a Writer for the output

text - the unencoded (or partially encoded) String

queryEncoding - the character set encoding for after the first question mark

useISOForBody - if false, text before the first question mark will be encoded with UTF-8; if true, encoded with ISO-8859-1.

Throws:

java.io.IOException

java.io.UnsupportedEncodingException

writeQueryParameters

public static void writeQueryParameters(java.io.Writer out,
                                        java.lang.String text,
                                        java.lang.String encoding,
                                        int start)
                                 throws java.io.IOException,
                                        java.io.UnsupportedEncodingException

Writes a query parameter. Very few clients will need to use this method - most will just call writeURL or encodeURL.

Throws:

java.io.IOException

java.io.UnsupportedEncodingException

encodeUIXQueryParameter

public static java.lang.String encodeUIXQueryParameter(java.lang.String text)

Partially encodes a query parameter. The characters '%', '#', '&',. and '+' will be encoded, but no other characters will be. This method should only be used for encoding strings that will be passed to the UIX rendering layer, because it does not perform the pieces of URL encoding automatically handled in that layer.

appendUIXQueryParameter

public static void appendUIXQueryParameter(java.lang.StringBuffer buffer,
                                           java.lang.String text)

Partially encodes a query parameter. The characters '%', '#', '&',. and '+' will be encoded, but no other characters will be. This method should only be used for encoding strings that will be passed to the UIX rendering layer, because it does not perform the pieces of URL encoding automatically handled in that layer.

encodeString

public static java.lang.String encodeString(java.lang.String text,
                                            java.lang.String encoding)
                                     throws java.io.UnsupportedEncodingException

Fully encodes a string - all characters with special meanings in an URL will be '%' encoded. This means that this function can double-encode strings that are already encoded, and will cause serious problems if used for an entire URL, since it'll escape characters like '?' and '&'. Generally, this function should be used only for encoding single query values.

Throws:

java.io.UnsupportedEncodingException

decodeString

public static java.lang.String decodeString(java.lang.String text)
                                     throws java.io.UnsupportedEncodingException

URL-decodes a string, assuming the platform default encoding. This function assumes that (for query parameters) CaboHttpUtils.decodeRequestParameter() has already been called, and this function is being passed the result of that function. That is: if the string does not contain any '%' characters, the string will be returned unmodified.

Parameters:

text - the original text

Throws:

java.io.UnsupportedEncodingException

decodeString

public static java.lang.String decodeString(java.lang.String text,
                                            java.lang.String encoding)
                                     throws java.io.UnsupportedEncodingException

URL-decodes a string. This function assumes that (for query parameters) CaboHttpUtils.decodeRequestParameter() has already been called, and this function is being passed the result of that function. That is: if the string does not contain any '%' characters, the string will be returned unmodified.

Parameters:

text - the original text

encoding - the character encoding to assume

Throws:

java.io.UnsupportedEncodingException