Class Util
- java.lang.Object
-
- javacard.framework.Util
-
public class Util extends Object
TheUtil
class contains common utility functions. Some of the methods may be implemented as native functions for performance reasons. All methods inUtil
, class are static methods.Some methods of
Util
, namelyarrayCopy()
,arrayCopyNonAtomic()
,arrayFill()
,arrayFillNonAtomic()
andsetShort()
, 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. TheJCSystem
class is used to control the persistence and transience of objects.- See Also:
JCSystem
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method 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.
-
-
-
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
ordestOff
orlength
parameter is negative anArrayIndexOutOfBoundsException
exception is thrown. - If
srcOff+length
is greater thansrc.length
, the length of thesrc
array aArrayIndexOutOfBoundsException
exception is thrown and no copy is performed. - If
destOff+length
is greater thandest.length
, the length of thedest
array anArrayIndexOutOfBoundsException
exception is thrown and no copy is performed. - If
src
ordest
parameter isnull
aNullPointerException
exception is thrown. - If the
src
anddest
arguments refer to the same array object, or if any of these arguments refer to an array view sharing components with the other argument, then the copying is performed as if the components at positionssrcOff
throughsrcOff+length-1
were first copied to a temporary array withlength
components and then the contents of the temporary array were copied into positionsdestOff
throughdestOff+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 theSensitiveResult
class, if supported by the platform.- Parameters:
src
- source byte arraysrcOff
- offset within source byte array to start copy fromdest
- destination byte arraydestOff
- offset within destination byte array to start copy intolength
- byte length to be copied- Returns:
destOff+length
- Throws:
ArrayIndexOutOfBoundsException
- if copying would cause access of data outside array boundsNullPointerException
- if eithersrc
ordest
isnull
TransactionException
- if copying would cause the commit capacity to be exceeded- See Also:
JCSystem.getUnusedCommitCapacity()
- If
-
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
ordestOff
orlength
parameter is negative anArrayIndexOutOfBoundsException
exception is thrown. - If
srcOff+length
is greater thansrc.length
, the length of thesrc
array aArrayIndexOutOfBoundsException
exception is thrown and no copy is performed. - If
destOff+length
is greater thandest.length
, the length of thedest
array anArrayIndexOutOfBoundsException
exception is thrown and no copy is performed. - If
src
ordest
parameter isnull
aNullPointerException
exception is thrown. - If the
src
anddest
arguments refer to the same array object, or if any of these arguments refer to an array view sharing components with the other argument, then the copying is performed as if the components at positionssrcOff
throughsrcOff+length-1
were first copied to a temporary array withlength
components and then the contents of the temporary array were copied into positionsdestOff
throughdestOff+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 thedest
array parameter is a persistent integrity-sensitive array aSystemException
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 theSensitiveResult
class, if supported by the platform.- Parameters:
src
- source byte arraysrcOff
- offset within source byte array to start copy fromdest
- destination byte arraydestOff
- offset within destination byte array to start copy intolength
- byte length to be copied- Returns:
destOff+length
- Throws:
ArrayIndexOutOfBoundsException
- if copying would cause access of data outside array boundsNullPointerException
- if eithersrc
ordest
isnull
SystemException
- with the following reason codes:ILLEGAL_VALUE
ifdest
is a persistent integrity-sensitive array object.
- See Also:
JCSystem.getUnusedCommitCapacity()
- If
-
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
orbLen
parameter is negative anArrayIndexOutOfBoundsException
exception is thrown. - If
bOff+bLen
is greater thanbArray.length
, the length of thebArray
array anArrayIndexOutOfBoundsException
exception is thrown. - If
bArray
parameter isnull
aNullPointerException
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 theSensitiveResult
class, if supported by the platform.- Parameters:
bArray
- the byte arraybOff
- offset within byte array to start filling bValue intobLen
- byte length to be filledbValue
- the value to fill the byte array with- Returns:
bOff+bLen
- Throws:
ArrayIndexOutOfBoundsException
- if the fill operation would cause access of data outside array boundsNullPointerException
- if bArray isnull
TransactionException
- if filling would cause the commit capacity to be exceeded- Since:
- 3.0.5
- See Also:
JCSystem.getUnusedCommitCapacity()
- If
-
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
orbLen
parameter is negative anArrayIndexOutOfBoundsException
exception is thrown. - If
bOff+bLen
is greater thanbArray.length
, the length of thebArray
array anArrayIndexOutOfBoundsException
exception is thrown. - If
bArray
parameter isnull
aNullPointerException
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 thebArray
array parameter is a persistent integrity-sensitive array aSystemException
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 theSensitiveResult
class, if supported by the platform.- Parameters:
bArray
- the byte arraybOff
- offset within byte array to start filling bValue intobLen
- byte length to be filledbValue
- the value to fill the byte array with- Returns:
bOff+bLen
- Throws:
ArrayIndexOutOfBoundsException
- if the fill operation would cause access of data outside array boundsNullPointerException
- if bArray isnull
SystemException
- with the following reason codes:ILLEGAL_VALUE
ifbArray
is a persistent integrity-sensitive array object.
- See Also:
JCSystem.getUnusedCommitCapacity()
- If
-
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
ordestOff
orlength
parameter is negative anArrayIndexOutOfBoundsException
exception is thrown. - If
srcOff+length
is greater thansrc.length
, the length of thesrc
array aArrayIndexOutOfBoundsException
exception is thrown. - If
destOff+length
is greater thandest.length
, the length of thedest
array anArrayIndexOutOfBoundsException
exception is thrown. - If
src
ordest
parameter isnull
aNullPointerException
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 theSensitiveResult
class, if supported by the platform.- Parameters:
src
- source byte arraysrcOff
- offset within source byte array to start comparedest
- destination byte arraydestOff
- offset within destination byte array to start comparelength
- 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 boundsNullPointerException
- if eithersrc
ordest
isnull
- If
-
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 arraybOff
- offset within byte array containing first byte (the high order byte)- Returns:
- the short value the concatenated result
- Throws:
NullPointerException
- if thebArray
parameter isnull
ArrayIndexOutOfBoundsException
- if thebOff
parameter is negative or ifbOff+2
is greater than the length ofbArray
-
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 arraybOff
- 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.
- If the byte array is persistent, this operation is performed atomically.
If the commit capacity is exceeded, no operation is performed and a
- Throws:
TransactionException
- if the operation would cause the commit capacity to be exceededArrayIndexOutOfBoundsException
- if thebOff
parameter is negative or ifbOff+2
is greater than the length ofbArray
NullPointerException
- if thebArray
parameter isnull
- See Also:
JCSystem.getUnusedCommitCapacity()
-
-