net.kano.joscar.tlv
Class AbstractTlvChain

java.lang.Object
  extended byAbstractTlvChain
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()