net.kano.joscar.tlv
Class AbstractTlvChain

java.lang.Object
  AbstractTlvChain

All Implemented Interfaces:

LiveWritable, TlvChain, Writable

Direct Known Subclasses:

DefaultMutableTlvChain, ImmutableTlvChain

public abstract class AbstractTlvChain

extends java.lang.Object

implements TlvChain

A base class for TLV chains, implementing basic functionality while leaving extra features and data storage to subclasses.

Extending this class requires one to hold both a list of all contained TLV's as well as a map from TLV type to TLV's in the chain with that type. See getTlvList() and getTlvMap() for details.

Constructor Summary

protected	AbstractTlvChain() Creates a new TLV chain with a total size of -1.
protected	AbstractTlvChain(int totalSize) Creates a new TLV chain with the given total byte size, as read from an incoming stream.

Method Summary

protected void	addTlvImpl(Tlv tlv) Adds a TLV to this chain.
protected void	copy(TlvChain chain) Effectively makes this chain a copy of the given chain.
protected java.util.List	createSiblingList() Creates a new List to serve as a value for the TLV map.
Tlv	getFirstTlv(int type) Returns the first TLV in this chain with the given type, or null of TLV of the given type is present.
Tlv	getLastTlv(int type) Returns the last TLV in this chain with the given type, or null of TLV of the given type is present.
java.lang.String	getString(int type) Returns the ASCII string contained in the last TLV in this chain with the given type, or null if no TLV with the given type is present in this chain.
java.lang.String	getString(int type, java.lang.String charset) Returns the string contained in the last TLV in this chain with the given type, decoded with the given charset, or null if no TLV with the given type is present in this chain.
int	getTlvCount() Returns the number of TLV's in this chain.
protected abstract java.util.List	getTlvList() Returns a list of all of the TLV's in this chain.
protected abstract java.util.Map	getTlvMap() Returns a map from TLV types (as Integers) to TLV lists (as Lists).
Tlv[]	getTlvs() Returns an array of all TLV's in this chain, in order.
Tlv[]	getTlvs(int type) Returns an array containing all TLV's in this chain with the given TLV type, with original order preserved.
int	getTotalSize() Returns the total size, in bytes, of this chain, as read from an incoming stream.
long	getUInt(int type) Returns an unsigned four-byte integer read from the value of the last TLV of the given type in this chain, or -1 if either no TLV of the given type is present in this chain or if the data block for the TLV contains fewer than two bytes.
int	getUShort(int type) Returns an unsigned two-byte integer read from the value of the last TLV of the given type in this chain, or -1 if either no TLV of the given type is present in this chain or if the data block for the TLV contains fewer than two bytes.
long	getWritableLength() Returns the length of the data that was or will be written in a call to write.
boolean	hasTlv(int type) Returns true if this TLV chain contains any TLV's of the given TLV type.
protected void	initFromBlock(ByteBlock block, int maxTlvs) Copies the given number of TLV's from the given block of TLV's into this chain.
java.util.Iterator	iterator() Returns an iterator over the TLV's in this TLV chain.
java.lang.String	toString()
void	write(java.io.OutputStream out) Writes a representation of this object to the given stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractTlvChain

protected AbstractTlvChain()

Creates a new TLV chain with a total size of -1.

AbstractTlvChain

protected AbstractTlvChain(int totalSize)

Creates a new TLV chain with the given total byte size, as read from an incoming stream.

Parameters:

totalSize - the total size of this object, in bytes, or -1 if this object was not read from a block of binary data

Method Detail

copy

protected final void copy(TlvChain chain)

Effectively makes this chain a copy of the given chain.

Parameters:

chain - a TLV chain to copy

initFromBlock

protected final void initFromBlock(ByteBlock block,
                                   int maxTlvs)

Copies the given number of TLV's from the given block of TLV's into this chain.

Parameters:

block - a data block containing zero or more TLV's

maxTlvs - the maximum number of TLV's to read, or -1 to read all possible TLV's in the given block

addTlvImpl

protected void addTlvImpl(Tlv tlv)

Adds a TLV to this chain. Presumably for use by mutable subclasses.

Parameters:

tlv - a TLV to add to this chain

hasTlv

public boolean hasTlv(int type)

Description copied from interface: TlvChain

Returns true if this TLV chain contains any TLV's of the given TLV type.

Specified by:

hasTlv in interface TlvChain

Parameters:

type - a TLV type

Returns:

whether or not this chain contains one or more TLV's of the given type

getTlvs

public Tlv[] getTlvs()

Description copied from interface: TlvChain

Returns an array of all TLV's in this chain, in order.

Specified by:

getTlvs in interface TlvChain

Returns:

all of this chain's TLV's

iterator

public java.util.Iterator iterator()

Description copied from interface: TlvChain

Returns an iterator over the TLV's in this TLV chain.

Specified by:

iterator in interface TlvChain

Returns:

an iterator traversing over the TLV's in this chain

getTlvCount

public int getTlvCount()

Description copied from interface: TlvChain

Returns the number of TLV's in this chain.

Specified by:

getTlvCount in interface TlvChain

Returns:

the number of TLV's in this chain

getFirstTlv

public Tlv getFirstTlv(int type)

Description copied from interface: TlvChain

Returns the first TLV in this chain with the given type, or null of TLV of the given type is present.

Specified by:

getFirstTlv in interface TlvChain

Parameters:

type - the type of TLV whose first match will be returned

Returns:

the first TLV in this chain with the given type, or null if none was found

getLastTlv

public Tlv getLastTlv(int type)

Description copied from interface: TlvChain

Returns the last TLV in this chain with the given type, or null of TLV of the given type is present.

Specified by:

getLastTlv in interface TlvChain

Parameters:

type - the type of TLV whose last match will be returned

Returns:

the last TLV in this chain with the given type, or null if none was found

getTlvs

public Tlv[] getTlvs(int type)

Description copied from interface: TlvChain

Returns an array containing all TLV's in this chain with the given TLV type, with original order preserved. Note that if there are no matches this will return a zero-length array and not null.

Specified by:

getTlvs in interface TlvChain

Parameters:

type - the type of TLV whose matching TLV's will be returned

Returns:

a list of the TLV's in this chain with the given type

getString

public java.lang.String getString(int type)

Description copied from interface: TlvChain

Returns the ASCII string contained in the last TLV in this chain with the given type, or null if no TLV with the given type is present in this chain. Equivalent to chain.hasTlv(type) ? chain.getLastTlv(type).getDataAsString() : null.

Specified by:

getString in interface TlvChain

Parameters:

type - the type of TLV whose ASCII string value will be returned

Returns:

the ASCII string stored in the value of the last TLV in this chain that has the given TLV type

See Also:

TlvChain.getLastTlv(int), Tlv.getDataAsString()

getString

public java.lang.String getString(int type,
                                  java.lang.String charset)

Description copied from interface: TlvChain

Returns the string contained in the last TLV in this chain with the given type, decoded with the given charset, or null if no TLV with the given type is present in this chain. Note that if the given charset is not found in this JVM, a valid charset will be derived (like converting "unicode-2.0" to "UTF-16BE") or "US-ASCII" will be used.

Specified by:

getString in interface TlvChain

Parameters:

type - the type of TLV whose string value will be returned

charset - the charset with which the string will be decoded, or null to decode as US-ASCII

Returns:

the ASCII string stored in the value of the last TLV in this chain that has the given TLV type

See Also:

TlvChain.getLastTlv(int)

getUShort

public int getUShort(int type)

Description copied from interface: TlvChain

Returns an unsigned two-byte integer read from the value of the last TLV of the given type in this chain, or -1 if either no TLV of the given type is present in this chain or if the data block for the TLV contains fewer than two bytes.

Specified by:

getUShort in interface TlvChain

Parameters:

type - the type of the TLV whose value will be returned

Returns:

the two-byte integer value stored in the last TLV of the given type, or -1 if none is present

See Also:

TlvChain.getLastTlv(int), Tlv.getDataAsUShort()

getUInt

public long getUInt(int type)

Description copied from interface: TlvChain

Returns an unsigned four-byte integer read from the value of the last TLV of the given type in this chain, or -1 if either no TLV of the given type is present in this chain or if the data block for the TLV contains fewer than two bytes.

Specified by:

getUInt in interface TlvChain

Parameters:

type - the type of the TLV whose value will be returned

Returns:

the four-byte integer value stored in the last TLV of the given type, or -1 if none is present

See Also:

TlvChain.getLastTlv(int), Tlv.getDataAsUInt()

getTotalSize

public int getTotalSize()

Description copied from interface: TlvChain

Returns the total size, in bytes, of this chain, as read from an incoming stream. Will be -1 if this chain was not read from a stream.

Specified by:

getTotalSize in interface TlvChain

Returns:

the total size, in bytes, of this chain

getWritableLength

public long getWritableLength()

Description copied from interface: Writable

Returns the length of the data that was or will be written in a call to write. The value returned by this method must not change after its first invocation.

Specified by:

getWritableLength in interface Writable

Returns:

the length of the data to be written by write

write

public void write(java.io.OutputStream out)
           throws java.io.IOException

Description copied from interface: Writable

Writes a representation of this object to the given stream. The length of the data written by this function must match any value previously returned by getWritableLength.

Specified by:

write in interface Writable

Parameters:

out - the stream to which to write

Throws:

java.io.IOException - if an I/O error occurs

getTlvList

protected abstract java.util.List getTlvList()

Returns a list of all of the TLV's in this chain.

Returns:

a list containing each of the TLV's in this chain, in order

getTlvMap

protected abstract java.util.Map getTlvMap()

Returns a map from TLV types (as Integers) to TLV lists (as Lists). The list should contain all TLV's of the given TLV type that exist in this TLV chain, in the same order as they appear in the full list.

Returns:

a map from TLV type to

createSiblingList

protected java.util.List createSiblingList()

Creates a new List to serve as a value for the TLV map. The default implementation returns a LinkedList.

Returns:

an empty list that can be used to store TLV's in this chain's TLV map

toString

public java.lang.String toString()