com.h3c.util.codec

Class CodecUtils

java.lang.Object

com.h3c.util.codec.CodecUtils

public final class CodecUtils
extends Object

This class defines methods to assist in the encodement and decodement of objects to strings and back.

Although it would be preferable to hide the implementation details of how string arrays (and lists) are encoded, we have determined cases where it is important for the consumer to be able to make assumptions about the delimiters used. Therefore, a brief description of the algorithm is given here:

The method encodeStringArray (and its counterpart, encodeStringList which simply delegates to this method), examines the strings in the array and attempts to find a delimiter which does not occur in the data. If one can be found, that one is used, avoiding the need to escape occurrences of the delimiter in the data. If all considered delimiters are found in the data, then a deeper examination is made and the one that occurs the least number of times is used, and escaped as appropriate.

If the caller knows that the string data does not contain the default delimiter, then the assumption can be made that this will be the delimiter used.

Method Summary

Methods

Modifier and Type	Method and Description
static Object	decodePrimitive(String encoded) This method accepts an encoded string (previously generated from encodePrimitive) and returns the original value (as the original type).
static String[]	decodeStringArray(String encoded) This method takes a string generated by encodeStringArray and regenerates the contents of the original array.
static List<String>	decodeStringList(String encoded) This method takes a string generated by encodeStringList and regenerates the contents of the original list.
static String	encodePrimitive(Object p) This method accepts a primitive and produces a string encoding of it.
static String	encodeStringArray(String[] strings) This method takes an array of strings and returns a single string that encodes that string array.
static String	encodeStringList(List<String> strings) This method takes a list of strings and returns a single string that encodes that list.
static String	getDefaultDelimiter() Returns the default delimiter used when encoding string arrays and lists.
static String	getMagic() Returns the magic value used to tag encoded string arrays and lists.

Methods inherited from class java.lang.Object

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

Method Detail

getDefaultDelimiter

public static String getDefaultDelimiter()

Returns the default delimiter used when encoding string arrays and lists.

Returns:

the default delimiter

encodeStringList

public static String encodeStringList(List<String> strings)

This method takes a list of strings and returns a single string that encodes that list. This method converts the list to an array then delegates the call to encodeStringArray.

Note that any null elements in the list will be silently converted to empty strings.

Parameters:

strings - a list of strings

Returns:

a single string representing the specified list of strings

Throws:

NullPointerException - if the parameter is null

encodeStringArray

public static String encodeStringArray(String[] strings)

This method takes an array of strings and returns a single string that encodes that string array. The original array can be regenerated by passing the encoded string to decodeStringArray.

Note that any null elements in the array will be silently converted to empty strings.

Parameters:

strings - an array of strings

Returns:

a single string encodement of the array of strings

Throws:

NullPointerException - if the parameter is null

decodeStringList

public static List<String> decodeStringList(String encoded)

This method takes a string generated by encodeStringList and regenerates the contents of the original list. This method calls decodeStringArray then converts that array back to a list before returning it.

Parameters:

encoded - the encoded string

Returns:

the reconstituted list of strings

Throws:

NullPointerException - if the parameter is null

IllegalArgumentException - if the format of the string is not recognized

decodeStringArray

public static String[] decodeStringArray(String encoded)

This method takes a string generated by encodeStringArray and regenerates the contents of the original array.

Parameters:

encoded - the encoded string

Returns:

the reconstituted array of strings

Throws:

NullPointerException - if the parameter is null

IllegalArgumentException - if the format of the string is not recognized

getMagic

public static String getMagic()

Returns the magic value used to tag encoded string arrays and lists. The following assertion may be made:

 String[] myStrings = ...
 String encArray = CodecUtils.encodeStringArray(myStrings);
 assert encArray.startsWith(CodecUtils.getMagic());
 

Returns:

the magic value

encodePrimitive

public static String encodePrimitive(Object p)

This method accepts a primitive and produces a string encoding of it. This encoding can be parsed by decodePrimitive to restore the original value (as the original type).

As a convenience, a String is also considered a "primitive" and can be "encoded" by this method.

Parameters:

p - the primitive value

Returns:

a string encoding of the value

Throws:

NullPointerException - if the parameter is null

IllegalArgumentException - if the parameter is not a String, Boolean, Character, Byte, Short, Integer, Long, Float, or Double

decodePrimitive

public static Object decodePrimitive(String encoded)

This method accepts an encoded string (previously generated from encodePrimitive) and returns the original value (as the original type).

Parameters:

encoded - the encoded string

Returns:

the (wrapped) primitive value that the encoded string represents

Throws:

NullPointerException - if the parameter is null

IllegalArgumentException - if the encoding is not recognized