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

    java.lang.Object
      javacardx.framework.tlv.BERTag

Direct Known Subclasses:
  ConstructedBERTag, PrimitiveBERTag

    @TransactionType(value=SUPPORTS)
    public abstract class BERTag

extends Object

The abstract `BERTag` class encapsulates a BER TLV tag. The rules on the allowed encoding of the Tag field are based on the ASN.1 BER encoding rules of ISO/IEC 8825-1:2002.

The `BERTag` class and the subclasses `ConstructedBERTag` and `PrimitiveBERTag`, also provide static methods to parse or edit a BER Tag structure representation in a byte array.

Since:
  2.2.2

Field Summary
`static byte` | `BER_TAG_CLASS_MASK_APPLICATION` Constant for BER Tag Class Application
`static byte` | `BER_TAG_CLASS_MASK_CONTEXT_SPECIFIC` Constant for BER Tag Class Context-Specific
`static byte` | `BER_TAG_CLASS_MASK_PRIVATE` Constant for BER Tag Class Private
`static byte` | `BER_TAG_CLASS_MASK_UNIVERSAL` Constant for BER Tag Class Universal
`static boolean` | `BER_TAG_TYPE_CONSTRUCTED` Constant for constructed BER Tag type
`static boolean` | `BER_TAG_TYPE_PRIMITIVE` Constant for primitive BER Tag type

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

Method Summary
`boolean` | `equals(BERTag otherTag)` Compares `this` BER Tag with another.
`static BERTag` | `getInstance(byte[] bArray, short bOff)` Create a `BERTLV` Tag object from the binary representation in the byte array.
`abstract void` | `init(byte[] bArray, short bOff)` Abstract init method.
`boolean` | `isConstructed()` Used to query if `this` BER tag structure is constructed
`static boolean` | `isConstructed(byte[] berTagArray, short bOff)` Returns the constructed flag part of the BER Tag from its representation in the specified byte array
`byte` | `size()` Returns the byte size required to represent `this` tag structure
`static byte` | `size(byte[] berTagArray, short bOff)` Returns the byte size required to represent the BER Tag from its representation in the specified byte array
`byte` | `tagClass()` Returns the tag class part of `this` BER Tag structure
`static byte` | `tagClass(byte[] berTagArray, short bOff)` Returns the tag class part of the BER Tag from its representation in the specified byte array
`short` | `tagNumber()` Returns the tag number part of `this` BER Tag structure
`static short` | `tagNumber(byte[] berTagArray, short bOff)` Returns the tag number part of the BER Tag from its representation in the specified byte array
`short` | `toBytes(byte[] outBuf, short bOffset)` Writes the representation of `this` BER tag structure to the byte array
`static short` | `toBytes(short tagClass, boolean isConstructed, short tagNumber, byte[] outArray, short bOff)` Writes the BER Tag bytes representing the specified tag class, constructed flag and the tag number as a BER Tag representation in the specified byte array
`static boolean` | `verifyFormat(byte[] berTagArray, short bOff)` Checks if the input data is a well-formed BER Tag representation

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

Field Detail

### BER_TAG_CLASS_MASK_UNIVERSAL

    public static final byte BER_TAG_CLASS_MASK_UNIVERSAL

  Constant for BER Tag Class Universal

  See Also:
    Constant Field Values

### BER_TAG_CLASS_MASK_APPLICATION

    public static final byte BER_TAG_CLASS_MASK_APPLICATION

  Constant for BER Tag Class Application

  See Also:
    Constant Field Values

### BER_TAG_CLASS_MASK_CONTEXT_SPECIFIC

    public static final byte BER_TAG_CLASS_MASK_CONTEXT_SPECIFIC

  Constant for BER Tag Class Context-Specific

  See Also:
    Constant Field Values

### BER_TAG_CLASS_MASK_PRIVATE

    public static final byte BER_TAG_CLASS_MASK_PRIVATE

  Constant for BER Tag Class Private

  See Also:
    Constant Field Values

### BER_TAG_TYPE_CONSTRUCTED

    public static final boolean BER_TAG_TYPE_CONSTRUCTED

  Constant for constructed BER Tag type

  See Also:
    Constant Field Values

### BER_TAG_TYPE_PRIMITIVE

    public static final boolean BER_TAG_TYPE_PRIMITIVE

  Constant for primitive BER Tag type

  See Also:
    Constant Field Values

Constructor Detail

### BERTag

    protected BERTag()

  Constructor creates an empty `BERTLV` Tag object capable of encapsulating a BER TLV Tag. All implementations must support at least 3 byte Tags which can encode tag numbers up to 0x3FFF.

Method Detail

### init

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

  Abstract init method. (Re-)Initialize `this` `BERTag` object from the binary representation in the byte array. All implementations must support tag numbers up to 0x3FFF.

  Parameters:
    `bArray` - the byte array containing the binary representation
    `bOff` - the offset within bArray where the tag binary begins
  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 `bArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.ILLEGAL_SIZE` if the tag number requested is larger than the supported maximum size
    - `TLVException.MALFORMED_TAG` if tag representation in the byte array is malformed

### getInstance

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

  Create a `BERTLV` Tag object from the binary representation in the byte array. All implementations must support tag numbers up to 0x3FFF. Note that the returned `BERTag` must be cast to the correct subclass: `PrimitiveBERTag` or `ConstructedBERTag` to access their specialized API.

  Parameters:
    `bArray` - the byte array containing the binary representation
    `bOff` - the offset within bArray where the tag binary begins
  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 `bArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.ILLEGAL_SIZE` if the tag number requested is larger than the supported maximum size
    - `TLVException.MALFORMED_TAG` if tag representation in the byte array is malformed.

### size

    public byte size()
              throws TLVException

  Returns the byte size required to represent `this` tag structure

  Returns:
    size of BER Tag in bytes
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.TAG_SIZE_GREATER_THAN_127` if the size of the BER Tag is > 127.
    - `TLVException.EMPTY_TAG` if the BER Tag is empty.

### toBytes

    public short toBytes(byte[] outBuf,
                         short bOffset)
                  throws TLVException

  Writes the representation of `this` BER tag structure to the byte array

  Parameters:
    `outBuf` - the byteArray where the BER tag is written
    `bOffset` - offset within outBuf where BER tag value starts
  Returns:
    size of BER Tag in bytes
  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.EMPTY_TAG` if the BER Tag is empty.

### tagNumber

    public short tagNumber()
                    throws TLVException

  Returns the tag number part of `this` BER Tag structure

  Returns:
    the BER Tag tag number
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.TAG_NUMBER_GREATER_THAN_32767` if the tag number is > 32767.
    - `TLVException.EMPTY_TAG` if the BER Tag is empty.

### isConstructed

    public boolean isConstructed()

  Used to query if `this` BER tag structure is constructed

  Returns:
    `true` if constructed, `false` if primitive
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.EMPTY_TAG` if the BER Tag is empty.

### tagClass

    public byte tagClass()

  Returns the tag class part of `this` BER Tag structure

  Returns:
    the BER Tag class. One of the `BER_TAG_CLASS_MASK_*`.. constants defined above. See `BER_TAG_CLASS_MASK_APPLICATION`.
  Throws:
    `TLVException` - with the following reason codes:
    - `TLVException.EMPTY_TAG` if the BER Tag is empty.

### equals

    public boolean equals(BERTag otherTag)

  Compares `this` BER Tag with another. Note that this method does not throw exceptions. If the parameter `otherTag` is `null`, the method returns `false`

  Returns:
    `true` if the tag data encapsulated are equal, `false` otherwise

### toBytes

    public static short toBytes(short tagClass,
                                boolean isConstructed,
                                short tagNumber,
                                byte[] outArray,
                                short bOff)

  Writes the BER Tag bytes representing the specified tag class, constructed flag and the tag number as a BER Tag representation in the specified byte array

  Parameters:
    `tagClass` - encodes the tag class. Valid codes are the `BER_TAG_CLASS_MASK_*` constants defined above. See `BER_TAG_CLASS_MASK_APPLICATION`.
    `isConstructed` - true if the tag is constructed, false if primitive
    `tagNumber` - is the tag number.
    `outArray` - output byte array
    `bOff` - offset within byte array containing first byte
  Returns:
    size of BER Tag output bytes
  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 `outArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.ILLEGAL_SIZE` if the tag size is larger than the supported maximum size or 32767
    - `TLVException.INVALID_PARAM` if `tagClass` parameter is invalid or if the `tagNumber` parameter is negative

### size

    public static byte size(byte[] berTagArray,
                            short bOff)
                     throws TLVException

  Returns the byte size required to represent the BER Tag from its representation in the specified byte array

  Parameters:
    `berTagArray` - input byte array containing the BER Tag representation
    `bOff` - offset within byte array containing first byte
  Returns:
    size of BER Tag in bytes
  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 `berTagArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.ILLEGAL_SIZE` if the size of the BER Tag is greater than the maximum Tag size supported
    - `TLVException.TAG_SIZE_GREATER_THAN_127` if the size of the BER Tag is > 127.
    - `TLVException.MALFORMED_TAG` if tag representation in the byte array is malformed

### tagNumber

    public static short tagNumber(byte[] berTagArray,
                                  short bOff)
                           throws TLVException

  Returns the tag number part of the BER Tag from its representation in the specified byte array

  Parameters:
    `berTagArray` - input byte array
    `bOff` - offset within byte array containing first byte
  Returns:
    the BER Tag tag number
  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 `berTagArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.ILLEGAL_SIZE` if the size of the BER Tag is greater than the maximum Tag size supported
    - `TLVException.TAG_NUMBER_GREATER_THAN_32767` if the tag number is > 32767.
    - `TLVException.MALFORMED_TAG` if tag representation in the byte array is malformed.

### isConstructed

    public static boolean isConstructed(byte[] berTagArray,
                                        short bOff)

  Returns the constructed flag part of the BER Tag from its representation in the specified byte array

  Parameters:
    `berTagArray` - input byte array
    `bOff` - offset within byte array containing first byte
  Returns:
    `true` if constructed, `false` if primitive
  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 `berTagArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.MALFORMED_TAG` if tag representation in the byte array is malformed.

### tagClass

    public static byte tagClass(byte[] berTagArray,
                                short bOff)

  Returns the tag class part of the BER Tag from its representation in the specified byte array

  Parameters:
    `berTagArray` - input byte array
    `bOff` - offset within byte array containing first byte
  Returns:
    the BER Tag class. One of the `BER_TAG_CLASS_MASK_*`.. constants defined above. See `BER_TAG_CLASS_MASK_APPLICATION`.
  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 `berTagArray` is `null`
    `TLVException` - with the following reason codes:
    - `TLVException.MALFORMED_TAG` if tag representation in the byte array is malformed.

### verifyFormat

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

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

  Parameters:
    `berTagArray` - input byte array
    `bOff` - offset within byte array containing first byte
  Returns:
    `true` if input data is a well formed BER Tag structure of tag size equal to or less than the supported maximum size, `false` otherwise
  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 `berTagArray` is `null`

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.