javacardx.framework.tlv

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 and Description
ConstructedBERTLV(short numTLVs) Constructor creates an empty ConstructedBERTLV object capable of encapsulating a ConstructedBERTLV structure.

Method Summary

Methods

Modifier and Type	Method and Description
short	append(BERTLV aTLV) Append the specified TLV to the end of ConstructedBERTLV.
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	delete(BERTLV aTLV, short occurrenceNum) Delete the specified occurrence of the specified BER TLV from this ConstructedBERTLV.
BERTLV	find(BERTag tag) Find the contained BERTLV within this ConstructedBERTLV object that matches the specified BER Tag.
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	findNext(BERTag tag, BERTLV aTLV, short occurrenceNum) Find the next 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.
short	init(byte[] bArray, short bOff, short bLen) (Re-)Initializes this ConstructedBERTLV using the input byte data.
short	init(ConstructedBERTag tag, BERTLV aTLV) (Re-)Initializes this ConstructedBERTLV object with the input tag and TLV parameter.
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.

Methods inherited from class javacardx.framework.tlv.BERTLV

getInstance, getLength, getLength, getTag, getTag, size, toBytes, verifyFormat

Methods inherited from class 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:

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