**javacardx.framework.tlv** ====Class ConstructedBERTLV ==== *[[javacard:java-card-api:object|java.lang.Object]] \\ *[[javacard:java-card-api:bertlv|javacardx.framework.tlv.BERTLV]] \\ ---- public final class **ConstructedBERTLV**extends [[javacard:java-card-api:BERTLV|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 ^^ | **[[javacard:java-card-api:ConstructedBERTLV#ConstructedBERTLV(short)|ConstructedBERTLV]] **(short numTLVs)          Constructor creates an empty ConstructedBERTLV object capable of encapsulating a ConstructedBERTLV structure. |   ^ Method Summary ^^ | ** short** | **[[javacard:java-card-api:ConstructedBERTLV#append(javacardx.framework.tlv.BERTLV)|append]] **([[javacard:java-card-api:BERTLV|BERTLV]]  aTLV)          Append the specified TLV to the end of ConstructedBERTLV. | | **static short** | **[[javacard:java-card-api:ConstructedBERTLV#append(byte[], short, byte[], 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** | **[[javacard:java-card-api:ConstructedBERTLV#delete(javacardx.framework.tlv.BERTLV, short)|delete]] **([[javacard:java-card-api:BERTLV|BERTLV]]  aTLV,short occurrenceNum)          Delete the specified occurrence of the specified BER TLV from this ConstructedBERTLV. | | ** [[javacard:java-card-api:BERTLV|BERTLV]] ** | **[[javacard:java-card-api:ConstructedBERTLV#find(javacardx.framework.tlv.BERTag)|find]] **([[javacard:java-card-api:BERTag|BERTag]]  tag)          Find the contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag. | | **static short** | **[[javacard:java-card-api:ConstructedBERTLV#find(byte[], short, byte[], 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. | | ** [[javacard:java-card-api:BERTLV|BERTLV]] ** | **[[javacard:java-card-api:ConstructedBERTLV#findNext(javacardx.framework.tlv.BERTag, javacardx.framework.tlv.BERTLV, short)|findNext]] **([[javacard:java-card-api:BERTag|BERTag]]  tag,[[javacard:java-card-api:BERTLV|BERTLV]]  aTLV,short occurrenceNum)          Find the next contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag. | | **static short** | **[[javacard:java-card-api:ConstructedBERTLV#findNext(byte[], short, short, byte[], 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. | | ** short** | **[[javacard:java-card-api:ConstructedBERTLV#init(byte[], short, short)|init]] **(byte[] bArray,short bOff,short bLen)          (Re-)Initializes this ConstructedBERTLV using the input byte data. | | ** short** | **[[javacard:java-card-api:ConstructedBERTLV#init(javacardx.framework.tlv.ConstructedBERTag, javacardx.framework.tlv.BERTLV)|init]] **([[javacard:java-card-api:ConstructedBERTag|ConstructedBERTag]]  tag,[[javacard:java-card-api:BERTLV|BERTLV]]  aTLV)          (Re-)Initializes this ConstructedBERTLV object with the input tag and TLV parameter. | | ** short** | **[[javacard:java-card-api:ConstructedBERTLV#init(javacardx.framework.tlv.ConstructedBERTag, byte[], short, short)|init]] **([[javacard:java-card-api:ConstructedBERTag|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. |   ^ Methods inherited from class javacardx.framework.tlv.BERTLV ^ | [[javacard:java-card-api:BERTLV#getInstance(byte[], short, short)|getInstance]] , [[javacard:java-card-api:BERTLV#getLength()|getLength]] , [[javacard:java-card-api:BERTLV#getLength(byte[], short)|getLength]] , [[javacard:java-card-api:BERTLV#getTag()|getTag]] , [[javacard:java-card-api:BERTLV#getTag(byte[], short, byte[], short)|getTag]] , [[javacard:java-card-api:BERTLV#size()|size]] , [[javacard:java-card-api:BERTLV#toBytes(byte[], short)|toBytes]] , [[javacard:java-card-api:BERTLV#verifyFormat(byte[], short, short)|verifyFormat]] |   ^ Methods inherited from class java.lang.Object ^ | [[javacard:java-card-api:Object#equals(java.lang.Object)|equals]] |   ^ Constructor Detail ^ === 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:** [[javacard:java-card-api:TLVException|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 Detail ^ === init === public short **init**(byte[] bArray, short bOff, short bLen) throws [[javacard:java-card-api:TLVException|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:**[[javacard:java-card-api:BERTLV#init(byte[], short, short)|init]] in class [[javacard:java-card-api:BERTLV|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:** [[javacard:java-card-api:ArrayIndexOutOfBoundsException|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 [[javacard:java-card-api:NullPointerException|NullPointerException]] - if bArray is null [[javacard:java-card-api:TLVException|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**([[javacard:java-card-api:ConstructedBERTag|ConstructedBERTag]]  tag, [[javacard:java-card-api:BERTLV|BERTLV]]  aTLV) throws [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:NullPointerException|NullPointerException]] - if either tag or aTLV is null [[javacard:java-card-api:TLVException|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**([[javacard:java-card-api:ConstructedBERTag|ConstructedBERTag]]  tag, byte[] vArray, short vOff, short vLen) throws [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:ArrayIndexOutOfBoundsException|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 [[javacard:java-card-api:NullPointerException|NullPointerException]] - if either tag or vArray is null [[javacard:java-card-api:TLVException|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**([[javacard:java-card-api:BERTLV|BERTLV]]  aTLV) throws [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:NullPointerException|NullPointerException]] - if aTLV is null [[javacard:java-card-api:TLVException|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**([[javacard:java-card-api:BERTLV|BERTLV]]  aTLV, short occurrenceNum) throws [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:NullPointerException|NullPointerException]] - if aTLV is null [[javacard:java-card-api:TLVException|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 [[javacard:java-card-api:BERTLV|BERTLV]] **find**([[javacard:java-card-api:BERTag|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 [[javacard:java-card-api:BERTLV|BERTLV]] **findNext**([[javacard:java-card-api:BERTag|BERTag]]  tag, [[javacard:java-card-api:BERTLV|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:** [[javacard:java-card-api:NullPointerException|NullPointerException]] - if aTLV is null [[javacard:java-card-api:TLVException|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 [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:ArrayIndexOutOfBoundsException|ArrayIndexOutOfBoundsException]] - if accessing the input or output array would cause access of data outside array bounds, or if either array offset parameter is negative [[javacard:java-card-api:NullPointerException|NullPointerException]] - if either berTLVInArray or berTLVOutArray is null [[javacard:java-card-api:TLVException|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 [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:ArrayIndexOutOfBoundsException|ArrayIndexOutOfBoundsException]] - if accessing the input arrays would cause access of data outside array bounds, or if either array offset parameter is negative [[javacard:java-card-api:NullPointerException|NullPointerException]] - if berTLVArray is null [[javacard:java-card-api:TLVException|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 [[javacard:java-card-api:TLVException|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:** [[javacard:java-card-api:ArrayIndexOutOfBoundsException|ArrayIndexOutOfBoundsException]] - if accessing the input arrays would cause access of data outside array bounds, or if any of the array offset parameters is negative [[javacard:java-card-api:NullPointerException|NullPointerException]] - if berTLVArray is null [[javacard:java-card-api:TLVException|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. \\