Java tutorial
/** * Copyright (c) Codice Foundation * <p> * This is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser * General Public License as published by the Free Software Foundation, either version 3 of the * License, or any later version. * <p> * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. A copy of the GNU Lesser General Public License * is distributed along with this program and can be found at * <http://www.gnu.org/licenses/lgpl.html>. */ package org.codice.ddf.libs.klv.data; import java.io.UnsupportedEncodingException; import java.util.Arrays; import java.util.LinkedList; import java.util.List; import com.google.common.base.Preconditions; /** * 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. * <p> * 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. * <p> * 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. * <p> * Everything in KLV is Big Endian. * <p> * All <tt>getValue...</tt> 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. * * @author Robert Harder * @author rharder # users.sourceforge.net * @version 0.3 */ public class Klv { /** * The encoding style for the length field can be fixed at * one byte, two bytes, four bytes, or variable with * Basic Encoding Rules (BER). */ public enum LengthEncoding { OneByte(1), TwoBytes(2), FourBytes(4), BER(5); // Max bytes a BER field could take up private int value; LengthEncoding(int value) { this.value = value; } /** * Returns the number of bytes used to encode length, * or zero if encoding is <code>BER</code> */ public int value() { return this.value; } } /** * The number of bytes in the key field can be * one byte, two bytes, four bytes, or sixteen bytes. */ public enum KeyLength { OneByte(1), TwoBytes(2), FourBytes(4), SixteenBytes(16); private int value; KeyLength(int value) { this.value = value; } /** * Returns the number of bytes used in the key. */ public int value() { return this.value; } } /** * Number of bytes in key. */ private KeyLength keyLength; /** * The key if the key length is greater than four bytes. */ private byte[] keyIfLong; /** * The key if the key length is four bytes or fewer. */ private int keyIfShort; /** * The bytes from which the KLV set is made up. * May include irrelevant bytes so that byte arrays * with offset and length specified separately so arrays * can be passed around with a minimum of copying. */ private byte[] value; /** * When instantiated by reading a byte array, this private * field will record the offset of the next byte in the array * where perhaps another KLV set begins. This is used by the * {@link #bytesToList} method to create a list of KLV sets * from a long byte array. */ private int offsetAfterInstantiation; /** * Creates a KLV set from the given byte array, the given offset in that array, * the total length of the KLV set in the byte array, the specified key length, * and the specified length field encoding. * <p> * If there are not as many bytes in the array as the length field * suggests, as many bytes as possible will be stored as the value, and * the length field will reflect the actual length. * * @param theBytes The bytes that make up the entire KLV set * @param offset The offset from beginning of theBytes * @param keyLength The number of bytes in the key. * @param lengthEncoding The length field encoding type. * @throws IndexOutOfBoundsException If offset is out of range of the byte array. */ private Klv(final byte[] theBytes, final int offset, final KeyLength keyLength, final LengthEncoding lengthEncoding) { Preconditions.checkElementIndex(offset, theBytes.length, String.format("Offset %d is out of range (byte array length: %d).", offset, theBytes.length)); // These methods will interpret the byte array // and set the appropriate key length and length encoding flags. // setLength returns the offset of where the length field ends // and the value portion begins. It also initializes an array in // this.value of the appropriate length. setKey(theBytes, offset, keyLength); // Set length and verify enough bytes exist // setLength(..) also establishes a this.value array. final int valueOffset = setLength(theBytes, offset + keyLength.value(), lengthEncoding); final int remaining = theBytes.length - valueOffset; checkEnoughBytesRemaining(remaining, this.value.length, String.format( "Not enough bytes left in array (%d) for the declared length (%d).", remaining, this.value.length)); System.arraycopy(theBytes, valueOffset, this.value, 0, this.value.length); // Private field used when creating a list of KLVs from a long array. this.offsetAfterInstantiation = valueOffset + this.value.length; } /** * Returns a byte array representing the key. This is a copy of the bytes * from the original byte set. * * @return the key */ public byte[] getFullKey() { final int length = this.keyLength.value; final byte[] key = new byte[length]; switch (this.keyLength) { case OneByte: key[0] = (byte) this.keyIfShort; break; case TwoBytes: key[0] = (byte) (this.keyIfShort >> 8); key[1] = (byte) this.keyIfShort; break; case FourBytes: key[0] = (byte) (this.keyIfShort >> 24); key[1] = (byte) (this.keyIfShort >> 16); key[2] = (byte) (this.keyIfShort >> 8); key[3] = (byte) this.keyIfShort; break; case SixteenBytes: System.arraycopy(this.keyIfLong, 0, key, 0, 16); break; } return key; } /** * Returns the value of this KLV set as a copy of the underlying byte array. * * @return the value */ public byte[] getValue() { return Arrays.copyOf(this.value, this.value.length); } /** * Returns up to the first byte of the value as an 8-bit signed integer. * * @return the value as an 8-bit signed integer */ public int getValueAs8bitSignedInt() { final byte[] bytes = getValue(); byte value = 0; if (bytes.length > 0) { value = bytes[0]; } return value; } /** * Returns up to the first byte of the value as an 8-bit unsigned integer. * * @return the value as an 8-bit unsigned integer */ public int getValueAs8bitUnsignedInt() { final byte[] bytes = getValue(); int value = 0; if (bytes.length > 0) { value = bytes[0] & 0xFF; } return value; } /** * Returns up to the first two bytes of the value as a 16-bit signed integer. * * @return the value as a 16-bit signed integer */ public int getValueAs16bitSignedInt() { final byte[] bytes = getValue(); final int length = bytes.length; final int shortLen = length < 2 ? length : 2; short value = 0; for (int i = 0; i < shortLen; i++) { value |= (bytes[i] & 0xFF) << (shortLen * 8 - i * 8 - 8); } return value; } /** * Returns up to the first two bytes of the value as a 16-bit unsigned integer. * * @return the value as a 16-bit unsigned integer */ public int getValueAs16bitUnsignedInt() { final byte[] bytes = getValue(); final int length = bytes.length; final int shortLen = length < 2 ? length : 2; int value = 0; for (int i = 0; i < shortLen; i++) { value |= (bytes[i] & 0xFF) << (shortLen * 8 - i * 8 - 8); } return value; } /** * 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 {@link #getValueAs64bitLong}. * * @return the value as an int */ public int getValueAs32bitInt() { final byte[] bytes = getValue(); final int length = bytes.length; final int shortLen = length < 4 ? length : 4; int value = 0; for (int i = 0; i < shortLen; i++) { value |= (bytes[i] & 0xFF) << (shortLen * 8 - i * 8 - 8); } return value; } /** * Returns up to the first eight bytes of the value as a 64-bit signed long. * Note if you expect a 32-bit <b>unsigned</b> int, and since Java doesn't * have such a thing, you could return a long instead and get the proper effect. * * @return the value as a long */ public long getValueAs64bitLong() { final byte[] bytes = getValue(); final int length = bytes.length; final int shortLen = length < 8 ? length : 8; long value = 0; for (int i = 0; i < shortLen; i++) { value |= (long) (bytes[i] & 0xFF) << (shortLen * 8 - i * 8 - 8); } return value; } /** * 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 <code>Float.intBitsToFloat</code> with * {@link #getValueAs32bitInt} as the argument. However it does check * to see that the value has at least four bytes. If it does not, * then <tt>Float.NaN</tt> is returned. * * @return the value as a float */ public float getValueAsFloat() { return this.getValue().length < 4 ? Float.NaN : Float.intBitsToFloat(getValueAs32bitInt()); } /** * 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 <code>Double.longBitsToDouble</code> with * {@link #getValueAs64bitLong} as the argument. However it does check * to see that the value has at least eight bytes. If it does not, * then <tt>Double.NaN</tt> is returned. * * @return the value as a double */ public double getValueAsDouble() { return this.getValue().length < 8 ? Double.NaN : Double.longBitsToDouble(getValueAs64bitLong()); } /** * Return the value as a String interpreted with the given encoding. * * @param charsetName the character encoding * @return value as String * @throws UnsupportedEncodingException if the String value cannot be interpreted using the * given encoding */ public String getValueAsString(final String charsetName) throws UnsupportedEncodingException { return new String(getValue(), charsetName); } /** * Sets the key according to the key found in the byte array * and of the given length. If <tt>keyLength</tt> is different * than what was previously set for this KLV, then this KLV's * key length parameter will be updated. * * @param inTheseBytes The byte array containing the key (and other stuff) * @param offset The offset where to look for the key * @param keyLength The length of the key * @return <tt>this</tt> to aid in stringing together commands * @throws IndexOutOfBoundsException If offset is invalid */ private Klv setKey(final byte[] inTheseBytes, final int offset, final KeyLength keyLength) { Preconditions.checkElementIndex(offset, inTheseBytes.length, String.format("Offset %d is out of range (byte array length: %d).", offset, inTheseBytes.length)); final int remaining = inTheseBytes.length - offset; checkEnoughBytesRemaining(remaining, keyLength.value(), String.format("Not enough bytes for %d-byte key.", keyLength.value())); // Set key according to length of key this.keyLength = keyLength; switch (keyLength) { case OneByte: this.keyIfShort = inTheseBytes[offset] & 0xFF; this.keyIfLong = null; break; case TwoBytes: this.keyIfShort = (inTheseBytes[offset] & 0xFF) << 8; this.keyIfShort |= inTheseBytes[offset + 1] & 0xFF; this.keyIfLong = null; break; case FourBytes: this.keyIfShort = (inTheseBytes[offset] & 0xFF) << 24; this.keyIfShort |= (inTheseBytes[offset + 1] & 0xFF) << 16; this.keyIfShort |= (inTheseBytes[offset + 2] & 0xFF) << 8; this.keyIfShort |= inTheseBytes[offset + 3] & 0xFF; this.keyIfLong = null; break; case SixteenBytes: this.keyIfLong = new byte[16]; System.arraycopy(inTheseBytes, offset, this.keyIfLong, 0, 16); this.keyIfShort = 0; break; } return this; } /** * Sets the length according to the length found in the byte array * and of the given length encoding. * If <tt>lengthEncoding</tt> is different * than what was previously set for this KLV, then this KLV's * length encoding parameter will be updated. * An array of the appropriate length will be initialized. * * @param inTheseBytes The byte array containing the key (and other stuff) * @param offset The offset where to look for the key * @param lengthEncoding The length of the key * @return Offset where value field would begin after length * @throws IndexOutOfBoundsException If offset is invalid */ private int setLength(final byte[] inTheseBytes, final int offset, final LengthEncoding lengthEncoding) { Preconditions.checkElementIndex(offset, inTheseBytes.length, String.format("Offset %d is out of range (byte array length: %d).", offset, inTheseBytes.length)); int length = 0; int valueOffset = 0; final int remaining = inTheseBytes.length - offset; final String lengthEncodingErrorMessage = String.format("Not enough bytes for %s length encoding.", lengthEncoding); switch (lengthEncoding) { case OneByte: checkEnoughBytesRemaining(remaining, 1, lengthEncodingErrorMessage); length = inTheseBytes[offset] & 0xFF; setLength(length, lengthEncoding); valueOffset = offset + 1; break; case TwoBytes: checkEnoughBytesRemaining(remaining, 2, lengthEncodingErrorMessage); length = (inTheseBytes[offset] & 0xFF) << 8; length |= inTheseBytes[offset + 1] & 0xFF; setLength(length, lengthEncoding); valueOffset = offset + 2; break; case FourBytes: checkEnoughBytesRemaining(remaining, 4, lengthEncodingErrorMessage); length = (inTheseBytes[offset] & 0xFF) << 24; length |= (inTheseBytes[offset + 1] & 0xFF) << 16; length |= (inTheseBytes[offset + 2] & 0xFF) << 8; length |= inTheseBytes[offset + 3] & 0xFF; setLength(length, lengthEncoding); valueOffset = offset + 4; break; case BER: // Short BER form: If high bit is not set, then // use the byte to determine length of payload. // Long BER form: If high bit is set (0x80), // then use low seven bits to determine how many // bytes that follow are themselves an unsigned // integer specifying the length of the payload. // Using more than four bytes to specify the length // is not supported in this code, though it's not // exactly illegal KLV notation either. checkEnoughBytesRemaining(remaining, 1, lengthEncodingErrorMessage); final int ber = inTheseBytes[offset] & 0xFF; // Easy case: low seven bits is length if ((ber & 0x80) == 0) { setLength(ber, lengthEncoding); valueOffset = offset + 1; } else { final int following = ber & 0x7F; // Low seven bits checkEnoughBytesRemaining(remaining, following + 1, lengthEncodingErrorMessage); for (int i = 0; i < following; i++) { length |= (inTheseBytes[offset + 1 + i] & 0xFF) << (following - 1 - i) * 8; } setLength(length, lengthEncoding); valueOffset = offset + 1 + following; } break; } return valueOffset; } /** * Sets the length of the value, copying or truncating the old value * as appropriate for the new length. * * @param length The new number of bytes in the Value * @param lengthEncoding The length encoding to use * @return <tt>this</tt> to aid in stringing commands together */ private Klv setLength(final int length, final LengthEncoding lengthEncoding) { // Copy old value final byte[] bytes = new byte[length]; if (this.value != null) { System.arraycopy(value, 0, bytes, 0, Math.min(length, this.value.length)); } this.value = bytes; return this; } /** * Returns a list of KLV sets in the supplied byte array * assuming the provided key length and length field encoding. * * @param bytes The byte array to parse * @param offset Where to start parsing * @param length How many bytes to parse * @param keyLength Length of keys assumed in the KLV sets * @param lengthEncoding Flag indicating encoding type * @return List of KLVs */ public static List<Klv> bytesToList(final byte[] bytes, final int offset, final int length, final KeyLength keyLength, LengthEncoding lengthEncoding) { final List<Klv> list = new LinkedList<>(); int currentPos = offset; while (currentPos < offset + length) { final Klv klv = new Klv(bytes, currentPos, keyLength, lengthEncoding); currentPos = klv.offsetAfterInstantiation; list.add(klv); } return list; } private void checkEnoughBytesRemaining(final int actualNumberOfBytesRemaining, final int minimumExpectedNumberOfBytesRemaining, final String message) { if (actualNumberOfBytesRemaining < minimumExpectedNumberOfBytesRemaining) { throw new IndexOutOfBoundsException(message); } } }