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

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

Direct Known Subclasses:
  ConstructedBERTLV, PrimitiveBERTLV

    @TransactionType(value=SUPPORTS)
    public abstract class BERTLV

extends Object

The abstract `BERTLV` class encapsulates a BER TLV structure. The rules on the allowed encoding of the Tag, length and value fields are based on the ASN.1 BER encoding rules ISO/IEC 8825-1:2002.

The `BERTLV` class and the subclasses - `ConstructedBERTLV` and `PrimitiveBERTLV` only support encoding of the length(L) octets in definite form. These classes do not provide support for the encoding rules of the contents octets of the value(V) field as described in ISO/IEC 8825-1:2002.

The `BERTLV` class and the subclasses - `ConstructedBERTLV` and `PrimitiveBERTLV` also provide static methods to parse/edit a TLV structure representation in a byte array.

Since:
  2.2.2

Constructor Summary
`protected` | `BERTLV()` Constructor creates an empty `BERTLV` object capable of encapsulating a BER TLV structure.

Method Summary
`static BERTLV` | `getInstance(byte[] bArray, short bOff, short bLen)` Creates the `BERTLV` using the input binary data.
`short` | `getLength()` Returns the value of `this` TLV object's Length component
`static short` | `getLength(byte[] berTLVArray, short bOff)` Returns the value of the TLV Structure's Length component in the specified input byte array
`BERTag` | `getTag()` Returns `this` value of the TLV object's Tag component
`static short` | `getTag(byte[] berTLVArray, short bTLVOff, byte[] berTagArray, short bTagOff)` Copies the tag component in the TLV representation in the specified input byte array to the specified output byte array
`abstract short` | `init(byte[] bArray, short bOff, short bLen)` Abstract init method.
`short` | `size()` Returns the number of bytes required to represent `this` TLV structure
`short` | `toBytes(byte[] outBuf, short bOff)` Writes `this` TLV structure to the specified byte array.
`static boolean` | `verifyFormat(byte[] berTlvArray, short bOff, short bLen)` Checks if the input data is a well-formed BER TLV representation.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### BERTLV

    protected BERTLV()

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

Method Detail

### init

    public abstract short init(byte[] bArray,
                               short bOff,
                               short bLen)
                        throws TLVException

  Abstract init method. (Re-)Initializes `this` `BERTLV` using the input byte data.

  If `this` is an empty TLV object the initial capacity of `this` `BERTLV` is set based on the size of the input TLV data structure.

  Note:

  - If `bOff+bLen` is greater than `bArray.length`, the length of the `bArray` array, an `ArrayIndexOutOfBoundsException` exception is thrown.

  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 BER TLV or the input data represents a primitive BER TLV structure and `this` is a `ConstructedBERTLV` object or the input data represents a constructed BER TLV structure and `this` is a `PrimiitveBERTLV` object.

### getInstance

    public static BERTLV getInstance(byte[] bArray,
                                     short bOff,
                                     short bLen)
                              throws TLVException

  Creates the `BERTLV` using the input binary data. The resulting BER TLV object may be a primitive or a constructed TLV object. The object must be cast to the correct sub-class: `ConstructedBERTLV` or `PrimitiveBERTLV` to access the specialized API. The `init( byte[] bArray, short bOff, short bLen )` methods of the appropriate `BERTLV` classes will be used to initialize the created TLV object.

  Note:

  - If `bOff+bLen` is greater than `bArray.length`, the length of the `bArray` array, an `ArrayIndexOutOfBoundsException` exception is thrown.

  Parameters:
    `bArray` - input byte array
    `bOff` - offset within byte array containing the tlv data
    `bLen` - byte length of input data
  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 TLV structure requested is larger than the supported maximum size
    - `TLVException.MALFORMED_TLV` if the input data is not a well-formed BER TLV.

### toBytes

    public short toBytes(byte[] outBuf,
                         short bOff)

  Writes `this` TLV structure to the specified byte array.

  Parameters:
    `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 output array would cause access of data outside array bounds, or if the array offset parameter is negative
    `NullPointerException` - if `outBuf` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_SIZE_GREATER_THAN_32767` if the size of the BER TLV is > 32767.
    - `TLVException.EMPTY_TLV` if the `BERTLV` object is empty.

### getTag

    public BERTag getTag()
                  throws TLVException

  Returns `this` value of the TLV object's Tag component

  Returns:
    the Tag for `this` `BERTLV` object
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.EMPTY_TLV` if the `BERTLV` object is empty.

### getLength

    public short getLength()
                    throws TLVException

  Returns the value of `this` TLV object's Length component

  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_LENGTH_GREATER_THAN_32767` if the value of the Length component is > 32767.
    - `TLVException.EMPTY_TLV` if the `BERTLV` object is empty.

### size

    public short size()

  Returns the number of bytes required to represent `this` TLV structure

  Returns:
    the byte length of the TLV
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_SIZE_GREATER_THAN_32767` if the size of TLV structure is > 32767.
    - `TLVException.EMPTY_TLV` if the `BERTLV` object is empty.

### verifyFormat

    public static boolean verifyFormat(byte[] berTlvArray,
                                       short bOff,
                                       short bLen)

  Checks if the input data is a well-formed BER TLV representation.

  Note:

  - If `bOff+bLen` is greater than `berTlvArray.length`, the length of the `berTlvArray` array, an `ArrayIndexOutOfBoundsException` exception is thrown.

  Parameters:
    `berTlvArray` - input byte array
    `bOff` - offset within byte array containing first byte
    `bLen` - byte length of input BER TLV data
  Returns:
    `true` if input data is a well formed BER TLV structure, `false` otherwise
  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 `berTlvArray` is `null`

### getTag

    public static short getTag(byte[] berTLVArray,
                               short bTLVOff,
                               byte[] berTagArray,
                               short bTagOff)
                        throws TLVException

  Copies the tag component in the TLV representation in the specified input byte array to the specified output byte array

  Parameters:
    `berTLVArray` - input byte array
    `bTLVOff` - offset within byte array containing the tlv data
    `berTagArray` - output Tag byte array
    `bTagOff` - offset within byte array where output begins
  Returns:
    the size of the output BER Tag
  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 `berTLVArray` or `berTagArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.ILLEGAL_SIZE` if the size of the Tag component is > 32767.
    - `TLVException.MALFORMED_TLV` if the input data is not a well-formed BER TLV.

### getLength

    public static short getLength(byte[] berTLVArray,
                                  short bOff)
                           throws TLVException

  Returns the value of the TLV Structure's Length component in the specified input byte array

  Parameters:
    `berTLVArray` - input byte array
    `bOff` - offset within byte array containing the tlv data
  Returns:
    the length value in the TLV representation in the specified byte array
  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 `berTLVArray`
    `TLVException` - with the following reason codes:
    - `TLVException.TLV_LENGTH_GREATER_THAN_32767` if the length element(L) > 32767.
    - `TLVException.MALFORMED_TLV` if the input data is not a well-formed BER TLV.

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.