Class JCSystem
- java.lang.Object
-
- javacard.framework.JCSystem
-
public final class JCSystem extends Object
TheJCSystem
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 inJCSystem
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.- See Also:
SystemException
,TransactionException
,Applet
-
-
Field Summary
Fields Modifier and Type Field 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 short
ATTR_READABLE_VIEW
Constant to configure an array view with the read attribute.static short
ATTR_WRITABLE_VIEW
Constant to configure an array view with the write attribute.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 inCLEAR_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.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method 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 theAID
object associated with the current applet context, ornull
if theApplet.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
getAttributes(Object view)
Get the attributes of the specified array view.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 theAID
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
isArrayView(Object object)
Check whether the specified object is an array viewstatic 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 theAID
object, if any, encapsulating the specified AID bytes in thebuffer
parameter if there exists a successfully installed applet on the card whose instance AID exactly matches that of the specified AID bytes.static Object
makeArrayView(Object array, short offset, short length, short attributes, Shareable service)
Creates an array which is a view on the specifiedarray
parameter.static boolean[]
makeBooleanArrayView(boolean[] array, short offset, short length, short attributes, Shareable service)
Creates a boolean array which is a view on the specifiedarray
parameter.static byte[]
makeByteArrayView(byte[] array, short offset, short length, short attributes, Shareable service)
Creates a byte array which is a view on the specifiedarray
parameter.static Object
makeGlobalArray(byte type, short length)
Creates a globalCLEAR_ON_RESET
transient array of the type specified, with the specified array length.static short[]
makeShortArrayView(short[] array, short offset, short length, short attributes, Shareable service)
Creates a short array which is a view on the specifiedarray
parameter.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 ofObject
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.
-
-
-
Field Detail
-
MEMORY_TYPE_PERSISTENT
public static final byte MEMORY_TYPE_PERSISTENT
Constant to indicate persistent memory type.- See Also:
- Constant Field Values
-
MEMORY_TYPE_TRANSIENT_RESET
public static final byte MEMORY_TYPE_TRANSIENT_RESET
Constant to indicate transient memory of CLEAR_ON_RESET type.- See Also:
- Constant Field Values
-
MEMORY_TYPE_TRANSIENT_DESELECT
public static final byte MEMORY_TYPE_TRANSIENT_DESELECT
Constant to indicate transient memory of CLEAR_ON_DESELECT type.- See Also:
- Constant Field Values
-
ARRAY_TYPE_BOOLEAN
public static final byte ARRAY_TYPE_BOOLEAN
Constant to indicate boolean array type.- See Also:
- Constant Field Values
-
ARRAY_TYPE_BYTE
public static final byte ARRAY_TYPE_BYTE
Constant to indicate byte array type.- See Also:
- Constant Field Values
-
ARRAY_TYPE_SHORT
public static final byte ARRAY_TYPE_SHORT
Constant to indicate short array type.- See Also:
- Constant Field Values
-
ARRAY_TYPE_INT
public static final byte ARRAY_TYPE_INT
Constant to indicate int array type.- See Also:
- Constant Field Values
-
ARRAY_TYPE_OBJECT
public static final byte ARRAY_TYPE_OBJECT
Constant to indicate object array type.- See Also:
- Constant Field Values
-
ATTR_READABLE_VIEW
public static final short ATTR_READABLE_VIEW
Constant to configure an array view with the read attribute.- Since:
- 3.1
- See Also:
- Constant Field Values
-
ATTR_WRITABLE_VIEW
public static final short ATTR_WRITABLE_VIEW
Constant to configure an array view with the write attribute.- Since:
- 3.1
- See Also:
- Constant Field Values
-
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 inCLEAR_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.- The Java Card runtime environment will throw a
SecurityException
if aCLEAR_ON_DESELECT
transient object is accessed when the currently selected applet is not in the same context as the applet which created the object.
- See Also:
- Constant Field Values
-
-
Method Detail
-
isTransient
public static byte isTransient(Object theObj)
Checks if the specified object is transient.This method returns a constant indicator as follows :
MEMORY_TYPE_TRANSIENT_RESET
if the specified object is aCLEAR_ON_RESET
transient array created by one of themakeTransient...Array
methods using aCLEAR_ON_RESET
event code or a view on such array.MEMORY_TYPE_TRANSIENT_DESELECT
if the specified object is aCLEAR_ON_DESELECT
transient array created by one of themakeTransient...Array
methods using aCLEAR_ON_DESELECT
event code or a view on such array.NOT_A_TRANSIENT_OBJECT
for all other objects.
- Parameters:
theObj
- the object being queried- Returns:
NOT_A_TRANSIENT_OBJECT
,CLEAR_ON_RESET
, orCLEAR_ON_DESELECT
- See Also:
makeTransientBooleanArray(short, byte)
,makeTransientByteArray(short, byte)
,makeTransientShortArray(short, byte)
,makeTransientObjectArray(short, byte)
,javacardx.framework.util.intx.JCint.makeTransientIntArray(short, byte)
-
makeTransientBooleanArray
public static boolean[] makeTransientBooleanArray(short length, byte event) throws NegativeArraySizeException, SystemException
Creates a transient boolean array with the specified array length.- Parameters:
length
- the length of the boolean arrayevent
- theCLEAR_ON...
event which causes the array elements to be cleared- Returns:
- the new transient boolean array
- Throws:
NegativeArraySizeException
- if thelength
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 andCLEAR_ON_DESELECT
is specified.
-
makeTransientByteArray
public static byte[] makeTransientByteArray(short length, byte event) throws NegativeArraySizeException, SystemException
Creates a transient byte array with the specified array length.- Parameters:
length
- the length of the byte arrayevent
- theCLEAR_ON...
event which causes the array elements to be cleared- Returns:
- the new transient byte array
- Throws:
NegativeArraySizeException
- if thelength
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 andCLEAR_ON_DESELECT
is specified.
-
makeTransientShortArray
public static short[] makeTransientShortArray(short length, byte event) throws NegativeArraySizeException, SystemException
Creates a transient short array with the specified array length.- Parameters:
length
- the length of the short arrayevent
- theCLEAR_ON...
event which causes the array elements to be cleared- Returns:
- the new transient short array
- Throws:
NegativeArraySizeException
- if thelength
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 andCLEAR_ON_DESELECT
is specified.
-
makeTransientObjectArray
public static Object[] makeTransientObjectArray(short length, byte event) throws NegativeArraySizeException, SystemException
Creates a transient array ofObject
with the specified array length.- Parameters:
length
- the length of theObject
arrayevent
- theCLEAR_ON...
event which causes the array elements to be cleared- Returns:
- the new transient Object array
- Throws:
NegativeArraySizeException
- if thelength
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 andCLEAR_ON_DESELECT
is specified.
-
makeGlobalArray
public static Object makeGlobalArray(byte type, short length)
Creates a globalCLEAR_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
, orARRAY_TYPE_OBJECT
length
- the length of the global transient array- Returns:
- the new transient Object array
- Throws:
NegativeArraySizeException
- if thelength
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 isARRAY_TYPE_INT
SystemException.NO_TRANSIENT_SPACE
if sufficient transient space is not available.
- Since:
- 3.0.4
- See Also:
ARRAY_TYPE_BOOLEAN
,ARRAY_TYPE_BYTE
,ARRAY_TYPE_SHORT
,ARRAY_TYPE_INT
,ARRAY_TYPE_OBJECT
-
makeArrayView
public static Object makeArrayView(Object array, short offset, short length, short attributes, Shareable service)
Creates an array which is a view on the specifiedarray
parameter. The elements of the created array have the same type and are mapped to the corresponding elements in the parent array. Any change in the parent array will be visible in the view and vice versa.The layout attributes (transient, persistent, sensitive) of the created array are identical to the
array
parameter ones.
In addition, it is possible to create read-only, write-only or R/W views using combinations (bitwise inclusive OR) of the following access attributes:ATTR_READABLE_VIEW
: the elements of the view can be read. If this attribute is not set, any attempt to read elements from the created view will throw aSecurityException
ATTR_WRITABLE_VIEW
: the elements of the view can be modified and changes are visible in the actual array and any other view on it. If this attribute is not set, any attempt to write elements in the created view will throw aSecurityException
The attributes requested for the view shall remain consistent with the attributes of the
array
parameter:- Any attempt to create a view with the
ATTR_READABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not readable. - Any attempt to create a view with the
ATTR_WRITABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not writable.
The created view is temporary and any attempt to store the reference into a class or instance field or in array elements will throw a
SecurityException
Example:
// creates a R/W view of 5 bytes on array, starting at offset 4 byte[] view = (byte[]) JCSystem.makeArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), null);
Note:
If theservice
parameter is non-null
, the method returns an object created in the context of the specifiedservice
and should be used as parameter when calling methods of thisservice
. Other operations executed in current context, including casting, will throw aSecurityException
.- Parameters:
array
- the array on which to create the view (either an actual array or a view)offset
- the offset in thearray
where the view startslength
- the number of elements in the viewattributes
- the view access attributes (combinations ofATTR_READABLE_VIEW
andATTR_WRITABLE_VIEW
attributes)service
- the shareable object identifying the recipient context of the new view. Ifnull
, the view will remain in the current context. If non-null
, the method returns an object created in the context of the specifiedservice
and should be used as parameter when calling methods of thisservice
. Other operations executed in current context, including casting, will throw aSecurityException
.- Returns:
- a view on the specified
array
parameter - Throws:
NullPointerException
- if thearray
parameter isnull
NegativeArraySizeException
- if thelength
parameter is negativeSecurityException
-- if the
array
cannot be accessed from current context - if requesting access attributes that were not available for
the
array
parameter
- if the
SystemException
- with the following reason code:SystemException.ILLEGAL_VALUE
if thearray
parameter is not an arraySystemException.NO_RESOURCE
if not enough resources to allocate the view
ArrayIndexOutOfBoundsException
- if the view would cause access of data outside array bounds- Since:
- 3.1
- See Also:
makeBooleanArrayView(boolean[], short, short, short, Shareable)
,makeByteArrayView(byte[], short, short, short, Shareable)
,makeShortArrayView(short[], short, short, short, Shareable)
-
makeBooleanArrayView
public static boolean[] makeBooleanArrayView(boolean[] array, short offset, short length, short attributes, Shareable service)
Creates a boolean array which is a view on the specifiedarray
parameter. The elements of the created array are mapped to the corresponding elements in the parent array. Any change in the parent array will be visible in the view and vice versa.The layout attributes (transient, persistent, sensitive) of the created array are identical to the
array
parameter ones.
In addition, it is possible to create read-only, write-only or R/W views using combinations (bitwise inclusive OR) of the following access attributes:ATTR_READABLE_VIEW
: the elements of the view can be read. If this attribute is not set, any attempt to read elements from the created view will throw aSecurityException
ATTR_WRITABLE_VIEW
: the elements of the view can be modified and changes are visible in the actual array and any other view on it. If this attribute is not set, any attempt to write elements in the created view will throw aSecurityException
The attributes requested for the view shall remain consistent with the attributes of the
array
parameter:- Any attempt to create a view with the
ATTR_READABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not readable. - Any attempt to create a view with the
ATTR_WRITABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not writable.
The created view is temporary and any attempt to store the reference into a class or instance field or in array elements will throw a
SecurityException
Example:
// creates a R/W view of 5 boolean on array, starting at offset 4 boolean[] view = JCSystem.makeBooleanArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), null); // creates a view in the service context and share it with the service boolean[] view = JCSystem.makeBooleanArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), service); service.execute(view);
- Parameters:
array
- the array on which to create the view (either an actual array or a view)offset
- the offset in thearray
where the view startslength
- the number of elements in the viewattributes
- the view access attributes (combinations ofATTR_READABLE_VIEW
andATTR_WRITABLE_VIEW
attributes)service
- the shareable object identifying the recipient context of the new view. Ifnull
, the view will remain in the current context. If non-null
, the method returns an object created in the context of the specifiedservice
and should be used as parameter when calling methods of thisservice
. Other operations executed in current context, including casting, will throw aSecurityException
.- Returns:
- a view on the specified
array
parameter - Throws:
NullPointerException
- if thearray
parameter isnull
NegativeArraySizeException
- if thelength
parameter is negativeSecurityException
-- if the
array
cannot be accessed from current context - if requesting access attributes that were not available for
the
array
parameter
- if the
SystemException
- with the following reason code:SystemException.ILLEGAL_VALUE
if thearray
parameter is not an arraySystemException.NO_RESOURCE
if not enough resources to allocate the view
ArrayIndexOutOfBoundsException
- if the view would cause access of data outside array bounds- Since:
- 3.1
-
makeByteArrayView
public static byte[] makeByteArrayView(byte[] array, short offset, short length, short attributes, Shareable service)
Creates a byte array which is a view on the specifiedarray
parameter. The elements of the created array have the same type and are mapped to the corresponding elements in the parent array. Any change in the parent array will be visible in the view and vice versa.The layout attributes (transient, persistent, sensitive) of the created array are identical to the
array
parameter ones.
In addition, it is possible to create read-only, write-only or R/W views using combinations (bitwise inclusive OR) of the following access attributes:ATTR_READABLE_VIEW
: the elements of the view can be read. If this attribute is not set, any attempt to read elements from the created view will throw aSecurityException
ATTR_WRITABLE_VIEW
: the elements of the view can be modified and changes are visible in the actual array and any other view on it. If this attribute is not set, any attempt to write elements in the created view will throw aSecurityException
The attributes requested for the view shall remain consistent with the attributes of the
array
parameter:- Any attempt to create a view with the
ATTR_READABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not readable. - Any attempt to create a view with the
ATTR_WRITABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not writable.
The created view is temporary and any attempt to store the reference into a class or instance field or in array elements will throw a
SecurityException
Example:
// creates a R/W view of 5 bytes on array, starting at offset 4 byte[] view = JCSystem.makeByteArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), null); // creates a view in the service context and share it with the service byte[] view = JCSystem.makeByteArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), service); service.execute(view);
- Parameters:
array
- the array on which to create the view (either an actual array or a view)offset
- the offset in thearray
where the view startslength
- the number of elements in the viewattributes
- the view access attributes (combinations ofATTR_READABLE_VIEW
andATTR_WRITABLE_VIEW
attributes)service
- the shareable object identifying the recipient context of the new view. Ifnull
, the view will remain in the current context. If non-null
, the method returns an object created in the context of the specifiedservice
and should be used as parameter when calling methods of thisservice
. Other operations executed in current context, including casting, will throw aSecurityException
.- Returns:
- a view on the specified
array
parameter - Throws:
NullPointerException
- if thearray
parameter isnull
NegativeArraySizeException
- if thelength
parameter is negativeSecurityException
-- if the
array
cannot be accessed from current context - if requesting access attributes that were not available for
the
array
parameter
- if the
SystemException
- with the following reason code:SystemException.ILLEGAL_VALUE
if thearray
parameter is not an arraySystemException.NO_RESOURCE
if not enough resources to allocate the view
ArrayIndexOutOfBoundsException
- if the view would cause access of data outside array bounds- Since:
- 3.1
-
makeShortArrayView
public static short[] makeShortArrayView(short[] array, short offset, short length, short attributes, Shareable service)
Creates a short array which is a view on the specifiedarray
parameter. The elements of the created array are mapped to the corresponding elements in the parent array. Any change in the parent array will be visible in the view and vice versa.The layout attributes (transient, persistent, sensitive) of the created array are identical to the
array
parameter ones.
In addition, it is possible to create read-only, write-only or R/W views using combinations (bitwise inclusive OR) of the following access attributes:ATTR_READABLE_VIEW
: the elements of the view can be read. If this attribute is not set, any attempt to read elements from the created view will throw aSecurityException
ATTR_WRITABLE_VIEW
: the elements of the view can be modified and changes are visible in the actual array and any other view on it. If this attribute is not set, any attempt to write elements in the created view will throw aSecurityException
The attributes requested for the view shall remain consistent with the attributes of the
array
parameter:- Any attempt to create a view with the
ATTR_READABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not readable. - Any attempt to create a view with the
ATTR_WRITABLE_VIEW
attribute will throw aSecurityException
if thearray
parameter is not writable.
The created view is temporary and any attempt to store the reference into a class or instance field or in array elements will throw a
SecurityException
Example:
// creates a R/W view of 5 short on array, starting at offset 4 short[] view = JCSystem.makeShortArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), null); // creates a view in the service context and share it with the service short[] view = JCSystem.makeShortArrayView(array, (short) 4, (short) 5, (short) (ATTR_READABLE_VIEW | ATTR_WRITABLE_VIEW), service); service.execute(view);
- Parameters:
array
- the array on which to create the view (either an actual array or a view)offset
- the offset in thearray
where the view startslength
- the number of elements in the viewattributes
- the view access attributes (combinations ofATTR_READABLE_VIEW
andATTR_WRITABLE_VIEW
attributes)service
- the shareable object identifying the recipient context of the new view. Ifnull
, the view will remain in the current context. If non-null
, the method returns an object created in the context of the specifiedservice
and should be used as parameter when calling methods of thisservice
. Other operations executed in current context, including casting, will throw aSecurityException
.- Returns:
- a view on the specified
array
parameter - Throws:
NullPointerException
- if thearray
parameter isnull
NegativeArraySizeException
- if thelength
parameter is negativeSecurityException
-- if the
array
cannot be accessed from current context - if requesting access attributes that were not available for
the
array
parameter
- if the
SystemException
- with the following reason code:SystemException.ILLEGAL_VALUE
if thearray
parameter is not an arraySystemException.NO_RESOURCE
if not enough resources to allocate the view
ArrayIndexOutOfBoundsException
- if the view would cause access of data outside array bounds- Since:
- 3.1
-
isArrayView
public static boolean isArrayView(Object object)
Check whether the specified object is an array view- Parameters:
object
- the object to query- Returns:
true
if the object parameter is an array view,false
otherwise- Since:
- 3.1
- See Also:
makeArrayView(Object, short, short, short, Shareable)
-
getAttributes
public static short getAttributes(Object view) throws SystemException
Get the attributes of the specified array view.The attributes returned are combinations (bitwise inclusive OR) of the following access attributes:
ATTR_READABLE_VIEW
: the elements of the view can be read. If this attribute is not set, any attempt to read elements from the view will throw aSecurityException
ATTR_WRITABLE_VIEW
: the elements of the view can be modified and changes are visible in the actual array and any other view on it. If this attribute is not set, any attempt to write elements in the view will throw aSecurityException
- Parameters:
view
- the object to query- Returns:
- the attributes (
ATTR_READABLE_VIEW
,ATTR_WRITABLE_VIEW
) of the view - Throws:
SystemException
- with the following reason codeSystemException.ILLEGAL_VALUE
if the object is not a view
- Since:
- 3.1
- See Also:
makeArrayView(Object, short, short, short, Shareable)
-
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 Java Card runtime environment-owned instance of theAID
object associated with the current applet context, ornull
if theApplet.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 an
Object
reference 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.- Returns:
- the
AID
object
-
lookupAID
public static AID lookupAID(byte[] buffer, short offset, byte length)
Returns the Java Card runtime environment-owned instance of theAID
object, if any, encapsulating the specified AID bytes in thebuffer
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 an
Object
reference 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:
buffer
- byte array containing the AID bytesoffset
- offset within buffer where AID bytes beginlength
- length of AID bytes in buffer- Returns:
- the
AID
object, if any;null
otherwise. A VM exception is thrown ifbuffer
isnull
, or ifoffset
orlength
are out of range.
-
beginTransaction
public static void beginTransaction() throws 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:
TransactionException
- with the following reason codes:TransactionException.IN_PROGRESS
if a transaction is already in progress.
- See Also:
commitTransaction()
,abortTransaction()
- This method may do nothing if the
-
abortTransaction
public static void abortTransaction() throws 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:
TransactionException
- with the following reason codes:TransactionException.NOT_IN_PROGRESS
if a transaction is not in progress.
- See Also:
beginTransaction()
,commitTransaction()
- This method may do nothing if the
-
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 (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:
TransactionException
- with the following reason codes:TransactionException.NOT_IN_PROGRESS
if a transaction is not in progress.
- See Also:
beginTransaction()
,abortTransaction()
- This method may do nothing if the
-
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 AID getPreviousContextAID()
Obtains the Java Card runtime environment-owned instance of theAID
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 an
Object
reference 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.- Returns:
- the
AID
object of the previous context, ornull
if Java Card runtime environment
-
getAvailableMemory
public static short getAvailableMemory(byte memoryType) throws 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. Please use getAvailableMemory(short[],short) method for accurate information.
- 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 theMEMORY_TYPE_*
constants defined above, for exampleMEMORY_TYPE_PERSISTENT
.- Returns:
- the upper bound on available bytes of memory for the specified type
- Throws:
SystemException
- with the following reason codes:SystemException.ILLEGAL_VALUE
ifmemoryType
is not a valid memory type.
- See Also:
getAvailableMemory(short[], short, byte)
-
getAvailableMemory
public static void getAvailableMemory(short[] buffer, short offset, byte memoryType) throws 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. The requested memory information is returned as a 32 bit number stored in the specified short array - buffer. The 32 bit number number is the concatenation of buffer[offset] and buffer[offset+1].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.
- The 32 bit number 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 theMEMORY_TYPE_*
constants defined above, for exampleMEMORY_TYPE_PERSISTENT
.buffer
- the output buffer for storing memory size informationoffset
- the offset within the buffer where memory size information begins- Throws:
ArrayIndexOutOfBoundsException
- if buffer[offset] or buffer[offset+1] outside array boundsNullPointerException
- if buffer isnull
SystemException
- with the following reason codes:SystemException.ILLEGAL_VALUE
ifmemoryType
is not a valid memory type.
- Since:
- 3.0.4
-
getAppletShareableInterfaceObject
public static Shareable getAppletShareableInterfaceObject(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
serverAID
parameter isnull
or the server applet does not exist - the server applet returns
null
- the server applet throws an uncaught exception
In addition to returning an
Object
reference 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:
serverAID
- the AID of the server appletparameter
- optional parameter data- Returns:
- the shareable interface object or
null
- Throws:
SecurityException
- if the server applet is not multiselectable and is currently active on another logical channel- See Also:
Applet.getShareableInterfaceObject(AID, byte)
- the
-
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 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 theApplet.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
orCLEAR_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:
SystemException
- with the following reason codes:SystemException.ILLEGAL_USE
if the object deletion mechanism is not implemented.
- 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
-
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 theApplet.select()
,Applet.deselect(
),MultiSelectable.select(boolean)
andMultiSelectable.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-19 assigned to the currently selected applet instance
-
isAppletActive
public static boolean isAppletActive(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. - This method returns
false
if the specified applet has not successfully registered viaApplet.register
. - If successfully registered, this method returns
true
even in theApplet.install
, andApplet.select
methods.
- 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- See Also:
lookupAID( byte[] buffer, short offset, byte length )
- This method returns
-
-