ConstructedBERTLV (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacardx.framework.tlv
Class ConstructedBERTLV

    java.lang.Object
      javacardx.framework.tlv.BERTLV
          javacardx.framework.tlv.ConstructedBERTLV

    @TransactionType(value=SUPPORTS)
    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
`ConstructedBERTLV(short numTLVs)` Constructor creates an empty `ConstructedBERTLV` object capable of encapsulating a `ConstructedBERTLV` structure.

Method Summary
`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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.