public final class JCSystem extends Object
JCSystem
class includes a collection of methods to control
applet execution, resource management, atomic transaction management, object
deletion mechanism and inter-applet object sharing in the Java Card
environment. All methods in JCSystem
class are static methods.
This class also includes methods to control the persistence and transience of objects. The term persistent means that objects and their values persist from one CAD session to the next, indefinitely. Persistent object values are updated atomically using transactions.
The makeTransient...Array()
methods can be used to create
transient arrays. Transient array data is lost (in an undefined
state, but the real data is unavailable) immediately upon power loss, and is
reset to the default value at the occurrence of certain events such as card
reset or deselect. Updates to the values of transient arrays are not atomic
and are not affected by transactions.
The Java Card runtime environment maintains an atomic transaction commit
buffer which is initialized on card reset (or power on). When a transaction
is in progress, the Java Card runtime environment journals all updates to
persistent data space into this buffer so that it can always guarantee, at
commit time, that everything in the buffer is written or nothing at all is
written. The JCSystem
includes methods to control an atomic
transaction. See
Runtime Environment Specification, Java Card Platform, Classic Edition for
details.
SystemException
,
TransactionException
,
Applet
Modifier and Type | Field and Description |
---|---|
static byte |
ARRAY_TYPE_BOOLEAN
Constant to indicate boolean array type.
|
static byte |
ARRAY_TYPE_BYTE
Constant to indicate byte array type.
|
static byte |
ARRAY_TYPE_INT
Constant to indicate int array type.
|
static byte |
ARRAY_TYPE_OBJECT
Constant to indicate object array type.
|
static byte |
ARRAY_TYPE_SHORT
Constant to indicate short array type.
|
static byte |
CLEAR_ON_DESELECT
This event code indicates that the contents of the transient object are
cleared to the default value on applet deselection event or in
CLEAR_ON_RESET cases. |
static byte |
CLEAR_ON_RESET
This event code indicates that the contents of the transient object are
cleared to the default value on card reset (or power on) event.
|
static byte |
MEMORY_TYPE_PERSISTENT
Constant to indicate persistent memory type.
|
static byte |
MEMORY_TYPE_TRANSIENT_DESELECT
Constant to indicate transient memory of CLEAR_ON_DESELECT type.
|
static byte |
MEMORY_TYPE_TRANSIENT_RESET
Constant to indicate transient memory of CLEAR_ON_RESET type.
|
static byte |
NOT_A_TRANSIENT_OBJECT
This event code indicates that the object is not transient.
|
Modifier and Type | Method and Description |
---|---|
static void |
abortTransaction()
Aborts the atomic transaction.
|
static void |
beginTransaction()
Begins an atomic transaction.
|
static void |
commitTransaction()
Commits an atomic transaction.
|
static AID |
getAID()
Returns the Java Card runtime environment-owned instance of the
AID object associated with the current applet context, or
null if the Applet.register() method has
not yet been invoked. |
static Shareable |
getAppletShareableInterfaceObject(AID serverAID,
byte parameter)
Called by a client applet to get a server applet's shareable interface
object.
|
static byte |
getAssignedChannel()
This method is called to obtain the logical channel number assigned to
the currently selected applet instance.
|
static short |
getAvailableMemory(byte memoryType)
Obtains the amount of memory of the specified type that is available to
the applet.
|
static void |
getAvailableMemory(short[] buffer,
short offset,
byte memoryType)
Obtains the amount of memory of the specified type that is available to
the applet.
|
static short |
getMaxCommitCapacity()
Returns the total number of bytes in the commit buffer.
|
static AID |
getPreviousContextAID()
Obtains the Java Card runtime environment-owned instance of the
AID object associated with the previously active applet
context. |
static byte |
getTransactionDepth()
Returns the current transaction nesting depth level.
|
static short |
getUnusedCommitCapacity()
Returns the number of bytes left in the commit buffer.
|
static short |
getVersion()
Returns the current major and minor version of the Java Card API.
|
static boolean |
isAppletActive(AID theApplet)
This method is used to determine if the specified applet is active on the
card.
|
static boolean |
isObjectDeletionSupported()
This method is used to determine if the implementation for the Java Card
platform supports the object deletion mechanism.
|
static byte |
isTransient(Object theObj)
Checks if the specified object is transient.
|
static AID |
lookupAID(byte[] buffer,
short offset,
byte length)
Returns the Java Card runtime environment-owned instance of the
AID object, if any, encapsulating the specified AID bytes
in the buffer parameter if there exists a successfully
installed applet on the card whose instance AID exactly matches that of
the specified AID bytes. |
static Object |
makeGlobalArray(byte type,
short length)
Creates a global
CLEAR_ON_RESET transient array of
the type specified, with the specified array length. |
static boolean[] |
makeTransientBooleanArray(short length,
byte event)
Creates a transient boolean array with the specified array length.
|
static byte[] |
makeTransientByteArray(short length,
byte event)
Creates a transient byte array with the specified array length.
|
static Object[] |
makeTransientObjectArray(short length,
byte event)
Creates a transient array of
Object with the specified
array length. |
static short[] |
makeTransientShortArray(short length,
byte event)
Creates a transient short array with the specified array length.
|
static void |
requestObjectDeletion()
This method is invoked by the applet to trigger the object deletion
service of the Java Card runtime environment.
|
public static final byte MEMORY_TYPE_PERSISTENT
public static final byte MEMORY_TYPE_TRANSIENT_RESET
public static final byte MEMORY_TYPE_TRANSIENT_DESELECT
public static final byte ARRAY_TYPE_BOOLEAN
public static final byte ARRAY_TYPE_BYTE
public static final byte ARRAY_TYPE_SHORT
public static final byte ARRAY_TYPE_INT
public static final byte ARRAY_TYPE_OBJECT
public static final byte NOT_A_TRANSIENT_OBJECT
public static final byte CLEAR_ON_RESET
public static final byte CLEAR_ON_DESELECT
CLEAR_ON_RESET
cases.
Notes:
CLEAR_ON_DESELECT
transient objects can be accessed only when the applet
which created the object is in the same context as the currently selected applet.
SecurityException
if a
CLEAR_ON_DESELECT
transient
object is accessed when the currently selected applet is not in the same context as
the applet which created the object.
public static byte isTransient(Object theObj)
This method returns a constant indicator as follows :
MEMORY_TYPE_TRANSIENT_RESET
if the specified object
is a CLEAR_ON_RESET
transient array created by
one of the makeTransient...Array
methods using a
CLEAR_ON_RESET
event code.
MEMORY_TYPE_TRANSIENT_DESELECT
if the specified object
is a CLEAR_ON_DESELECT
transient array created by
one of the makeTransient...Array
methods using a
CLEAR_ON_DESELECT
event code.
NOT_A_TRANSIENT_OBJECT
for all other objects.
theObj
- the object being queriedNOT_A_TRANSIENT_OBJECT
,
CLEAR_ON_RESET
, or CLEAR_ON_DESELECT
makeTransientBooleanArray(short, byte)
,
makeTransientByteArray(short,
byte)
,
makeTransientShortArray(short,
byte)
,
makeTransientObjectArray(short, byte)
,
javacardx.framework.util.intx.JCint.makeTransientIntArray(short,
byte)
public static boolean[] makeTransientBooleanArray(short length, byte event) throws NegativeArraySizeException, SystemException
length
- the length of the boolean arrayevent
- the CLEAR_ON...
event which causes the array
elements to be clearedNegativeArraySizeException
- if the length
parameter is negativeSystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if event
is not a valid event code.
SystemException.NO_TRANSIENT_SPACE
if
sufficient transient space is not available.
SystemException.ILLEGAL_TRANSIENT
if
the current applet context is not the currently selected
applet context and CLEAR_ON_DESELECT
is
specified.
public static byte[] makeTransientByteArray(short length, byte event) throws NegativeArraySizeException, SystemException
length
- the length of the byte arrayevent
- the CLEAR_ON...
event which causes the array
elements to be clearedNegativeArraySizeException
- if the length
parameter is negativeSystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if event
is not a valid event code.
SystemException.NO_TRANSIENT_SPACE
if
sufficient transient space is not available.
SystemException.ILLEGAL_TRANSIENT
if
the current applet context is not the currently selected
applet context and CLEAR_ON_DESELECT
is
specified.
public static short[] makeTransientShortArray(short length, byte event) throws NegativeArraySizeException, SystemException
length
- the length of the short arrayevent
- the CLEAR_ON...
event which causes the array
elements to be clearedNegativeArraySizeException
- if the length
parameter is negativeSystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if event
is not a valid event code.
SystemException.NO_TRANSIENT_SPACE
if
sufficient transient space is not available.
SystemException.ILLEGAL_TRANSIENT
if
the current applet context is not the currently selected
applet context and CLEAR_ON_DESELECT
is
specified.
public static Object[] makeTransientObjectArray(short length, byte event) throws NegativeArraySizeException, SystemException
Object
with the specified
array length.length
- the length of the Object
arrayevent
- the CLEAR_ON...
event which causes the array
elements to be clearedNegativeArraySizeException
- if the length
parameter is negativeSystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if event
is not a valid event code.
SystemException.NO_TRANSIENT_SPACE
if
sufficient transient space is not available.
SystemException.ILLEGAL_TRANSIENT
if
the current applet context is not the currently selected
applet context and CLEAR_ON_DESELECT
is
specified.
public static Object makeGlobalArray(byte type, short length)
CLEAR_ON_RESET
transient array of
the type specified, with the specified array length.
A global array can be accessed from any applet context. References to global arrays cannot be stored in class variables or instance variables or array components. (See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.2 for details)
type
- the array type - must be one of : ARRAY_TYPE_BOOLEAN
,
ARRAY_TYPE_BYTE
, ARRAY_TYPE_SHORT
,
ARRAY_TYPE_INT
, or ARRAY_TYPE_OBJECT
length
- the length of the global transient arrayNegativeArraySizeException
- if the length
parameter is negativeSystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if type
is not a valid type code. An implementation which does not
support the "int" type may throw this exception if
type is ARRAY_TYPE_INT
SystemException.NO_TRANSIENT_SPACE
if
sufficient transient space is not available.
ARRAY_TYPE_BOOLEAN
,
ARRAY_TYPE_BYTE
,
ARRAY_TYPE_SHORT
,
ARRAY_TYPE_INT
,
ARRAY_TYPE_OBJECT
public static short getVersion()
public static AID getAID()
AID
object associated with the current applet context, or
null
if the Applet.register()
method has
not yet been invoked.
Java Card runtime environment-owned instances of AID
are
permanent Java Card runtime environment Entry Point Objects and can be
accessed from any applet context. References to these permanent objects
can be stored and re-used.
See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
In addition to returning anObject
reference 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.AID
objectpublic static AID lookupAID(byte[] buffer, short offset, byte length)
AID
object, if any, encapsulating the specified AID bytes
in the buffer
parameter if there exists a successfully
installed applet on the card whose instance AID exactly matches that of
the specified AID bytes.
Java Card runtime environment-owned instances of AID
are
permanent Java Card runtime environment Entry Point Objects and can be
accessed from any applet context. References to these permanent objects
can be stored and re-used.
See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
In addition to returning anObject
reference 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.buffer
- byte array containing the AID bytesoffset
- offset within buffer where AID bytes beginlength
- length of AID bytes in bufferAID
object, if any; null
otherwise. A VM exception is thrown if buffer
is
null
, or if offset
or
length
are out of range.public static void beginTransaction() throws TransactionException
Note:
Applet.register()
method has not yet been invoked. In case of tear or failure prior to successful
registration, the Java Card runtime environment will roll back all atomically updated persistent state.
TransactionException
- with the following reason codes:
TransactionException.IN_PROGRESS
if a
transaction is already in progress.
commitTransaction()
,
abortTransaction()
public static void abortTransaction() throws TransactionException
Note:
Applet.register()
method has not yet been invoked. In case of tear or failure prior to successful
registration, the Java Card runtime environment will roll back all atomically updated persistent state.
null
reference.
TransactionException
- with the following reason codes:
TransactionException.NOT_IN_PROGRESS
if a transaction is not in progress.
beginTransaction()
,
commitTransaction()
public static void commitTransaction() throws TransactionException
Note:
Applet.register()
method has not yet been invoked. In case of tear or failure prior to successful
registration, the Java Card runtime environment will roll back all atomically updated persistent state.
TransactionException
- with the following reason codes:
TransactionException.NOT_IN_PROGRESS
if a transaction is not in progress.
beginTransaction()
,
abortTransaction()
public static byte getTransactionDepth()
public static short getUnusedCommitCapacity()
Note:
getMaxCommitCapacity()
public static short getMaxCommitCapacity()
Note:
getUnusedCommitCapacity()
public static AID getPreviousContextAID()
AID
object associated with the previously active applet
context. This method is typically used by a server applet, while
executing a shareable interface method to determine the identity of its
client and thereby control access privileges.
Java Card runtime environment-owned instances of AID
are
permanent Java Card runtime environment Entry Point Objects and can be
accessed from any applet context. References to these permanent objects
can be stored and re-used.
See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
In addition to returning anObject
reference 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.AID
object of the previous context, or
null
if Java Card runtime environmentpublic static short getAvailableMemory(byte memoryType) throws SystemException
Notes:
memoryType
- the type of memory being queried. One of the
MEMORY_TYPE_*
constants defined above, for example
MEMORY_TYPE_PERSISTENT
.SystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if
memoryType
is not a valid memory type.
getAvailableMemory(short[], short, byte)
public static void getAvailableMemory(short[] buffer, short offset, byte memoryType) throws SystemException
Notes:
memoryType
- the type of memory being queried. One of the
MEMORY_TYPE_*
constants defined above, for example
MEMORY_TYPE_PERSISTENT
.buffer
- the output buffer for storing memory size informationoffset
- the offset within the buffer where memory size
information beginsArrayIndexOutOfBoundsException
- if buffer[offset] or buffer[offset+1] outside array boundsNullPointerException
- if buffer is null
SystemException
- with the following reason codes:
SystemException.ILLEGAL_VALUE
if
memoryType
is not a valid memory type.
public static Shareable getAppletShareableInterfaceObject(AID serverAID, byte parameter)
This method returns null
if:
Applet.register()
has not yet been invokedserverAID
parameter is null
or the server applet does not existnull
Object
reference 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.serverAID
- the AID of the server appletparameter
- optional parameter datanull
SecurityException
- if the server applet is not multiselectable and is
currently active on another logical channel
Applet.getShareableInterfaceObject(AID, byte)
public static boolean isObjectDeletionSupported()
true
if the object deletion mechanism is
supported, false
otherwisepublic static void requestObjectDeletion() throws SystemException
Applet.process()
method. The object deletion mechanism
must ensure that :
Applet.process()
method.
CLEAR_ON_DESELECT
or
CLEAR_ON_RESET
transient object owned by the current
applet context is deleted and the associated space is recovered for reuse
before the next card reset session.
SystemException
- with the following reason codes:
SystemException.ILLEGAL_USE
if the
object deletion mechanism is not implemented.
public static byte getAssignedChannel()
Applet.select()
, Applet.deselect(
),
MultiSelectable.select(boolean)
and
MultiSelectable.deselect(boolean)
methods during MANAGE
CHANNEL APDU command processing, the logical channel number returned may
be different.public static boolean isAppletActive(AID theApplet)
Note:
false
if the specified applet is
not active, even if its context is active.
false
if the specified applet has
not successfully registered via Applet.register
.
true
even in the Applet.install
, and
Applet.select
methods.
theApplet
- the AID of the applet object being queriedtrue
if and only if the applet specified by the
AID parameter is currently active on this or another logical
channellookupAID(
byte[] buffer, short offset, byte length )
Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms