net.kano.joscar.tlv
Interface TlvChain

All Superinterfaces:
LiveWritable, Writable
All Known Subinterfaces:
MutableTlvChain
All Known Implementing Classes:
AbstractTlvChain, DefaultMutableTlvChain

public interface TlvChain
extends Writable

Represents a "chain," or block, or sequence, of Tlvs.


Method Summary
 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.
 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.
 boolean hasTlv(int type)
          Returns true if this TLV chain contains any TLV's of the given TLV type.
 java.util.Iterator iterator()
          Returns an iterator over the TLV's in this TLV chain.
 
Methods inherited from interface net.kano.joscar.Writable
getWritableLength, write
 

Method Detail

hasTlv

public boolean hasTlv(int type)
Returns true if this TLV chain contains any TLV's of the given TLV type.

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()
Returns an array of all TLV's in this chain, in order.

Returns:
all of this chain's TLV's

iterator

public java.util.Iterator iterator()
Returns an iterator over the TLV's in this TLV chain.

Returns:
an iterator traversing over the TLV's in this chain

getTlvCount

public int getTlvCount()
Returns the number of TLV's in this chain.

Returns:
the number of TLV's in this chain

getFirstTlv

public 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.

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)
Returns the last TLV in this chain with the given type, or null of TLV of the given type is present.

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)
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.

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)
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.

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:
getLastTlv(int), Tlv.getDataAsString()

getString

public 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. 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.

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:
getLastTlv(int)

getUShort

public 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.

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:
getLastTlv(int), Tlv.getDataAsUShort()

getUInt

public 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.

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:
getLastTlv(int), Tlv.getDataAsUInt()

getTotalSize

public int getTotalSize()
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.

Returns:
the total size, in bytes, of this chain