Class ConstructedBERTLV

java.lang.Object
javacardx.framework.tlv.BERTLV
javacardx.framework.tlv.ConstructedBERTLV
public final class ConstructedBERTLV extends BERTLV
The ConstructedBERTLV class encapsulates a constructed BER TLV structure. It extends the generic BER TLV class. The rules on the allowed encoding of the Tag, length and value fields is based on the ASN.1 BER encoding rules ISO/IEC 8825-1:2002.

The ConstructedBERTLV class only supports encoding of the length(L) octets in definite form. The value(V) field which encodes the contents octets are merely viewed as a set of other BERTLVs.

Every ConstructedBERTLV has a capacity which represents the size of the allocated internal data structures to reference all the contained BER TLV objects. As long as the number of contained BER TLV objects of the ConstructedBERTLV does not exceed the capacity, it is not necessary to allocate new internal data. If the internal buffer overflows, and the implementation supports automatic expansion which might require new data allocation and possibly old data/object deletion, it is automatically made larger. Otherwise a TLVException is thrown.

The BERTLV class and the subclasses ConstructedBERTLV and PrimitiveBERTLV, also provide static methods to parse or edit a TLV structure representation in a byte array.

Since:
2.2.2

  • Constructor Summary

    Constructors
    Constructor
    Description
    ConstructedBERTLV(short numTLVs)
    Constructor creates an empty ConstructedBERTLV object capable of encapsulating a ConstructedBERTLV structure.

  • Method Summary

    Modifier and Type
    Method
    Description
    static short
    append(byte[] berTLVInArray, short bTLVInOff, byte[] berTLVOutArray, short bTLVOutOff)
    Append the TLV representation in the specified byte array to the constructed BER tlv representation in the specified output byte array.
    short
    append(BERTLV aTLV)
    Append the specified TLV to the end of ConstructedBERTLV.
    short
    delete(BERTLV aTLV, short occurrenceNum)
    Delete the specified occurrence of the specified BER TLV from this ConstructedBERTLV.
    static short
    find(byte[] berTLVArray, short bTLVOff, byte[] berTagArray, short bTagOff)
    Find the offset of the contained TLV representation at the top level within the TLV structure representation in the specified byte array that matches the specified tag representation in the specified byte array If the tag array parameter is null, the offset of the first contained TLV is returned.
    BERTLV
    find(BERTag tag)
    Find the contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag.
    static short
    findNext(byte[] berTLVArray, short bTLVOff, short startOffset, byte[] berTagArray, short bTagOff)
    Find the offset of the next contained TLV representation at the top level within the TLV structure representation in the specified byte array that matches the specified tag representation in the specified byte array.
    BERTLV
    findNext(BERTag tag, BERTLV aTLV, short occurrenceNum)
    Find the next contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag.
    short
    init(byte[] bArray, short bOff, short bLen)
    (Re-)Initializes this ConstructedBERTLV using the input byte data.
    short
    init(ConstructedBERTag tag, byte[] vArray, short vOff, short vLen)
    (Re-)Initializes this ConstructedBERTLV object with the input tag and specified data as value of the object.
    short
    init(ConstructedBERTag tag, BERTLV aTLV)
    (Re-)Initializes this ConstructedBERTLV object with the input tag and TLV parameter.

    Methods inherited from class BERTLV

    getInstance, getLength, getLength, getTag, getTag, size, toBytes, verifyFormat
    Modifier and Type
    Method
    Description
    static BERTLV
    getInstance(byte[] bArray, short bOff, short bLen)
    Creates the BERTLV using the input binary data.
    short
    getLength()
    Returns the value of this TLV object's Length component
    static short
    getLength(byte[] berTLVArray, short bOff)
    Returns the value of the TLV Structure's Length component in the specified input byte array
    BERTag
    getTag()
    Returns this value of the TLV object's Tag component
    static short
    getTag(byte[] berTLVArray, short bTLVOff, byte[] berTagArray, short bTagOff)
    Copies the tag component in the TLV representation in the specified input byte array to the specified output byte array
    short
    size()
    Returns the number of bytes required to represent this TLV structure
    short
    toBytes(byte[] outBuf, short bOff)
    Writes this TLV structure to the specified byte array.
    static boolean
    verifyFormat(byte[] berTlvArray, short bOff, short bLen)
    Checks if the input data is a well-formed BER TLV representation.

    Methods inherited from class Object

    equals
    Modifier and Type
    Method
    Description
    boolean
    equals(Object obj)
    Compares two Objects for equality.

  • Constructor Details

    • ConstructedBERTLV

      public ConstructedBERTLV(short numTLVs)
      Constructor creates an empty ConstructedBERTLV object capable of encapsulating a ConstructedBERTLV structure.

      The initial capacity is specified by the numTLVs argument.

      Parameters:
      numTLVs - is the number of contained TLVs to allocate
      Throws:
      TLVException - with the following reason codes:
      • TLVException.INVALID_PARAM if numTLVs parameter is negative or larger than the maximum capacity supported by the implementation.

  • Method Details

    • init

      public short init(byte[] bArray, short bOff, short bLen) throws TLVException
      (Re-)Initializes this ConstructedBERTLV using the input byte data.

      If this ConstructedBERTLV is not empty, internal references to the previously contained BER TLV objects is removed.

      Each contained BERTLV is constructed and initialized using this init method. The initial capacity of each of the contained ConstructedBERTLV objects is set to the number of TLVs contained at the top level of that TLV structure in the byte array.

      Note:

      • If bOff+bLen is greater than bArray.length, the length of the bArray array, an ArrayIndexOutOfBoundsException exception is thrown.

      Specified by:
      init in class BERTLV
      Parameters:
      bArray - input byte array
      bOff - offset within byte array containing the tlv data
      bLen - byte length of input data
      Returns:
      the resulting size of this TLV if represented in bytes
      Throws:
      ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds, or if the array offset or array length parameter is negative
      NullPointerException - if bArray is null
      TLVException - with the following reason codes:
      • TLVException.ILLEGAL_SIZE if the required capacity is not available and the implementation does not support automatic expansion.
      • TLVException.MALFORMED_TLV if the input data is not a well-formed constructed BER TLV structure.

    • init

      public short init(ConstructedBERTag tag, BERTLV aTLV) throws TLVException
      (Re-)Initializes this ConstructedBERTLV object with the input tag and TLV parameter. Note that a reference to the BER Tag object parameter is retained by this object. If the input BER Tag object is modified, the TLV structure encapsulated by this TLV instance is also modified. Similarly, a reference to the BER TLV object parameter is also retained by this object. If the input BER TLV object is modified, the TLV structure encapsulated by this TLV instance is also modified.
      Parameters:
      tag - a BERTag object
      aTLV - to use to initialize as the value of this TLV
      Returns:
      the resulting size of this TLV if represented in bytes
      Throws:
      NullPointerException - if either tag or aTLV is null
      TLVException - with the following reason codes:
      • TLVException.INSUFFICIENT_STORAGE if the required capacity is not available and the implementation does not support automatic expansion
      • TLVException.INVALID_PARAM if aTLV is this or this TLV object is contained in any of the constructed TLV objects in the hierarchy of the aTLV object.

    • init

      public short init(ConstructedBERTag tag, byte[] vArray, short vOff, short vLen) throws TLVException
      (Re-)Initializes this ConstructedBERTLV object with the input tag and specified data as value of the object. Note that a reference to the BER Tag object is retained by this object. If the input BER Tag object is modified, the TLV structure encapsulated by this TLV instance is also modified.

      Each contained BERTLV is constructed and initialized using this init method. The initial capacity of each of the contained ConstructedBERTLV objects is set to the number of TLVs contained at the top level of that TLV structure in the byte array.

      Note:

      • If vOff+vLen is greater than vArray.length, the length of the vArray array, an ArrayIndexOutOfBoundsException exception is thrown.

      Parameters:
      tag - a BERTag object
      vArray - the byte array containing vLen bytes of TLV Value
      vOff - offset within the vArray byte array where data begins
      vLen - byte length of the value data in vArray
      Returns:
      the resulting size of this TLV if represented in bytes
      Throws:
      ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds, or if the array offset or array length parameter is negative
      NullPointerException - if either tag or vArray is null
      TLVException - with the following reason codes:
      • TLVException.INSUFFICIENT_STORAGE or if the required capacity is not available and the implementation does not support automatic expansion.

    • append

      public short append(BERTLV aTLV) throws TLVException
      Append the specified TLV to the end of ConstructedBERTLV. Note that a reference to the BER TLV object parameter is retained by this object. A change in the BER TLV object contents affects this TLV instance.
      Parameters:
      aTLV - a BER TLV object
      Returns:
      the resulting size of this TLV if represented in bytes
      Throws:
      NullPointerException - if aTLV is null
      TLVException - with the following reason codes:
      • TLVException.INSUFFICIENT_STORAGE if the required capacity is not available and the implementation does not support automatic expansion.
      • TLVException.INVALID_PARAM if aTLV is this or this TLV object is contained in any of the constructed TLV objects in the hierarchy of the aTLV object.

    • delete

      public short delete(BERTLV aTLV, short occurrenceNum) throws TLVException
      Delete the specified occurrence of the specified BER TLV from this ConstructedBERTLV. The internal reference at the specified occurrence to the specified BER TLV object is removed.
      Parameters:
      aTLV - the BER TLV object to delete from this
      occurrenceNum - specifies which occurrence of aTLV within this BER TLV to use
      Returns:
      the resulting size of this TLV if represented in bytes
      Throws:
      NullPointerException - if aTLV is null
      TLVException - with the following reason codes:
      • TLVException.INVALID_PARAM if the specified BER TLV object parameter is not an element of this or occurs less than occurrenceNum times in this or occurrenceNum is 0 or negative.

    • find

      public BERTLV find(BERTag tag)
      Find the contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag. If the tag parameter is null, the first contained BER TLV object is returned.
      Parameters:
      tag - the BERTag to be found
      Returns:
      TLV object matching the indicated tag or null if none found.

    • findNext

      public BERTLV findNext(BERTag tag, BERTLV aTLV, short occurrenceNum)
      Find the next contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag. The search must be started from the TLV position following the specified occurrence of the specified BER TLV object parameter. If the tag parameter is null, the next contained BER TLV object is returned.
      Parameters:
      tag - the BERTag to be found
      aTLV - tlv object contained within this BER TLV following which the search begins
      occurrenceNum - specifies which occurrence of aTLV within this BER TLV to use
      Returns:
      TLV object matching the indicated tag or null if none found.
      Throws:
      NullPointerException - if aTLV is null
      TLVException - with the following reason codes:
      • TLVException.INVALID_PARAM if the specified BER TLV object parameter is not an element of this or occurs less than occurrenceNum times in this or if occurrenceNum is 0 or negative.

    • append

      public static short append(byte[] berTLVInArray, short bTLVInOff, byte[] berTLVOutArray, short bTLVOutOff) throws TLVException
      Append the TLV representation in the specified byte array to the constructed BER tlv representation in the specified output byte array.
      Parameters:
      berTLVInArray - input byte array
      bTLVInOff - offset within byte array containing the tlv data
      berTLVOutArray - output TLV byte array
      bTLVOutOff - offset within byte array where output begins
      Returns:
      the size of the resulting output TLV
      Throws:
      ArrayIndexOutOfBoundsException - if accessing the input or output array would cause access of data outside array bounds, or if either array offset parameter is negative
      NullPointerException - if either berTLVInArray or berTLVOutArray is null
      TLVException - with the following reason codes:
      • TLVException.MALFORMED_TLV if the TLV representation in the input byte array is not a well-formed constructed BER TLV.

    • find

      public static short find(byte[] berTLVArray, short bTLVOff, byte[] berTagArray, short bTagOff) throws TLVException
      Find the offset of the contained TLV representation at the top level within the TLV structure representation in the specified byte array that matches the specified tag representation in the specified byte array If the tag array parameter is null, the offset of the first contained TLV is returned.
      Parameters:
      berTLVArray - input byte array
      bTLVOff - offset within byte array containing the tlv data
      berTagArray - byte array containing the Tag to be searched
      bTagOff - offset within berTagArray byte array where tag data begins
      Returns:
      offset into berTLVArray where the indicated tag was found or -1 if none found.
      Throws:
      ArrayIndexOutOfBoundsException - if accessing the input arrays would cause access of data outside array bounds, or if either array offset parameter is negative
      NullPointerException - if berTLVArray is null
      TLVException - with the following reason codes:
      • TLVException.MALFORMED_TLV if the TLV representation in the specified byte array is not a well-formed constructed BER TLV structure.
      • TLVException.MALFORMED_TAG if tag representation in the specified byte array is is not a well-formed BER Tag structure.

    • findNext

      public static short findNext(byte[] berTLVArray, short bTLVOff, short startOffset, byte[] berTagArray, short bTagOff) throws TLVException
      Find the offset of the next contained TLV representation at the top level within the TLV structure representation in the specified byte array that matches the specified tag representation in the specified byte array. The search must be started from the TLV position following the specified startOffset parameter where a contained TLV exists at the top level. If the tag array parameter - berTagArray - is null, the offset of the next contained TLV representation at the top level is returned.
      Parameters:
      berTLVArray - input byte array
      bTLVOff - offset within byte array containing the TLV data
      startOffset - offset within the input berTLVArray to begin the search
      berTagArray - byte array containing the Tag to be searched
      bTagOff - offset within berTagArray byte array where tag data begins
      Returns:
      offset into berTLVArray where the indicated tag was found or -1 if none found.
      Throws:
      ArrayIndexOutOfBoundsException - if accessing the input arrays would cause access of data outside array bounds, or if any of the array offset parameters is negative
      NullPointerException - if berTLVArray is null
      TLVException - with the following reason codes:
      • TLVException.MALFORMED_TLV if the TLV representation in the specified byte array is not a well-formed constructed BER TLV structure.
      • TLVException.MALFORMED_TAG if the tag representation in the specified byte array is not a well-formed BER Tag structure.
      • TLVException.INVALID_PARAM if the berTLVArray array does not contain a top level contained TLV element at the specified startOffset offset.