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

## javacard.framework
Class Util

    java.lang.Object
      javacard.framework.Util

    @TransactionType(value=SUPPORTS)
    public class Util

extends Object

The `Util` class contains common utility functions. Some of the methods may be implemented as native functions for performance reasons. All methods in `Util`, class are static methods.

Some methods of `Util`, namely `arrayCopy()`, `arrayCopyNonAtomic()`, `arrayFillNonAtomic()` and `setShort()`, refer to the persistence of array objects. The term persistent means that arrays and their values persist from one CAD session to the next, indefinitely. The `JCSystem` class is used to control the persistence and transience of objects.

See Also:
  `JCSystem`

Method Summary
`static byte` | `arrayCompare(byte[] src, short srcOff, byte[] dest, short destOff, short length)` Compares an array from the specified source array, beginning at the specified position, with the specified position of the destination array from left to right.
`static short` | `arrayCopy(byte[] src, short srcOff, byte[] dest, short destOff, short length)` Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array.
`static short` | `arrayCopyNonAtomic(byte[] src, short srcOff, byte[] dest, short destOff, short length)` Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array (non-atomically).
`static short` | `arrayFillNonAtomic(byte[] bArray, short bOff, short bLen, byte bValue)` Fills the byte array (non-atomically) beginning at the specified position, for the specified length with the specified byte value.
`static short` | `getShort(byte[] bArray, short bOff)` Concatenates two bytes in a byte array to form a short value.
`static short` | `makeShort(byte b1, byte b2)` Concatenates the two parameter bytes to form a short value.
`static short` | `setShort(byte[] bArray, short bOff, short sValue)` Deposits the short value as two successive bytes at the specified offset in the byte array.

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

Method Detail

### arrayCopy

    @TransactionType(value=REQUIRED)
    public static final short arrayCopy(byte[] src,
                                                                     short srcOff,
                                                                     byte[] dest,
                                                                     short destOff,
                                                                     short length)
                                 throws ArrayIndexOutOfBoundsException,
                                        NullPointerException,
                                        TransactionException

  Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array.

  Note:

  - If `srcOff` or `destOff` or `length` parameter is negative an `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `srcOff+length` is greater than `src.length`, the length of the `src` array a `ArrayIndexOutOfBoundsException` exception is thrown and no copy is performed.
  - If `destOff+length` is greater than `dest.length`, the length of the `dest` array an `ArrayIndexOutOfBoundsException` exception is thrown and no copy is performed.
  - If `src` or `dest` parameter is `null`
  a `NullPointerException` exception is thrown.
  - If the `src` and `dest` arguments refer to the same array object, then the copying is performed as if the components at positions `srcOff` through `srcOff+length-1` were first copied to a temporary array with `length` components and then the contents of the temporary array were copied into positions `destOff` through `destOff+length-1` of the argument array.
  - If the destination array is persistent, the entire copy is performed atomically.
  - The copy operation is subject to atomic commit capacity limitations. If the commit capacity is exceeded, no copy is performed and a `TransactionException` exception is thrown.

  Parameters:
    `src` - source byte array
    `srcOff` - offset within source byte array to start copy from
    `dest` - destination byte array
    `destOff` - offset within destination byte array to start copy into
    `length` - byte length to be copied
  Returns:
    `destOff+length`
  Throws:
    `ArrayIndexOutOfBoundsException` - if copying would cause access of data outside array bounds
    `NullPointerException` - if either `src` or `dest` is `null`
    `TransactionException` - if copying would cause the commit capacity to be exceeded
  See Also:
    `JCSystem.getUnusedCommitCapacity()`

### arrayCopyNonAtomic

    @TransactionType(value=NOT_SUPPORTED)
    public static final short arrayCopyNonAtomic(byte[] src,
                                                                                   short srcOff,
                                                                                   byte[] dest,
                                                                                   short destOff,
                                                                                   short length)
                                          throws ArrayIndexOutOfBoundsException,
                                                 NullPointerException

  Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array (non-atomically).

  This method does not use the transaction facility during the copy operation even if a transaction is in progress. Thus, this method is suitable for use only when the contents of the destination array can be left in a partially modified state in the event of a power loss in the middle of the copy operation.

  Note:

  - If `srcOff` or `destOff` or `length` parameter is negative an `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `srcOff+length` is greater than `src.length`, the length of the `src` array a `ArrayIndexOutOfBoundsException` exception is thrown and no copy is performed.
  - If `destOff+length` is greater than `dest.length`, the length of the `dest` array an `ArrayIndexOutOfBoundsException` exception is thrown and no copy is performed.
  - If `src` or `dest` parameter is `null` a `NullPointerException` exception is thrown.
  - If the `src` and `dest` arguments refer to the same array object, then the copying is performed as if the components at positions `srcOff` through `srcOff+length-1` were first copied to a temporary array with `length` components and then the contents of the temporary array were copied into positions `destOff` through `destOff+length-1` of the argument array.
  - If power is lost during the copy operation and the destination array is persistent, a partially changed destination array could result.
  - The copy `length` parameter is not constrained by the atomic commit capacity limitations.

  Parameters:
    `src` - source byte array
    `srcOff` - offset within source byte array to start copy from
    `dest` - destination byte array
    `destOff` - offset within destination byte array to start copy into
    `length` - byte length to be copied
  Returns:
    `destOff+length`
  Throws:
    `ArrayIndexOutOfBoundsException` - if copying would cause access of data outside array bounds
    `NullPointerException` - if either `src` or `dest` is `null`
  See Also:
    `JCSystem.getUnusedCommitCapacity()`

### arrayFillNonAtomic

    @TransactionType(value=NOT_SUPPORTED)
    public static final short arrayFillNonAtomic(byte[] bArray,
                                                                                   short bOff,
                                                                                   short bLen,
                                                                                   byte bValue)
                                          throws ArrayIndexOutOfBoundsException,
                                                 NullPointerException

  Fills the byte array (non-atomically) beginning at the specified position, for the specified length with the specified byte value.

  This method does not use the transaction facility during the fill operation even if a transaction is in progress. Thus, this method is suitable for use only when the contents of the byte array can be left in a partially filled state in the event of a power loss in the middle of the fill operation.

  Note:

  - If `bOff` or `bLen` parameter is negative an `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `bOff+bLen` is greater than `bArray.length`, the length of the `bArray` array an `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `bArray` parameter is `null` a `NullPointerException` exception is thrown.
  - If power is lost during the copy operation and the byte array is persistent, a partially changed byte array could result.
  - The `bLen` parameter is not constrained by the atomic commit capacity limitations.

  Parameters:
    `bArray` - the byte array
    `bOff` - offset within byte array to start filling bValue into
    `bLen` - byte length to be filled
    `bValue` - the value to fill the byte array with
  Returns:
    `bOff+bLen`
  Throws:
    `ArrayIndexOutOfBoundsException` - if the fill operation would cause access of data outside array bounds
    `NullPointerException` - if bArray is `null`
  See Also:
    `JCSystem.getUnusedCommitCapacity()`

### arrayCompare

    public static final byte arrayCompare(byte[] src,
                                          short srcOff,
                                          byte[] dest,
                                          short destOff,
                                          short length)
                                   throws ArrayIndexOutOfBoundsException,
                                          NullPointerException

  Compares an array from the specified source array, beginning at the specified position, with the specified position of the destination array from left to right. Returns the ternary result of the comparison : less than(-1), equal(0) or greater than(1).

  Note:

  - If `srcOff` or `destOff` or `length` parameter is negative an `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `srcOff+length` is greater than `src.length`, the length of the `src` array a `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `destOff+length` is greater than `dest.length`, the length of the `dest` array an `ArrayIndexOutOfBoundsException` exception is thrown.
  - If `src` or `dest` parameter is `null` a `NullPointerException` exception is thrown.

  Parameters:
    `src` - source byte array
    `srcOff` - offset within source byte array to start compare
    `dest` - destination byte array
    `destOff` - offset within destination byte array to start compare
    `length` - byte length to be compared
  Returns:
    the result of the comparison as follows:
    - `0` if identical
    - `-1` if the first miscomparing byte in source array is less than that in destination array
    - `1` if the first miscomparing byte in source array is greater that that in destination array
  Throws:
    `ArrayIndexOutOfBoundsException` - if comparing all bytes would cause access of data outside array bounds
    `NullPointerException` - if either `src` or `dest` is `null`

### makeShort

    public static final short makeShort(byte b1,
                                        byte b2)

  Concatenates the two parameter bytes to form a short value.

  Parameters:
    `b1` - the first byte ( high order byte )
    `b2` - the second byte ( low order byte )
  Returns:
    the short value the concatenated result

### getShort

    public static final short getShort(byte[] bArray,
                                       short bOff)
                                throws NullPointerException,
                                       ArrayIndexOutOfBoundsException

  Concatenates two bytes in a byte array to form a short value.

  Parameters:
    `bArray` - byte array
    `bOff` - offset within byte array containing first byte (the high order byte)
  Returns:
    the short value the concatenated result
  Throws:
    `NullPointerException` - if the `bArray` parameter is `null`
    `ArrayIndexOutOfBoundsException` - if the `bOff` parameter is negative or if `bOff+2` is greater than the length of `bArray`

### setShort

    @TransactionType(value=REQUIRED)
    public static final short setShort(byte[] bArray,
                                                                    short bOff,
                                                                    short sValue)
                                throws TransactionException,
                                       NullPointerException,
                                       ArrayIndexOutOfBoundsException

  Deposits the short value as two successive bytes at the specified offset in the byte array.

  Parameters:
    `bArray` - byte array
    `bOff` - offset within byte array to deposit the first byte (the high order byte)
    `sValue` - the short value to set into array.
  Returns:
    `bOff+2`

    Note:

    - If the byte array is persistent, this operation is performed atomically. If the commit capacity is exceeded, no operation is performed and a `TransactionException` exception is thrown.
  Throws:
    `TransactionException` - if the operation would cause the commit capacity to be exceeded
    `ArrayIndexOutOfBoundsException` - if the `bOff` parameter is negative or if `bOff+2` is greater than the length of `bArray`
    `NullPointerException` - if the `bArray` parameter is `null`
  See Also:
    `JCSystem.getUnusedCommitCapacity()`

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.