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

Copyright © 2014. All Rights Reserved.