com.licel.jcardsim.framework

Class JCSystemProxy

java.lang.Object

com.licel.jcardsim.framework.JCSystemProxy

public class JCSystemProxy
extends Object

ProxyClass for JCSystem

See Also:

JCSystem

Constructor Summary

Constructors

Constructor and Description
JCSystemProxy()

Method Summary

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 javacard.framework.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 javacard.framework.Shareable	getAppletShareableInterfaceObject(javacard.framework.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 short	getMaxCommitCapacity() Returns the total number of bytes in the commit buffer.
static javacard.framework.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(javacard.framework.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 javacard.framework.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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JCSystemProxy

public JCSystemProxy()

Method Detail

isTransient

public static byte isTransient(Object theObj)

Checks if the specified object is transient.

Note:

• 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), makeTransientObjectArray(short, byte), makeTransientShortArray(short, byte)

makeTransientBooleanArray

public static boolean[] makeTransientBooleanArray(short length,
                                                  byte event)
                                           throws NegativeArraySizeException,
                                                  javacard.framework.SystemException

Creates 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

Returns:

the new transient boolean array

Throws:

NegativeArraySizeException - if the length parameter is negative

javacard.framework.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 NegativeArraySizeException,
                                            javacard.framework.SystemException

Creates 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

Returns:

the new transient byte array

Throws:

NegativeArraySizeException - if the length parameter is negative

javacard.framework.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 NegativeArraySizeException,
                                              javacard.framework.SystemException

Creates 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

Returns:

the new transient short array

Throws:

NegativeArraySizeException - if the length parameter is negative

javacard.framework.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 NegativeArraySizeException,
                                                javacard.framework.SystemException

Creates 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

Returns:

the new transient Object array

Throws:

NegativeArraySizeException - if the length parameter is negative

javacard.framework.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.

makeGlobalArray

public static Object makeGlobalArray(byte type,
                                     short length)

Creates a global 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)

Parameters:

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 array

Returns:

the new transient Object array

Throws:

NegativeArraySizeException - if the length parameter is negative

javacard.framework.SystemException - 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.

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 javacard.framework.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.

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 for the Java Card Platform, section 6.2.1 for details.

Returns:

the AID object

lookupAID

public static javacard.framework.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.

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 for the Java Card Platform, 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 javacard.framework.TransactionException

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

Note:

• This method may do nothing if the 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.

Throws:

javacard.framework.TransactionException - with the following reason codes:

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

See Also:

abortTransaction(), commitTransaction()

abortTransaction

public static void abortTransaction()
                             throws javacard.framework.TransactionException

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

Note:

• This method may do nothing if the 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.
• Do not call this method from within a transaction which creates new objects because the Java Card runtime environment 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 Java Card runtime environment 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 Java Card runtime environment ensures that any variable of reference type which references an object instantiated from within this aborted transaction is equivalent to a null reference.

Throws:

javacard.framework.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 javacard.framework.TransactionException

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

Note:

• This method may do nothing if the 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.

Throws:

javacard.framework.TransactionException - ith 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.

Note:

• If the number of bytes left in the commit buffer is greater than 32767, then this method returns 32767.

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.

Note:

• If the total number of bytes in the commit buffer is greater than 32767, then this method returns 32767.

Returns:

the total number of bytes in the commit buffer

See Also:

getUnusedCommitCapacity()

getPreviousContextAID

public static javacard.framework.AID getPreviousContextAID()

Obtains the Java Card runtime environment-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.

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 for the Java Card Platform, section 6.2.1 for details.

Returns:

the AID object of the previous context, or null if Java Card runtime environment

getAvailableMemory

public static short getAvailableMemory(byte memoryType)
                                throws javacard.framework.SystemException

Obtains the amount of memory of the specified type that is available to the applet. Note that implementation-dependent memory overhead structures may also use the same memory pool.

Notes:

• The number of bytes returned is only an upper bound on the amount of memory available due to overhead requirements.
• Allocation of CLEAR_ON_RESET transient objects may affect the amount of CLEAR_ON_DESELECT transient memory available.
• Allocation of CLEAR_ON_DESELECT transient objects may affect the amount of CLEAR_ON_RESET transient memory available.
• If the number of available bytes is greater than 32767, then this method returns 32767.
• The returned count is not an indicator of the size of object which may be created since memory fragmentation is possible.

Parameters:

memoryType - the type of memory being queried. One of the MEMORY_TYPE_.. constants defined above

Returns:

the upper bound on available bytes of memory for the specified type

Throws:

javacard.framework.SystemException - with the following reason codes:

• SystemException.ILLEGAL_VALUE if memoryType is not a valid memory type.

getAppletShareableInterfaceObject

public static javacard.framework.Shareable getAppletShareableInterfaceObject(javacard.framework.AID serverAID,
                                                                             byte parameter)

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
• the server does not exist
• 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)

isObjectDeletionSupported

public static boolean isObjectDeletionSupported()

This method is used to determine if the implementation for the Java Card platform supports the object deletion mechanism.

Returns:

true if the object deletion mechanism is supported, false otherwise

requestObjectDeletion

public static void requestObjectDeletion()
                                  throws javacard.framework.SystemException

This method is invoked by the applet to trigger the object deletion service of the Java Card runtime environment. If the Java Card runtime environment implements the object deletion mechanism, the request is merely logged at this time. The Java Card runtime environment must schedule the object deletion service prior to the next invocation of the Applet.process() method. The object deletion mechanism must ensure that :

• Any unreferenced persistent object owned by the current applet context is deleted and the associated space is recovered for reuse prior to the next invocation of the Applet.process() method.
• Any unreferenced 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.

Throws:

javacard.framework.SystemException - with the following reason codes:

• SystemException.ILLEGAL_USE if the object deletion mechanism is not implemented.

getAssignedChannel

public static byte getAssignedChannel()

This method is called to obtain the logical channel number assigned to the currently selected applet instance. The assigned logical channel is the logical channel on which the currently selected applet instance is or will be the active applet instance. This logical channel number is always equal to the origin logical channel number returned by the APDU.getCLAChannel() method except during selection and deselection via the MANAGE CHANNEL APDU command. If this method is called from the 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.

Returns:

the logical channel number in the range 0-3 assigned to the currently selected applet instance

isAppletActive

public static boolean isAppletActive(javacard.framework.AID theApplet)

This method is used to determine if the specified applet is active on the card.

Note:

• This method returns false if the specified applet is not active, even if its context is active.

Parameters:

theApplet - the AID of the applet object being queried

Returns:

true if and only if the applet specified by the AID parameter is currently active on this or another logical channel