|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javacard.framework.JCSystem
The JCSystem
class includes a collection of methods to control
applet execution, resource management, atomic transaction management
and inter-applet object sharing in Java Card.
All methods in JCSystem
class are static methods.
The JCSystem 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
with primitive data components.
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 JCRE maintains an atomic transaction commit buffer which is initialized on card reset
(or power on).
When a transaction is in progress, the JCRE 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 Java Card Runtime Environment (JCRE) Specification for details.
SystemException
,
TransactionException
,
Applet
Field Summary | |
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 |
NOT_A_TRANSIENT_OBJECT
This event code indicates that the object is not transient. |
Method Summary | |
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 JCRE owned instance of the AID object associated with
the current applet context. |
static Shareable |
getAppletShareableInterfaceObject(AID serverAID,
byte parameter)
This method is called by a client applet to get a server applet's shareable interface object. |
static short |
getMaxCommitCapacity()
Returns the total number of bytes in the commit buffer. |
static AID |
getPreviousContextAID()
This method is called to obtain the JCRE 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 byte |
isTransient(Object theObj)
Used to check if the specified object is transient. |
static AID |
lookupAID(byte[] buffer,
short offset,
byte length)
Returns the JCRE 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 boolean[] |
makeTransientBooleanArray(short length,
byte event)
Create a transient boolean array with the specified array length. |
static byte[] |
makeTransientByteArray(short length,
byte event)
Create a transient byte array with the specified array length. |
static Object[] |
makeTransientObjectArray(short length,
byte event)
Create a transient array of Object with the specified array length. |
static short[] |
makeTransientShortArray(short length,
byte event)
Create a transient short array with the specified array length. |
Methods inherited from class java.lang.Object |
equals |
Field Detail |
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 the currently the selected applet.
SecurityException
if a
CLEAR_ON_DESELECT
transient
object is accessed when the currently selected applet is not the applet which created the object.
Method Detail |
public static byte isTransient(Object theObj)
Notes:
NOT_A_TRANSIENT_OBJECT
if the specified object is
null
or is not an array type.
theObj
- the object being queried.
NOT_A_TRANSIENT_OBJECT
, CLEAR_ON_RESET
, or CLEAR_ON_DESELECT
.makeTransientBooleanArray(short, byte)
,
makeTransientByteArray(short, byte)
,
makeTransientShortArray(short, byte)
,
makeTransientObjectArray(short, byte)
public static boolean[] makeTransientBooleanArray(short length, byte event) throws SystemException
length
- the length of the boolean array.event
- the CLEAR_ON...
event which causes the array elements to be cleared.
SystemException
- 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 SystemException
length
- the length of the byte array.event
- the CLEAR_ON...
event which causes the array elements to be cleared.
SystemException
- 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 SystemException
length
- the length of the short array.event
- the CLEAR_ON...
event which causes the array elements to be cleared.
SystemException
- 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 SystemException
Object
with the specified array length.
length
- the length of the Object
array.event
- the CLEAR_ON...
event which causes the array elements to be cleared.
SystemException
- 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 getVersion()
public static AID getAID()
AID
object associated with
the current applet context.
Returns null
if the Applet.register()
method
has not yet been invoked.
JCRE owned instances of AID
are permanent JCRE
Entry Point Objects and can be accessed from any applet context.
References to these permanent objects can be stored and re-used.
See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details.
AID
object.public 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.
JCRE owned instances of AID
are permanent JCRE
Entry Point Objects and can be accessed from any applet context.
References to these permanent objects can be stored and re-used.
See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details.
buffer
- byte array containing the AID bytes.offset
- offset within buffer where AID bytes begin.length
- length of AID bytes in buffer.
AID
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
TransactionException
- with the following reason codes:TransactionException.IN_PROGRESS
if a transaction is already in progress.commitTransaction()
,
abortTransaction()
public static void abortTransaction() throws TransactionException
Notes:
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
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()
getMaxCommitCapacity()
public static short getMaxCommitCapacity()
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.
JCRE owned instances of AID
are permanent JCRE
Entry Point Objects and can be accessed from any applet context.
References to these permanent objects can be stored and re-used.
See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details.
AID
object of the previous context, or null
if JCRE.public static Shareable getAppletShareableInterfaceObject(AID serverAID, byte parameter)
This method returns null
if the Applet.register()
has not yet been invoked or
if the server does not exist or if the server returns null
.
serverAID
- the AID of the server applet.parameter
- optional parameter data.
null
.Applet.getShareableInterfaceObject(AID, byte)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |