|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavacard.framework.JCSystem
@TransactionType(value=NOT_SUPPORTED) public final class JCSystem
The 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, Connected Edition,
chapter 2, 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 |
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 | |
---|---|
static void |
abortTransaction()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use transaction annotation instead. |
static void |
beginTransaction()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use transaction annotation instead. |
static void |
commitTransaction()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use transaction annotation instead. |
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 or if called from the context of a Web Application. |
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 application. |
static short |
getMaxCommitCapacity()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use transaction annotation instead. |
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()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use transaction annotation instead. |
static short |
getUnusedCommitCapacity()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use transaction annotation instead. |
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 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()
Deprecated. Deprecated for extended applets and web applications on the Connected Edition of the Java Card 3 Platform. Use System.gc() instead. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
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 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.
Method Detail |
---|
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 or if the specified object
is an instance of the TransientReference
class.
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 queried
NOT_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)
,
TransientReference
public static boolean[] makeTransientBooleanArray(short length, byte event) throws NegativeArraySizeException, SystemException
Note:
CLEAR_ON_DESELECT
event parameter, this method
throws a SystemException
execption with reason code
SystemException.ILLEGAL_TRANSIENT
.
length
- the length of the boolean arrayevent
- the CLEAR_ON...
event which causes the array
elements to be cleared
NegativeArraySizeException
- if the length
parameter is negative
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 NegativeArraySizeException, SystemException
Note:
CLEAR_ON_DESELECT
event parameter, this method
throws a SystemException
execption with reason code
SystemException.ILLEGAL_TRANSIENT
.
length
- the length of the byte arrayevent
- the CLEAR_ON...
event which causes the array
elements to be cleared
NegativeArraySizeException
- if the length
parameter is negative
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 NegativeArraySizeException, SystemException
Note:
CLEAR_ON_DESELECT
event parameter, this method
throws a SystemException
execption with reason code
SystemException.ILLEGAL_TRANSIENT
.
length
- the length of the short arrayevent
- the CLEAR_ON...
event which causes the array
elements to be cleared
NegativeArraySizeException
- if the length
parameter is negative
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 NegativeArraySizeException, SystemException
Object
with the specified
array length.
Note:
CLEAR_ON_DESELECT
event parameter, this method
throws a SystemException
execption with reason code
SystemException.ILLEGAL_TRANSIENT
.
length
- the length of the Object
arrayevent
- the CLEAR_ON...
event which causes the array
elements to be cleared
NegativeArraySizeException
- if the length
parameter is negative
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, or
null
if the Applet.register()
method has
not yet been invoked or if called from the context of a Web Application.
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, Connected Edition, chapter 6 for details.
Note:
null
if called from the context
of a Web Application.
AID
object or null
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.
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, Connected Edition, chapter 6 for details.
buffer
- byte array containing the AID bytesoffset
- offset within buffer where AID bytes beginlength
- 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
Notes:
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.
TransactionException.ILLEGAL_USE
if called from a thread which does not own the
Classic Applet Container Mutex Object.
commitTransaction()
,
abortTransaction()
public static void abortTransaction() throws TransactionException
Notes:
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.
TransactionException.ILLEGAL_USE
if called from a thread which does not own the
Classic Applet Container Mutex Object.
beginTransaction()
,
commitTransaction()
public static void commitTransaction() throws TransactionException
Notes:
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.
TransactionException.ILLEGAL_USE
if called from a thread which does not own the
Classic Applet Container Mutex Object.
beginTransaction()
,
abortTransaction()
public static byte getTransactionDepth() throws TransactionException
Note:
TransactionException
- with the following reason codes:
TransactionException.ILLEGAL_USE
if called from a thread which does not own the
Classic Applet Container Mutex Object.
public static short getUnusedCommitCapacity() throws TransactionException
Notes:
TransactionException
- with the following reason codes:
TransactionException.ILLEGAL_USE
if called from a thread which does not own the
Classic Applet Container Mutex Object.
getMaxCommitCapacity()
public static short getMaxCommitCapacity() throws TransactionException
Notes:
TransactionException
- with the following reason codes:
TransactionException.ILLEGAL_USE
if called from a thread which does not own the
Classic Applet Container Mutex Object.
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, Connected Edition, chapter 6 for details.
Note:
null
if the previous context is that of
a Web Application or the Java Card runtime environment.
AID
object of the previous context, or
null
if Java Card runtime environment, or if
the previous context is that of a web applicationpublic static short getAvailableMemory(byte memoryType) throws SystemException
Notes:
memoryType
- the type of memory being queried. One of the
MEMORY_TYPE_*
constants defined above. See
MEMORY_TYPE_PERSISTENT
.
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
If the classic server applet returns an SIO synchronization proxy instance for an SIO object owned by an extended applet or web application, the contained SIO object must be subsitituted instead.
If the extended applet application returns an SIOsynchronization proxy instance for an SIO object owned by an classic applet, the contained SIO object MUST be subsitituted instead.
proxy
subpackage of the package of the classic server
or client applet or classic library.
In that package, the Java Card RE must search for classes named
Proxy1, Proxy2 .. It must pick the
first proxy class which implements exactly the same set of Shareable
interfaces that are implemented by the SIO instance. If an exact match is not
found, it must pick the first proxy class which implements all the Shareable
interfaces that are implemented by the SIO instance.
See Runtime Environment Specification for the Java Card Platform, Connected Edition, chapter 4 for details regarding SIO synchronization proxy classes.
serverAID
- the AID of the server appletparameter
- optional parameter data
null
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
System.gc()
instead.
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.
Note:
SystemException
with reason code SystemException.ILLEGAL_USE
. See the
Runtime Environment Specification, Java Card Platform, Connected Edition
chapters 2, 4 for more details.
SystemException
- with the following reason codes:
SystemException.ILLEGAL_USE
if the
object deletion mechanism is not implemented or if
called from the context of an extended applet or
web application.
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.
Note:
public static boolean isAppletActive(AID theApplet)
Note:
false
if the specified applet is
not active, even if its context is active.
theApplet
- the AID of the applet object being queried
true
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 )
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |