wt.util
Class EncodingConverter

java.lang.Object
  java.io.OutputStream
      java.io.ByteArrayOutputStream
          wt.util.EncodingConverter

Direct Known Subclasses:

EncodingConverter

public class EncodingConverter

extends ByteArrayOutputStream

The class contains utility methods for converting a String into a MIME format called "x-www-form-urlencoded" and vice versa.

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

• The ASCII characters 'a' through 'z', 'A' through 'Z', and '0' through '9' remain the same.
• The space character ' ' is converted into a plus sign '+'.
• All other characters are converted into an 8-bit byte sequence using a character encoding and the resulting bytes are each represented as a 3-character string "%xy", where xy is the two-digit hexadecimal representation of the byte.

Deployment Notes:

The EncodingConverter is a replacement for WTURLEncoder and is instance based. The EncodingConverter should not be shared amongst threads or used as a static instance unless appropriate synchronization blocks are used to protect the internal buffers from overrighting. This can be done one of two ways. Firstly by declaring the method which calls the encode/decode methods as synchronized, or by placing a syncrhonized block around the actually calls to encode/decode as shown below.





static EncodingConverter staticEncoder = new EncodingConverter();

public void sampleMethod(String s)
{

synchronized( staticEncoder )
{

staticEncoder.encode(s);

}

}

Supported API: true
Extendable: false

Field Summary

private static char[]	cannotEscapeByEncodingChars
private OutputStreamWriter	defaultWriter The default output stream writer
static boolean[]	dontNeedEncoding Array of characters that don't require encoding public so WTURLEncoder can use it.
private String	ivEncoding The EncodingConverter's Encoding
static int	MAX_BYTES_PER_CHAR Constnat for Maximum bytes per character
static char[]	toHex
static String	UTF8 Constant for UTF8 encoding used by the Java Language

Fields inherited from class java.io.ByteArrayOutputStream

buf, count

Constructor Summary

EncodingConverter()
Consturctor to create a new EncodingConverter with the encoding set to UTF-8.

EncodingConverter(int ByteSize)
Constructor to create a new EncodingConverter with an encoding set to UTF-8 and a specified buffer capacity.

EncodingConverter(String encoding)
Constructor to create a new EncodingConverter with a specified encoding.

Method Summary

String	decode(String s) Translates a string from x-www-form-urlencoded format back into a string.
String	decode(String encoded, String encoding) Translates a string from x-www-form-urlencoded format back the original string.
static String	decodeBytes(String str) Convience method to convert the bytes of a String in ISO-8859_1 encoding to UTF-8 encoding.
static String	decodeBytes(String str, String enc) Convience method to convert the bytes of a String in ISO-8859_1 encoding to a designated encoding.
static String	decodeBytes(String str, String from_enc, String to_enc) Convience method to convert the bytes of a String in an input encoding encoding to a designated encoding.
String	encode(String s) Translates a string into x-www-form-urlencoded format.
void	encode(StringBuffer buf, String s) Translates a string into x-www-form-urlencoded format.
void	encode(StringBuffer buf, String s, String encoding) Translates a string into x-www-form-urlencoded format.
String	encode(String s, String encoding) Translates a string into x-www-form-urlencoded format.
static String	escape(String str) Escape special characters in accordance with URL path segment encoding requirements.
static String	escape(String str, EncodingConverter encoder)
private static int	getNextIndexOf(String str, int strLength, int startIdx, char[] searchChars)
private void	setupBuffersAndWriters() Internal method used to create the writers for the class Supported API: false
static String	unicodeToAscii(String in_str) Convert a Unicode string into the so called 'ascii' format, where each Unicode characters (except the range of 0x00 - 0x7F) are represented with uxxxx escape sequences.

Methods inherited from class java.io.ByteArrayOutputStream

close, reset, size, toByteArray, toString, toString, toString, write, write, writeTo

Methods inherited from class java.io.OutputStream

flush, write

Methods inherited from class java.lang.Object

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

Field Detail

toHex

public static final char[] toHex

dontNeedEncoding

public static boolean[] dontNeedEncoding

Array of characters that don't require encoding public so WTURLEncoder can use it.

MAX_BYTES_PER_CHAR

public static final int MAX_BYTES_PER_CHAR

Constnat for Maximum bytes per character

See Also:

Constant Field Values

UTF8

public static final String UTF8

Constant for UTF8 encoding used by the Java Language

See Also:

Constant Field Values

ivEncoding

private String ivEncoding

The EncodingConverter's Encoding

defaultWriter

private OutputStreamWriter defaultWriter

The default output stream writer

cannotEscapeByEncodingChars

private static final char[] cannotEscapeByEncodingChars

Constructor Detail

EncodingConverter

public EncodingConverter()

Consturctor to create a new EncodingConverter with the encoding set to UTF-8.

Supported API: true

EncodingConverter

public EncodingConverter(int ByteSize)

Constructor to create a new EncodingConverter with an encoding set to UTF-8 and a specified buffer capacity.

Supported API: true

Parameters:

ByteSize - The buffer capacity.

EncodingConverter

public EncodingConverter(String encoding)

Constructor to create a new EncodingConverter with a specified encoding.

Supported API: true

Parameters:

encoding - The encoding to use for encode/decoding.

Method Detail

setupBuffersAndWriters

private void setupBuffersAndWriters()

Internal method used to create the writers for the class

Supported API: false

encode

public String encode(String s)

Translates a string into x-www-form-urlencoded format. Hex escaped characters are first encoded using UTF8 character encoding before Hex escaping the resulting bytes. This produces an encoded string that can be decoded without loss of data.

Thread Safe: true (not if shared between thread)

Supported API: true

Parameters:

s - String to be translated.

Returns:

the translated String.

encode

public String encode(String s,
                     String encoding)

Translates a string into x-www-form-urlencoded format. Hex escaped characters are first encoded using the given character encoding before Hex escaping the resulting bytes.

Thread Safe: true (not if shared between thread)

Supported API: true

Parameters:

s - String to be translated.

encoding - the character encoding name

Returns:

the translated String, or "" if the string s was null.

encode

public void encode(StringBuffer buf,
                   String s)

Translates a string into x-www-form-urlencoded format. Hex escaped characters are first encoded using UTF8 character encoding before Hex escaping the resulting bytes. This produces an encoded string that can be decoded without loss of data.

Thread Safe: true (not if shared between thread)

Supported API: true

Parameters:

buf - StringBuffer to receive encoded characters.

s - String to be translated.

encode

public void encode(StringBuffer buf,
                   String s,
                   String encoding)

Translates a string into x-www-form-urlencoded format. Hex escaped characters are first encoded using the given character encoding before Hex escaping the resulting bytes.

Thread Safe: true (not if shared between thread)

Supported API: true

Parameters:

buf - StringBuffer to receive encoded characters.

s - String to be translated.

encoding - the character encoding name

escape

public static String escape(String str)

Escape special characters in accordance with URL path segment encoding requirements. Replaces spaces with %20 and double quotes with %22. In theory, all special characters should be URLEncoded, but the 4.x browsers don't interpret the file name correctly using their native character encoding when that is done.

Supported API: true

Parameters:

str - String to escape.

Returns:

Escaped string value.

escape

public static String escape(String str,
                            EncodingConverter encoder)

getNextIndexOf

private static int getNextIndexOf(String str,
                                  int strLength,
                                  int startIdx,
                                  char[] searchChars)

decode

public String decode(String s)

Translates a string from x-www-form-urlencoded format back into a string. Hex escaped bytes are converted and the resulting sequence of 8-bit values is converted to characters using UTF8 encoding. This produces a decoded string from the results of encode without loss data.

Thread Safe: true (not if shared between thread)

Supported API: true

Parameters:

s - String to be translated.

Returns:

the translated String.

decode

public String decode(String encoded,
                     String encoding)

Translates a string from x-www-form-urlencoded format back the original string. Hex escaped bytes are converted and the resulting sequence of 8-bit values is converted to characters using the given character encoding.

Thread Safe: true (not if shared between thread)

Supported API: true

Parameters:

encoded - String to be translated.

encoding - the character encoding name

Returns:

the translated String or "" if encoded is null.

decodeBytes

public static final String decodeBytes(String str)
                                throws UnsupportedEncodingException

Convience method to convert the bytes of a String in ISO-8859_1 encoding to UTF-8 encoding. This should typically be called after a JSP request.getParameter( ) call.

Supported API: true

Parameters:

str - The string to re-encode for the correct bytes.

Returns:

String the decoded and translated String.

Throws:

UnsupportedEncodingException

decodeBytes

public static final String decodeBytes(String str,
                                       String enc)
                                throws UnsupportedEncodingException

Convience method to convert the bytes of a String in ISO-8859_1 encoding to a designated encoding. This should typically be called after a JSP request.getParameter( ) call.

Supported API: true

Parameters:

str - The string to re-encode for the correct bytes.

enc - The encoding to translate to.

Returns:

String the decoded and translated String.

Throws:

UnsupportedEncodingException

decodeBytes

public static final String decodeBytes(String str,
                                       String from_enc,
                                       String to_enc)
                                throws UnsupportedEncodingException

Convience method to convert the bytes of a String in an input encoding encoding to a designated encoding. This should typically be called after a JSP request.getParameter( ) call.

Supported API: true

Parameters:

str - The string to re-encode for the correct bytes.

from_enc - The encoding coming from.

to_enc - The encoding to translate to.

Returns:

String the decoded and translated String.

Throws:

UnsupportedEncodingException

unicodeToAscii

public static String unicodeToAscii(String in_str)

Convert a Unicode string into the so called 'ascii' format, where each Unicode characters (except the range of 0x00 - 0x7F) are represented with uxxxx escape sequences. xxxx is a four digit hexadecimal integer.