Package org.codice.ddf.libs.klv.data

Class Klv

java.lang.Object
org.codice.ddf.libs.klv.data.Klv
public class Klv extends Object
A public domain class for working with Key-Length-Value (KLV) byte-packing and unpacking. Supports 1-, 2-, 4-byte, and BER-encoded length fields and 1-, 2-, 4-, and 16-byte key fields.

KLV has been used for years as a repeatable, no-guesswork technique for byte-packing data, that is, sending data in a binary format with two bytes for this integer, four bytes for that float, and so forth. KLV is used in broadcast television and is defined in SMPTE 336M-2001, but it also greatly eases the burden of non-TV-related applications for an easy, interchangeable binary format.

The underlying byte array is always king. If you change the key length or the length encoding, you only change how the underlying byte array is interpreted on subsequent calls.

Everything in KLV is Big Endian.

All getValue... methods will return up to the number of bytes specified in the length fields unless there are fewer bytes actually given. In that case, the number of bytes given will be used. This is to make the code more robust for reading corrupted data.

Version:
0.3
Author:
Robert Harder, rharder # users.sourceforge.net

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Klv.KeyLength
    The number of bytes in the key field can be one byte, two bytes, four bytes, or sixteen bytes.
    static enum 
    Klv.LengthEncoding
    The encoding style for the length field can be fixed at one byte, two bytes, four bytes, or variable with Basic Encoding Rules (BER).

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<Klv>
    bytesToList(byte[] bytes, int offset, int length, Klv.KeyLength keyLength, Klv.LengthEncoding lengthEncoding)
    Returns a list of KLV sets in the supplied byte array assuming the provided key length and length field encoding.
    byte[]
    getFullKey()
    Returns a byte array representing the key.
    byte[]
    getValue()
    Returns the value of this KLV set as a copy of the underlying byte array.
    int
    getValueAs16bitSignedInt()
    Returns up to the first two bytes of the value as a 16-bit signed integer.
    int
    getValueAs16bitUnsignedInt()
    Returns up to the first two bytes of the value as a 16-bit unsigned integer.
    int
    getValueAs32bitInt()
    Returns up to the first four bytes of the value as a 32-bit int.
    long
    getValueAs64bitLong()
    Returns up to the first eight bytes of the value as a 64-bit signed long.
    int
    getValueAs8bitSignedInt()
    Returns up to the first byte of the value as an 8-bit signed integer.
    int
    getValueAs8bitUnsignedInt()
    Returns up to the first byte of the value as an 8-bit unsigned integer.
    double
    getValueAsDouble()
    Returns the first eight bytes of the value as a double according to IEEE 754 byte packing.
    float
    getValueAsFloat()
    Returns the first four bytes of the value as a float according to IEEE 754 byte packing.
    String
    getValueAsString(String charsetName)
    Return the value as a String interpreted with the given encoding.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • getFullKey

      public byte[] getFullKey()
      Returns a byte array representing the key. This is a copy of the bytes from the original byte set.
      Returns:
      the key

    • getValue

      public byte[] getValue()
      Returns the value of this KLV set as a copy of the underlying byte array.
      Returns:
      the value

    • getValueAs8bitSignedInt

      public int getValueAs8bitSignedInt()
      Returns up to the first byte of the value as an 8-bit signed integer.
      Returns:
      the value as an 8-bit signed integer

    • getValueAs8bitUnsignedInt

      public int getValueAs8bitUnsignedInt()
      Returns up to the first byte of the value as an 8-bit unsigned integer.
      Returns:
      the value as an 8-bit unsigned integer

    • getValueAs16bitSignedInt

      public int getValueAs16bitSignedInt()
      Returns up to the first two bytes of the value as a 16-bit signed integer.
      Returns:
      the value as a 16-bit signed integer

    • getValueAs16bitUnsignedInt

      public int getValueAs16bitUnsignedInt()
      Returns up to the first two bytes of the value as a 16-bit unsigned integer.
      Returns:
      the value as a 16-bit unsigned integer

    • getValueAs32bitInt

      public int getValueAs32bitInt()
      Returns up to the first four bytes of the value as a 32-bit int. Since all Java ints are signed, there is no signed/unsigned option. If you need a 32-bit unsigned int, try getValueAs64bitLong().
      Returns:
      the value as an int

    • getValueAs64bitLong

      public long getValueAs64bitLong()
      Returns up to the first eight bytes of the value as a 64-bit signed long. Note if you expect a 32-bit unsigned int, and since Java doesn't have such a thing, you could return a long instead and get the proper effect.
      Returns:
      the value as a long

    • getValueAsFloat

      public float getValueAsFloat()
      Returns the first four bytes of the value as a float according to IEEE 754 byte packing. See Java's Float class for details. This method calls Float.intBitsToFloat with getValueAs32bitInt() as the argument. However it does check to see that the value has at least four bytes. If it does not, then Float.NaN is returned.
      Returns:
      the value as a float

    • getValueAsDouble

      public double getValueAsDouble()
      Returns the first eight bytes of the value as a double according to IEEE 754 byte packing. See Java's Double class for details. This method calls Double.longBitsToDouble with getValueAs64bitLong() as the argument. However it does check to see that the value has at least eight bytes. If it does not, then Double.NaN is returned.
      Returns:
      the value as a double

    • getValueAsString

      public String getValueAsString(String charsetName) throws UnsupportedEncodingException
      Return the value as a String interpreted with the given encoding.
      Parameters:
      charsetName - the character encoding
      Returns:
      value as String
      Throws:
      UnsupportedEncodingException - if the String value cannot be interpreted using the given encoding

    • bytesToList

      public static List<Klv> bytesToList(byte[] bytes, int offset, int length, Klv.KeyLength keyLength, Klv.LengthEncoding lengthEncoding)
      Returns a list of KLV sets in the supplied byte array assuming the provided key length and length field encoding.
      Parameters:
      bytes - The byte array to parse
      offset - Where to start parsing
      length - How many bytes to parse
      keyLength - Length of keys assumed in the KLV sets
      lengthEncoding - Flag indicating encoding type
      Returns:
      List of KLVs