PrimitiveBERTLV (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 PrimitiveBERTLV

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

    @TransactionType(value=SUPPORTS)
    public class PrimitiveBERTLV

extends BERTLV

The `PrimitiveBERTLV` class encapsulates a primitive BER TLV structure. It extends the generic `BERTLV` 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 `PrimitiveBERTLV` 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 series of bytes.

Every `PrimitiveBERTLV` has a capacity which represents the allocated internal buffer to represent the Value of `this` TLV object. As long as the number of bytes required to represent the Value of the TLV object does not exceed the capacity, it is not necessary to allocate additional internal buffer space. 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
`PrimitiveBERTLV(short numValueBytes)` Constructor creates an empty `PrimitiveBERTLV` object capable of encapsulating a Primitive BER TLV structure.

Method Summary
`static short` | `appendValue(byte[] berTLVArray, short bTLVOff, byte[] vArray, short vOff, short vLen)` Appends the specified data to the end of the Primitive TLV representation in the specified byte array.
`short` | `appendValue(byte[] vArray, short vOff, short vLen)` Appends the specified data to the end of `this` Primitive BER TLV object.
`short` | `getValue(byte[] tlvValue, short tOff)` Writes the value (V) part of `this` Primitive BER TLV object into the output buffer.
`static short` | `getValueOffset(byte[] berTLVArray, short bTLVOff)` Returns the offset into the specified input byte array of the value (V) part of the BER TLV structure representation in the input array.
`short` | `init(byte[] bArray, short bOff, short bLen)` (Re-)Initializes `this` `PrimitiveBERTLV` using the input byte data.
`short` | `init(PrimitiveBERTag tag, byte[] vArray, short vOff, short vLen)` (Re-)Initializes `this` `PrimitiveBERTLV` object with the input tag, length and data.
`short` | `replaceValue(byte[] vArray, short vOff, short vLen)` Replaces the specified data in place of the current value of `this` Primitive BER TLV object.
`static short` | `toBytes(byte[] berTagArray, short berTagOff, byte[] valueArray, short vOff, short vLen, byte[] outBuf, short bOff)` Writes a primitive TLV representation to the specified byte array using as input a Primitive BER tag representation in a byte array and a value representation in another byte array.

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

### PrimitiveBERTLV

    public PrimitiveBERTLV(short numValueBytes)

  Constructor creates an empty `PrimitiveBERTLV` object capable of encapsulating a Primitive BER TLV structure.

  The initial capacity is specified by the numValueBytes argument.

  Parameters:
    `numValueBytes` - is the number of Value bytes to allocate
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.INVALID_PARAM` if numValueBytes 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` `PrimitiveBERTLV` using the input byte data.

  If `this` primitive TLV object is empty, the initial capacity of `this` `PrimitiveBERTLV` is set to the byte length of the Value represented in the primitive TLV structure of the input 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.INSUFFICIENT_STORAGE` 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 primitive BER TLV structure.

### init

    public short init(PrimitiveBERTag tag,
                      byte[] vArray,
                      short vOff,
                      short vLen)
               throws TLVException

  (Re-)Initializes `this` `PrimitiveBERTLV` object with the input tag, length and data. Note that a reference to the BER Tag object is retained by `this` object. A change in the BER Tag object contents affects `this` TLV instance.

  If `this` primitive TLV object is empty, the initial capacity of `this` `PrimitiveBERTLV` is set to the value of the vLen argument.

  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 length 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` parameter 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.

### appendValue

    public short appendValue(byte[] vArray,
                             short vOff,
                             short vLen)
                      throws TLVException

  Appends the specified data to the end of `this` Primitive BER TLV object.

  Note:

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

  Parameters:
    `vArray` - the byte array containing length bytes of TLV value
    `vOff` - offset within the `vArray` byte array where data begins
    `vLen` - the byte length of the value in the input `vArray`
  Returns:
    the resulting size of `this` 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 length parameter is negative
    `NullPointerException` - if `vArray` 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.EMPTY_TLV` if `this` `PrimitiveBERTLV` object is empty.

### replaceValue

    public short replaceValue(byte[] vArray,
                              short vOff,
                              short vLen)
                       throws TLVException

  Replaces the specified data in place of the current value of `this` Primitive BER TLV object.

  Note:

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

  Parameters:
    `vArray` - the byte array containing length bytes of TLV value
    `vOff` - offset within the `vArray` byte array where data begins
    `vLen` - the byte length of the value in the input `vArray`
  Returns:
    the resulting size of `this` 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 length parameter is negative
    `NullPointerException` - if `vArray` 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.EMPTY_TLV` if `this` `PrimitiveBERTLV` object is empty.

### getValue

    public short getValue(byte[] tlvValue,
                          short tOff)
                   throws TLVException

  Writes the value (V) part of `this` Primitive BER TLV object into the output buffer. Returns the length of data written to tlvValue output array

  Parameters:
    `tlvValue` - the output byte array
    `tOff` - offset within the `tlvValue` byte array where output data begins
  Returns:
    the byte length of data written to tlvValue output array
  Throws:
    `ArrayIndexOutOfBoundsException` - if accessing the output array would cause access of data outside array bounds, or if the array offset parameter is negative
    `NullPointerException` - if `tlvValue` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_SIZE_GREATER_THAN_32767` if the size of the Primitive BER TLV is > 32767
    - `TLVException.EMPTY_TLV` if `this` `PrimitiveBERTLV` object is empty.

### getValueOffset

    public static short getValueOffset(byte[] berTLVArray,
                                       short bTLVOff)
                                throws TLVException

  Returns the offset into the specified input byte array of the value (V) part of the BER TLV structure representation in the input array.

  Parameters:
    `berTLVArray` - input byte array
    `bTLVOff` - offset within byte array containing the TLV data
  Returns:
    the offset into the specified input byte array of the value (V) part
  Throws:
    `ArrayIndexOutOfBoundsException` - if accessing the input array would cause access of data outside array bounds, or if the array offset parameter is negative
    `NullPointerException` - if `tlvValue` or `berTLVArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_SIZE_GREATER_THAN_32767` if the size of the Primitive BER TLV is > 32767.
    - `TLVException.MALFORMED_TLV` if the TLV representation in the input byte array is not a well-formed primitive BER TLV structure.

### toBytes

    public static short toBytes(byte[] berTagArray,
                                short berTagOff,
                                byte[] valueArray,
                                short vOff,
                                short vLen,
                                byte[] outBuf,
                                short bOff)

  Writes a primitive TLV representation to the specified byte array using as input a Primitive BER tag representation in a byte array and a value representation in another byte array.

  Note:

  - If `vOff+vLen` is greater than `valueArray.length`, the length of the `valueArray` array, an `ArrayIndexOutOfBoundsException` exception is thrown.

  Parameters:
    `berTagArray` - input byte array
    `berTagOff` - offset within byte array containing first byte of tag
    `valueArray` - input byte array containing primitive value
    `vOff` - offset within byte array containing the first byte of value
    `vLen` - length in bytes of the value component of the TLV
    `outBuf` - output byte array
    `bOff` - offset within byte array output data begins
  Returns:
    the byte length written to the output array
  Throws:
    `ArrayIndexOutOfBoundsException` - if accessing the input or output arrays would cause access of data outside array bounds, or if any of the array offset or array length parameters is negative
    `NullPointerException` - if `berTagArray` or `valueArray` or `outBuf` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_SIZE_GREATER_THAN_32767` if the size of the resulting Primitive BER TLV is > 32767.
    - `TLVException.MALFORMED_TAG` if the tag representation in the byte array is not a well-formed constructed array tag.

### appendValue

    public static short appendValue(byte[] berTLVArray,
                                    short bTLVOff,
                                    byte[] vArray,
                                    short vOff,
                                    short vLen)
                             throws TLVException

  Appends the specified data to the end of the Primitive TLV representation in the specified byte array. Note that this method is only applicable to a primitive TLV representation, otherwise an exception is thrown.

  Note:

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

  Parameters:
    `berTLVArray` - input byte array
    `bTLVOff` - offset within byte array containing the TLV data
    `vArray` - the byte array containing value to be appended
    `vOff` - offset within the `vArray` byte array where the data begins
    `vLen` - the byte length of the value in the input `vArray`
  Returns:
    the resulting size of `this` if represented in bytes
  Throws:
    `ArrayIndexOutOfBoundsException` - if accessing the input arrays would cause access of data outside array bounds, or if any of the array offset or array length parameters is negative
    `NullPointerException` - if `berTLVArray` or `vArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_SIZE_GREATER_THAN_32767` if the size of the resulting Primitive BER TLV is > 32767.
    - `TLVException.MALFORMED_TLV` if the TLV representation in the input byte array is not a well-formed primitive BER TLV structure

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.