javacard.framework
Class JCSystem

java.lang.Object
  javacard.framework.JCSystem

public final class JCSystem

extends Object

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.

See Also:

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

NOT_A_TRANSIENT_OBJECT

public static final byte NOT_A_TRANSIENT_OBJECT

This event code indicates that the object is not transient.

See Also:

Constant Field Values

CLEAR_ON_RESET

public static final 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.

See Also:

Constant Field Values

CLEAR_ON_DESELECT

public static final 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.

Notes:

• CLEAR_ON_DESELECT transient objects can be accessed only when the applet which created the object is the currently the selected applet.
• The JCRE will throw a SecurityException if a CLEAR_ON_DESELECT transient object is accessed when the currently selected applet is not the applet which created the object.

See Also:

Constant Field Values

Method Detail

isTransient

public static byte isTransient(Object theObj)

Used to check if the specified object is transient.

Notes:

This method returns NOT_A_TRANSIENT_OBJECT if the specified object is null or is not an array type.

Parameters:

theObj - the object being queried.

Returns:

NOT_A_TRANSIENT_OBJECT, CLEAR_ON_RESET, or CLEAR_ON_DESELECT.

See Also:

makeTransientBooleanArray(short, byte), makeTransientByteArray(short, byte), makeTransientShortArray(short, byte), makeTransientObjectArray(short, byte)

makeTransientBooleanArray

public static boolean[] makeTransientBooleanArray(short length,
                                                  byte event)
                                           throws SystemException

Create a transient boolean array with the specified array length.

Parameters:

length - the length of the boolean array.

event - the CLEAR_ON... event which causes the array elements to be cleared.

Throws:

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.

makeTransientByteArray

public static byte[] makeTransientByteArray(short length,
                                            byte event)
                                     throws SystemException

Create a transient byte array with the specified array length.

Parameters:

length - the length of the byte array.

event - the CLEAR_ON... event which causes the array elements to be cleared.

Throws:

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.

makeTransientShortArray

public static short[] makeTransientShortArray(short length,
                                              byte event)
                                       throws SystemException

Create a transient short array with the specified array length.

Parameters:

length - the length of the short array.

event - the CLEAR_ON... event which causes the array elements to be cleared.

Throws:

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.

makeTransientObjectArray

public static Object[] makeTransientObjectArray(short length,
                                                byte event)
                                         throws SystemException

Create a transient array of Object with the specified array length.

Parameters:

length - the length of the Object array.

event - the CLEAR_ON... event which causes the array elements to be cleared.

Throws:

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.

getVersion

public static short getVersion()

Returns the current major and minor version of the Java Card API.

Returns:

version number as byte.byte (major.minor)

getAID

public static AID getAID()

Returns the JCRE owned instance of the 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.

Returns:

the AID object.

lookupAID

public 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.

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.

Parameters:

buffer - byte array containing the AID bytes.

offset - offset within buffer where AID bytes begin.

length - length of AID bytes in buffer.

Returns:

the AID object, if any; null otherwise. A VM exception is thrown if buffer is null, or if offset or length are out of range.

beginTransaction

public static void beginTransaction()
                             throws TransactionException

Begins an atomic transaction. If a transaction is already in progress (transactionDepth != 0), a TransactionException is thrown.

Throws:

TransactionException - with the following reason codes:

• TransactionException.IN_PROGRESS if a transaction is already in progress.

See Also:

commitTransaction(), abortTransaction()

abortTransaction

public static void abortTransaction()
                             throws TransactionException

Aborts the atomic transaction. The contents of the commit buffer is discarded.

Notes:

• Do not call this method from within a transaction which creates new objects because the JCRE may not recover the heap space used by the new object instances.
• Do not call this method from within a transaction which creates new objects because the JCRE may, to ensure the security of the card and to avoid heap space loss, lock up the card session to force tear/reset processing.
• The JCRE ensures that any variable of reference type which references an object instantiated from within this aborted transaction is equivalent to a null reference.

Throws:

TransactionException - with the following reason codes:

• TransactionException.NOT_IN_PROGRESS if a transaction is not in progress.

See Also:

beginTransaction(), commitTransaction()

commitTransaction

public static void commitTransaction()
                              throws TransactionException

Commits an atomic transaction. The contents of commit buffer is atomically committed. If a transaction is not in progress (transactionDepth == 0) then a TransactionException is thrown.

Throws:

TransactionException - with the following reason codes:

• TransactionException.NOT_IN_PROGRESS if a transaction is not in progress.

See Also:

beginTransaction(), abortTransaction()

getTransactionDepth

public static byte getTransactionDepth()

Returns the current transaction nesting depth level. At present, only 1 transaction can be in progress at a time.

Returns:

1 if transaction in progress, 0 if not.

getUnusedCommitCapacity

public static short getUnusedCommitCapacity()

Returns the number of bytes left in the commit buffer.

Returns:

the number of bytes left in the commit buffer

See Also:

getMaxCommitCapacity()

getMaxCommitCapacity

public static short getMaxCommitCapacity()

Returns the total number of bytes in the commit buffer. This is approximately the maximum number of bytes of persistent data which can be modified during a transaction. However, the transaction subsystem requires additional bytes of overhead data to be included in the commit buffer, and this depends on the number of fields modified and the implementation of the transaction subsystem. The application cannot determine the actual maximum amount of data which can be modified during a transaction without taking these overhead bytes into consideration.

Returns:

the total number of bytes in the commit buffer

See Also:

getUnusedCommitCapacity()

getPreviousContextAID

public static AID getPreviousContextAID()

This method is called to obtain the JCRE owned instance of the 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.

Returns:

the AID object of the previous context, or null if JCRE.

getAppletShareableInterfaceObject

public static Shareable getAppletShareableInterfaceObject(AID serverAID,
                                                          byte parameter)

This method is called by a client applet to get a server applet's shareable interface object.

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.

Parameters:

serverAID - the AID of the server applet.

parameter - optional parameter data.

Returns:

the shareable interface object or null.

See Also:

Applet.getShareableInterfaceObject(AID, byte)