net.named_data.jndn.encoding.tlv

Class TlvDecoder

java.lang.Object

net.named_data.jndn.encoding.tlv.TlvDecoder

public class TlvDecoder
extends Object

A TlvDecoder has methods to decode an input according to NDN-TLV.

Constructor Summary

Constructors

Constructor and Description
TlvDecoder(ByteBuffer input) Create a new TlvDecoder to decode the input.

Method Summary

Methods

Modifier and Type	Method and Description
void	finishNestedTlvs(int endOffset) Call this after reading all nested TLVs to skip any remaining unrecognized TLVs and to check if the input buffer position after the final nested TLV matches the endOffset returned by readNestedTlvsStart.
int	getOffset() Get the input buffer position (offset), used for the next read.
ByteBuffer	getSlice(int beginOffset, int endOffset) Return a ByteBuffer slice of the input for the given offset range.
boolean	peekType(int expectedType, int endOffset) Decode the type from the input starting at the input buffer position, and if it is the expectedType, then return true, else false.
ByteBuffer	readBlobTlv(int expectedType) Decode the type and length from the input starting at the input buffer position, expecting the type to be expectedType.
boolean	readBooleanTlv(int expectedType, int endOffset) Peek at the next TLV, and if it has the expectedType then read a type and value, ignoring the value, and return true.
int	readExtendedVarNumber(int firstOctet) Do the work of readVarNumber, given the firstOctet which is greater than or equal to 253.
int	readNestedTlvsStart(int expectedType) Decode the type and length from the input starting at the input buffer position, expecting the type to be expectedType.
long	readNonNegativeInteger(int length) Decode a non-negative integer in NDN-TLV and return it.
long	readNonNegativeIntegerTlv(int expectedType) Decode the type and length from the input starting at the input buffer position, expecting the type to be expectedType.
ByteBuffer	readOptionalBlobTlv(int expectedType, int endOffset) Peek at the next TLV, and if it has the expectedType then call readBlobTlv and return the value.
long	readOptionalNonNegativeIntegerTlv(int expectedType, int endOffset) Peek at the next TLV, and if it has the expectedType then call readNonNegativeIntegerTlv and return the integer.
int	readTypeAndLength(int expectedType) Decode the type and length from this's input starting at the input buffer position, expecting the type to be expectedType and return the length.
int	readVarNumber() Decode a VAR-NUMBER in NDN-TLV and return it.
void	seek(int offset) Set the offset into the input, used for the next read.

Methods inherited from class java.lang.Object

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

Constructor Detail

TlvDecoder

public TlvDecoder(ByteBuffer input)

Create a new TlvDecoder to decode the input.

Parameters:

input - The input ByteBuffer whose position and limit are set to the desired bytes to decode. This calls input.duplicate(), but does not copy the underlying buffer whose contents must remain valid during the life of this object.

Method Detail

readVarNumber

public final int readVarNumber()
                        throws EncodingException

Decode a VAR-NUMBER in NDN-TLV and return it. Update the input buffer position.

Returns:

The decoded VAR-NUMBER as a Java 32-bit int.

Throws:

EncodingException - if the VAR-NUMBER is 64-bit or read past the end of the input.

readExtendedVarNumber

public final int readExtendedVarNumber(int firstOctet)
                                throws EncodingException

Do the work of readVarNumber, given the firstOctet which is greater than or equal to 253. Update the input buffer position.

Parameters:

firstOctet - The first octet which is greater than or equal to 253, used to decode the remaining bytes.

Returns:

The decoded VAR-NUMBER as a Java 32-bit int.

Throws:

EncodingException - if the VAR-NUMBER is 64-bit or read past the end of the input.

readTypeAndLength

public final int readTypeAndLength(int expectedType)
                            throws EncodingException

Decode the type and length from this's input starting at the input buffer position, expecting the type to be expectedType and return the length. Update the input buffer position. Also make sure the decoded length does not exceed the number of bytes remaining in the input.

Parameters:

expectedType - The expected type as a 32-bit Java int.

Returns:

The length of the TLV as a 32-bit Java int.

Throws:

EncodingException - if did not get the expected TLV type, or the TLV length exceeds the buffer length, or the type is encoded as a 64-bit value, or the length is encoded as a 64-bit value.

readNestedTlvsStart

public final int readNestedTlvsStart(int expectedType)
                              throws EncodingException

Decode the type and length from the input starting at the input buffer position, expecting the type to be expectedType. Update the input buffer position. Also make sure the decoded length does not exceed the number of bytes remaining in the input. Return the input buffer position (offset) of the end of this parent TLV, which is used in decoding optional nested TLVs. After reading all nested TLVs, you should call finishNestedTlvs.

Parameters:

expectedType - The expected type as a 32-bit Java int.

Returns:

The input buffer position (offset) of the end of the parent TLV.

Throws:

EncodingException - if did not get the expected TLV type, or the TLV length exceeds the buffer length, or the type is encoded as a 64-bit value, or the length is encoded as a 64-bit value.

finishNestedTlvs

public final void finishNestedTlvs(int endOffset)
                            throws EncodingException

Call this after reading all nested TLVs to skip any remaining unrecognized TLVs and to check if the input buffer position after the final nested TLV matches the endOffset returned by readNestedTlvsStart. Update the input buffer position as needed if skipping TLVs.

Parameters:

endOffset - The offset of the end of the parent TLV, returned by readNestedTlvsStart.

Throws:

EncodingException - if the TLV length does not equal the total length of the nested TLVs.

peekType

public final boolean peekType(int expectedType,
               int endOffset)
                       throws EncodingException

Decode the type from the input starting at the input buffer position, and if it is the expectedType, then return true, else false. However, if the input buffer position is greater than or equal to endOffset, then return false and don't try to read the type. Do not update the input buffer position.

Parameters:

expectedType - The expected type as a 32-bit Java int.

endOffset - The offset of the end of the parent TLV, returned by readNestedTlvsStart.

Returns:

true if the type of the next TLV is the expectedType, otherwise false.

Throws:

EncodingException

readNonNegativeInteger

public final long readNonNegativeInteger(int length)
                                  throws EncodingException

Decode a non-negative integer in NDN-TLV and return it. Update the input buffer position by length.

Parameters:

length - The number of bytes in the encoded integer.

Returns:

The integer as a Java 64-bit long.

Throws:

EncodingException - if length is an invalid length for a TLV non-negative integer or read past the end of the input.

readNonNegativeIntegerTlv

public final long readNonNegativeIntegerTlv(int expectedType)
                                     throws EncodingException

Decode the type and length from the input starting at the input buffer position, expecting the type to be expectedType. Then decode a non-negative integer in NDN-TLV and return it. Update the input buffer position.

Parameters:

expectedType - The expected type as a 32-bit Java int.

Returns:

The integer as a Java 64-bit long.

Throws:

EncodingException - if did not get the expected TLV type or can't decode the value.

readOptionalNonNegativeIntegerTlv

public final long readOptionalNonNegativeIntegerTlv(int expectedType,
                                     int endOffset)
                                             throws EncodingException

Peek at the next TLV, and if it has the expectedType then call readNonNegativeIntegerTlv and return the integer. Otherwise, return -1. However, if the input buffer position is greater than or equal to endOffset, then return -1 and don't try to read the type.

Parameters:

expectedType - The expected type as a 32-bit Java int.

endOffset - The offset of the end of the parent TLV, returned by readNestedTlvsStart.

Returns:

The integer as a Java 64-bit long or -1 if the next TLV doesn't have the expected type.

Throws:

EncodingException

readBlobTlv

public final ByteBuffer readBlobTlv(int expectedType)
                             throws EncodingException

Decode the type and length from the input starting at the input buffer position, expecting the type to be expectedType. Then return a ByteBuffer of the bytes in the value. Update the input buffer position.

Parameters:

expectedType - The expected type as a 32-bit Java int.

Returns:

The bytes in the value as a slice on the input buffer. This is not a copy of the bytes in the input buffer. If you need a copy, then you must make a copy of the return value.

Throws:

EncodingException - if did not get the expected TLV type.

readOptionalBlobTlv

public final ByteBuffer readOptionalBlobTlv(int expectedType,
                             int endOffset)
                                     throws EncodingException

Peek at the next TLV, and if it has the expectedType then call readBlobTlv and return the value. Otherwise, return null. However, if the input buffer position is greater than or equal to endOffset, then return null and don't try to read the type.

Parameters:

expectedType - The expected type as a 32-bit Java int.

endOffset - The offset of the end of the parent TLV, returned by readNestedTlvsStart.

Returns:

The bytes in the value as a slice on the input buffer or null if the next TLV doesn't have the expected type. This is not a copy of the bytes in the input buffer. If you need a copy, then you must make a copy of the return value.

Throws:

EncodingException

readBooleanTlv

public final boolean readBooleanTlv(int expectedType,
                     int endOffset)
                             throws EncodingException

Peek at the next TLV, and if it has the expectedType then read a type and value, ignoring the value, and return true. Otherwise, return false. However, if the input buffer position is greater than or equal to endOffset, then return false and don't try to read the type and value.

Parameters:

expectedType - The expected type as a 32-bit Java int.

endOffset - The offset of the end of the parent TLV, returned by readNestedTlvsStart.

Returns:

true, or else false if the next TLV doesn't have the expected type.

Throws:

EncodingException

getOffset

public final int getOffset()

Get the input buffer position (offset), used for the next read.

Returns:

The input buffer position (offset).

seek

public final void seek(int offset)

Set the offset into the input, used for the next read.

Parameters:

offset - The new offset.

getSlice

public final ByteBuffer getSlice(int beginOffset,
                  int endOffset)

Return a ByteBuffer slice of the input for the given offset range.

Parameters:

beginOffset - The offset in the input of the beginning of the slice.

endOffset - The offset in the input of the end of the slice.

Returns:

A slice on the input buffer. This is not a copy of the bytes in the input buffer. If you need a copy, then you must make a copy of the return value.