Class ConstructedBERTLV
- java.lang.Object
-
- javacardx.framework.tlv.BERTLV
-
- javacardx.framework.tlv.ConstructedBERTLV
-
public final class ConstructedBERTLV extends BERTLV
TheConstructedBERTLV
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 theConstructedBERTLV
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
andPrimitiveBERTLV
, 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 emptyConstructedBERTLV
object capable of encapsulating aConstructedBERTLV
structure.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods 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 ofConstructedBERTLV
.short
delete(BERTLV aTLV, short occurrenceNum)
Delete the specified occurrence of the specified BER TLV fromthis
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 containedBERTLV
withinthis
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 containedBERTLV
withinthis
ConstructedBERTLV
object that matches the specified BER Tag.short
init(byte[] bArray, short bOff, short bLen)
(Re-)Initializesthis
ConstructedBERTLV
using the input byte data.short
init(ConstructedBERTag tag, byte[] vArray, short vOff, short vLen)
(Re-)Initializesthis
ConstructedBERTLV
object with the input tag and specified data as value of the object.short
init(ConstructedBERTag tag, BERTLV aTLV)
(Re-)Initializesthis
ConstructedBERTLV
object with the input tag and TLV parameter.-
Methods inherited from class javacardx.framework.tlv.BERTLV
getInstance, getLength, getLength, getTag, getTag, size, toBytes, verifyFormat
-
-
-
-
Constructor Detail
-
ConstructedBERTLV
public ConstructedBERTLV(short numTLVs)
Constructor creates an emptyConstructedBERTLV
object capable of encapsulating aConstructedBERTLV
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-)Initializesthis
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 containedConstructedBERTLV
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 thanbArray.length
, the length of thebArray
array, anArrayIndexOutOfBoundsException
exception is thrown.
- Specified by:
init
in classBERTLV
- Parameters:
bArray
- input byte arraybOff
- offset within byte array containing the tlv databLen
- 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 negativeNullPointerException
- ifbArray
isnull
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.
- If
-
init
public short init(ConstructedBERTag tag, BERTLV aTLV) throws TLVException
(Re-)Initializesthis
ConstructedBERTLV
object with the input tag and TLV parameter. Note that a reference to the BER Tag object parameter is retained bythis
object. If the input BER Tag object is modified, the TLV structure encapsulated bythis
TLV instance is also modified. Similarly, a reference to the BER TLV object parameter is also retained bythis
object. If the input BER TLV object is modified, the TLV structure encapsulated bythis
TLV instance is also modified.- Parameters:
tag
- aBERTag
objectaTLV
- to use to initialize as the value ofthis
TLV- Returns:
- the resulting size of
this
TLV if represented in bytes - Throws:
NullPointerException
- if eithertag
oraTLV
isnull
TLVException
- with the following reason codes:TLVException.INSUFFICIENT_STORAGE
if the required capacity is not available and the implementation does not support automatic expansionTLVException.INVALID_PARAM
ifaTLV
isthis
orthis
TLV object is contained in any of the constructed TLV objects in the hierarchy of theaTLV
object.
-
init
public short init(ConstructedBERTag tag, byte[] vArray, short vOff, short vLen) throws TLVException
(Re-)Initializesthis
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 bythis
object. If the input BER Tag object is modified, the TLV structure encapsulated bythis
TLV instance is also modified.Each contained
BERTLV
is constructed and initialized using this init method. The initial capacity of each of the containedConstructedBERTLV
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 thanvArray.length
, the length of thevArray
array, anArrayIndexOutOfBoundsException
exception is thrown.
- Parameters:
tag
- a BERTag objectvArray
- the byte array containingvLen
bytes of TLV ValuevOff
- offset within the vArray byte array where data beginsvLen
- 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 negativeNullPointerException
- if eithertag
orvArray
isnull
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.
- If
-
append
public short append(BERTLV aTLV) throws TLVException
Append the specified TLV to the end ofConstructedBERTLV
. Note that a reference to the BER TLV object parameter is retained bythis
object. A change in the BER TLV object contents affectsthis
TLV instance.- Parameters:
aTLV
- a BER TLV object- Returns:
- the resulting size of
this
TLV if represented in bytes - Throws:
NullPointerException
- ifaTLV
isnull
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
ifaTLV
isthis
orthis
TLV object is contained in any of the constructed TLV objects in the hierarchy of theaTLV
object.
-
delete
public short delete(BERTLV aTLV, short occurrenceNum) throws TLVException
Delete the specified occurrence of the specified BER TLV fromthis
ConstructedBERTLV
. The internal reference at the specified occurrence to the specified BER TLV object is removed.- Parameters:
aTLV
- the BER TLV object to delete fromthis
occurrenceNum
- specifies which occurrence ofaTLV
withinthis
BER TLV to use- Returns:
- the resulting size of
this
TLV if represented in bytes - Throws:
NullPointerException
- ifaTLV
isnull
TLVException
- with the following reason codes:TLVException.INVALID_PARAM
if the specified BER TLV object parameter is not an element ofthis
or occurs less thanoccurrenceNum
times inthis
oroccurrenceNum
is 0 or negative.
-
find
public BERTLV find(BERTag tag)
Find the containedBERTLV
withinthis
ConstructedBERTLV
object that matches the specified BER Tag. If the tag parameter isnull
, the first contained BER TLV object is returned.- Parameters:
tag
- theBERTag
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 containedBERTLV
withinthis
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 foundaTLV
- tlv object contained withinthis
BER TLV following which the search beginsoccurrenceNum
- specifies which occurrence ofaTLV
withinthis
BER TLV to use- Returns:
- TLV object matching the indicated tag or null if none found.
- Throws:
NullPointerException
- ifaTLV
isnull
TLVException
- with the following reason codes:TLVException.INVALID_PARAM
if the specified BER TLV object parameter is not an element ofthis
or occurs less thanoccurrenceNum
times inthis
or ifoccurrenceNum
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 arraybTLVInOff
- offset within byte array containing the tlv databerTLVOutArray
- output TLV byte arraybTLVOutOff
- 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 negativeNullPointerException
- if eitherberTLVInArray
orberTLVOutArray
isnull
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 arraybTLVOff
- offset within byte array containing the tlv databerTagArray
- byte array containing the Tag to be searchedbTagOff
- offset withinberTagArray
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 negativeNullPointerException
- ifberTLVArray
isnull
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 specifiedstartOffset
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 arraybTLVOff
- offset within byte array containing the TLV datastartOffset
- offset within the inputberTLVArray
to begin the searchberTagArray
- byte array containing the Tag to be searchedbTagOff
- offset withinberTagArray
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 negativeNullPointerException
- ifberTLVArray
isnull
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 theberTLVArray
array does not contain a top level contained TLV element at the specifiedstartOffset
offset.
-
-