com.buildforge.services.common.text
Class StringConverter

java.lang.Object
  extended by com.buildforge.services.common.text.StringConverter

public class StringConverter
extends java.lang.Object

This class performs translation to and from UTF-8 or ISO-8859-1 encoding, as directed. The ISO-8859-1 conversion is done directly because it is such a simple conversion to perform and because that avoids the overhead of using the library conversion routines, which often involve unnecessary creation of wrapper objects. The conversion to ISO-8859-1 (Latin-1) does not check for invalid input characters. If there are any, their high-order bits are silently discarded.

The conversion routines use cached CharBuffer and ByteBuffer objects whenever it is possible to do so. These cached objects should be large enough for the vast majority of conversion requests, but when they are not, a temporary buffer is allocated instead.

As the cached buffer is reused whenever possible, the caller should make immediate use of the return value. Old buffer contents should not be trusted once another conversion has been requested. For efficiency reasons, this class requires thread confinement for correct behavior. Threads should always obtain their own reference to a string converter using get(), and such objects should never be shared with other threads.


Field Summary
static int BYTE_BUFFER_SIZE
          Size of the char buffer we keep around for short pieces of data.
static int CHAR_BUFFER_SIZE
          Size of the char buffer we keep around for short pieces of data.
 
Constructor Summary
StringConverter()
           
 
Method Summary
 java.lang.String fromLatin1(byte[] bary)
          Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.
 java.lang.String fromLatin1(byte[] bary, int offset, int len)
          Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.
 java.lang.String fromLatin1(java.nio.ByteBuffer bbuf)
          Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.
 java.lang.String fromLatin1(java.nio.ByteBuffer bbuf, int len)
          Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.
 java.lang.String fromUtf8(byte[] bary)
          Converts a sequence of UTF-8 bytes into a string.
 java.lang.String fromUtf8(byte[] bary, int offset, int len)
          Converts a sequence of UTF-8 bytes into a string.
 java.lang.String fromUtf8(java.nio.ByteBuffer bbuf)
          Converts a sequence of UTF-8 bytes into a string.
 java.lang.String fromUtf8(java.nio.ByteBuffer bbuf, int len)
          Converts a sequence of UTF-8 bytes into a string.
static StringConverter get()
          Factory method for getting a thread-local converter.
 java.nio.ByteBuffer toLatin1(java.lang.String s)
          Converts a string into a sequence of ISO-8859-1 (Latin-1) bytes.
 byte[] toLatin1Bytes(java.lang.String s)
          Converts a string into a sequence of ISO-8859-1 (Latin-1) bytes.
 java.nio.ByteBuffer toUtf8(java.lang.String s)
          Converts a string into a sequence of UTF-8 bytes.
 byte[] toUtf8Bytes(java.lang.String s)
          Converts a string into a sequence of UTF-8 bytes.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CHAR_BUFFER_SIZE

public static final int CHAR_BUFFER_SIZE
Size of the char buffer we keep around for short pieces of data. Since most of the strings we want to convert are fairly short, this buffer can be reused most of the time. Whenever we need a larger buffer, we allocate it on a temporary basis.

See Also:
Constant Field Values

BYTE_BUFFER_SIZE

public static final int BYTE_BUFFER_SIZE
Size of the char buffer we keep around for short pieces of data. Since most of the string we want to convert are fairly short, this buffer can be reused most of the time. This length is four times CHAR_BUFFER_SIZE characters, as 1:4 is the worst-case expansion of characters to bytes.

See Also:
Constant Field Values
Constructor Detail

StringConverter

public StringConverter()
Method Detail

fromLatin1

public java.lang.String fromLatin1(byte[] bary)
Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.

Parameters:
bary - the byte array to convert into a string
Returns:
the decoded string
Throws:
java.lang.NullPointerException - if bary is null

fromLatin1

public java.lang.String fromLatin1(byte[] bary,
                                   int offset,
                                   int len)
Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.

Parameters:
bary - the byte array to convert into a string
offset - the offset into the array of the bytes to translate
len - the length of the data to translate
Returns:
the decoded string
Throws:
java.lang.NullPointerException - if bary is null and len is positive
java.lang.NegativeArraySizeException - if len is negative
java.lang.IndexOutOfBoundsException - if the offset and len values violate the bounds of the array

fromLatin1

public java.lang.String fromLatin1(java.nio.ByteBuffer bbuf)
Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.

Parameters:
bbuf - the byte buffer to convert into a string
Returns:
the decoded string
Throws:
java.lang.NullPointerException - if bbuf is null

fromLatin1

public java.lang.String fromLatin1(java.nio.ByteBuffer bbuf,
                                   int len)
Converts a sequence of ISO-8859-1 (Latin-1) bytes into a string.

Parameters:
bbuf - the byte buffer to convert into a string
len - the length of the data to translate
Returns:
the decoded string
Throws:
java.lang.NullPointerException - if bbuf is null
java.lang.NegativeArraySizeException - if the len value is negative
java.nio.BufferUnderflowException - if the specified len would underflow the buffer

toLatin1

public java.nio.ByteBuffer toLatin1(java.lang.String s)
Converts a string into a sequence of ISO-8859-1 (Latin-1) bytes.

Parameters:
s - the string to convert
Returns:
the ISO-8859-1 (Latin-1) encoding of the string
Throws:
java.lang.NullPointerException - if s is null

toLatin1Bytes

public byte[] toLatin1Bytes(java.lang.String s)
Converts a string into a sequence of ISO-8859-1 (Latin-1) bytes.

Parameters:
s - the string to convert
Returns:
the ISO-8859-1 (Latin-1) encoding of the string
Throws:
java.lang.NullPointerException - if s is null

fromUtf8

public java.lang.String fromUtf8(byte[] bary)
Converts a sequence of UTF-8 bytes into a string.

Parameters:
bary - the array to decode
Returns:
the decoded string

fromUtf8

public java.lang.String fromUtf8(byte[] bary,
                                 int offset,
                                 int len)
Converts a sequence of UTF-8 bytes into a string.

Parameters:
bary - the array to decode
offset - the starting index within the array
len - the number of bytes to decode
Returns:
the decoded string

fromUtf8

public java.lang.String fromUtf8(java.nio.ByteBuffer bbuf,
                                 int len)
Converts a sequence of UTF-8 bytes into a string.

Parameters:
bbuf - the byte buffer to convert into a string
len - the length of the data to translate
Returns:
the decoded string
Throws:
java.lang.NullPointerException - if bbuf is null
java.lang.NegativeArraySizeException - if the len value is negative
java.nio.BufferUnderflowException - if the specified len would underflow the buffer

fromUtf8

public java.lang.String fromUtf8(java.nio.ByteBuffer bbuf)
Converts a sequence of UTF-8 bytes into a string.

Parameters:
bbuf - the byte buffer to convert into a string
Returns:
the decoded string
Throws:
java.lang.NullPointerException - if bbuf is null

toUtf8

public java.nio.ByteBuffer toUtf8(java.lang.String s)
Converts a string into a sequence of UTF-8 bytes.

Parameters:
s - the string to encode
Returns:
the UTF-8 encoding of the string

toUtf8Bytes

public byte[] toUtf8Bytes(java.lang.String s)
Converts a string into a sequence of UTF-8 bytes.

Parameters:
s - the string to encode
Returns:
the UTF-8 encoding of the string

get

public static StringConverter get()
Factory method for getting a thread-local converter.

Returns:
the string converter for this thread