javacard.framework

Class Util

java.lang.Object

javacard.framework.Util

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(), arrayFill(), 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

Methods

Modifier and Type	Method and Description
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	arrayFill(byte[] bArray, short bOff, short bLen, byte bValue) Fills the byte array beginning at the specified position, for the specified length with the specified byte value.
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

Method Detail

arrayCopy

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.

In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

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

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

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.
• Non atomic array operations on persistent integrity-sensitive arrays created using the SensitiveArrays API are not supported; therefore if the dest array parameter is a persistent integrity-sensitive array a SystemException exception is thrown.

In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

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

SystemException - with the following reason codes:

• ILLEGAL_VALUE if dest is a persistent integrity-sensitive array object.

See Also:

JCSystem.getUnusedCommitCapacity()

arrayFill

public static final short arrayFill(byte[] bArray,
              short bOff,
              short bLen,
              byte bValue)
                             throws ArrayIndexOutOfBoundsException,
                                    NullPointerException

Fills the byte array beginning at the specified position, for the specified length with the specified byte value.

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.
• The bLen parameter is not constrained by the atomic commit capacity limitations.
• The fill operation is subject to atomic commit capacity limitations. If the commit capacity is exceeded, no filling is performed and a TransactionException exception is thrown.

In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

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

TransactionException - if filling would cause the commit capacity to be exceeded

Since:

3.0.5

See Also:

JCSystem.getUnusedCommitCapacity()

arrayFillNonAtomic

public static final short arrayFillNonAtomic(byte[] bArray,
                       short bOff,
                       short bLen,
                       byte bValue)
                                      throws ArrayIndexOutOfBoundsException,
                                             NullPointerException,
                                             SystemException

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 fill 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.
• Non atomic array operations on persistent integrity-sensitive arrays created using the SensitiveArrays API are not supported; therefore if the bArray array parameter is a persistent integrity-sensitive array a SystemException exception is thrown.

In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

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

SystemException - with the following reason codes:

• ILLEGAL_VALUE if bArray is a persistent integrity-sensitive array object.

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.

In addition to returning a byte result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

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

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