javacardx.framework
Class JCSystem

java.lang.Object
  extended by javacardx.framework.JCSystem

@TransactionType(value=NOT_SUPPORTED)
public final class JCSystem
extends Object

This JCSystem class complements the JCSystem class with functionalities required for integrating the Applet application model and the Servlet application model to provide a consistent programming model.

This class includes a collection of methods to control application execution, user authentication and inter-application object sharing in the Java Card environment.

Enhanced Shareable Interface Mechanism

The Enhanced Shareable Interface mechanism allows for some "core" objects not explicitly tagged as Shareable to be passed as parameter and return values of SIO method calls. Only direct instances of a well-defined set of classes can be passed in this manner. All other classes are prohibited unless marked as Shareable.

Direct instances of the following classes are implicitly transferable, that is they are not bound to any context and can be passed freely between contexts. These objects are immutable:

Strings computed at run time are not by default implicitly transferable; such newly created strings are bound to their creator's context until they are explicitly interned by calling their intern() method, in which case they become context-free and can be directly passed to applications in other contexts.

Instances of the following classes are explicitly transferable, that is they are bound to their creator's context and cannot be passed between contexts unless their ownership is explicitly transferred by calling one of the transferOwnership methods:

Note that the ownership of the objects referenced by the components of an array are not affected when the ownership of the array is transferred. Especially, since a multi-dimensional array is an array of arrays, the ownership of nested arrays are not affected when the ownership of the nesting array is transferred.

See Runtime Environment Specification for the Java Card Platform, Connected Edition , chapter 7 for details regarding transfer of ownership.

Since:
Java Card 3.0
See Also:
JCSystem, String.intern()

Field Summary
static byte TIME_ACCURATE
          The time value returned by System.currentTimeMillis() is accurate.
static byte TIME_DELTA_ACCURATE
          The difference of the values returned on two invocations of System.currentTimeMillis() corresponds to the time elapsed between the two invocations.
static byte TIME_DELTA_MIN_ACCURATE
          The time between two invocations of System.currentTimeMillis() is at minimum as big as indicated by the difference of the two values returned; the time may be bigger.
 
Method Summary
static
<T> T
copyTransferable(T object)
          Creates a shallow copy of the provided explicitly transferable object.
static AID getAID(String uri)
          Returns the AID object corresponding to the provided application URI.
static String getAppProperty(String name, String uri)
          Gets the application property indicated by the specified name.
static String getClientURI()
          Returns the URI identifying the client application of the most recently called shareable interface object invoked through one of its shareable interface methods.
static byte getCurrentTimeAccuracy()
          Returns the accuracy of the time returned by System.currentTimeMillis().
static String getPreviousURI()
          Returns the URI identifying the application in the most recently active group context.
static String getServerURI(Shareable sio)
          Returns the URI identifying the server application exposing/owning the provided Shareable Interface Object.
static String getURI()
          Returns the URI identifying the currently executing application.
static String getURI(AID aid)
          Returns the applet application URI corresponding to the instance of the AID object.
static boolean isClientInRole(String role, String rsrcURI)
          Indicates whether the client application URI as returned by a call to getClientURI() is included in the specified logical "role" permitted to access the specified resource (e.g., SIO-based service or event) URI.
static boolean isTransferable(Object object)
          Tests whether an object is a direct instance of a transferable class.
static boolean isUserInRole(String role, String uri)
          Indicates whether the authenticated user identity bound to the current thread is included in the specified logical "role" or if one of the users included in that role corresponds to a globally authenticated user - the card holder.
static void synchronizeTime()
          Requests that the time as returned by System.currentTimeMillis() be synchronized with some external time reference.
static void transferOwnership(Object object)
          Transfers ownership of the provided object from the server application's context to the context of the client application as determined by a call to getClientURI().
static void transferOwnership(Object object, Shareable sio)
          Transfers ownership of the provided object to the context identified by the provided SIO.
static void transferOwnership(Object object, String appURI)
          Transfers ownership of the provided object to the context identified by the provided application URI.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TIME_ACCURATE

public static final byte TIME_ACCURATE
The time value returned by System.currentTimeMillis() is accurate.

See Also:
Constant Field Values

TIME_DELTA_ACCURATE

public static final byte TIME_DELTA_ACCURATE
The difference of the values returned on two invocations of System.currentTimeMillis() corresponds to the time elapsed between the two invocations.

See Also:
Constant Field Values

TIME_DELTA_MIN_ACCURATE

public static final byte TIME_DELTA_MIN_ACCURATE
The time between two invocations of System.currentTimeMillis() is at minimum as big as indicated by the difference of the two values returned; the time may be bigger.

See Also:
Constant Field Values
Method Detail

getAID

public static AID getAID(String uri)
Returns the AID object corresponding to the provided application URI.

Parameters:
uri - the applet's application URI.
Returns:
the AID object corresponding to the provided application URI, or null if it does not correspond to an applet currently registered.
Throws:
NullPointerException - if uri is null.
IllegalArgumentException - if uri is not a well-formed application URI.

getAppProperty

public static String getAppProperty(String name,
                                    String uri)
Gets the application property indicated by the specified name. Provides an application with a mechanism to retrieve named properties from the application's runtime descriptor.

The property retrieved is that of the application explicitly or implicitly designated by the provided application or resource URI. If the URI is null, is relative or does not designates an application, such as when it is a standard service or event URI, the configuration that applies is that of the current application.

Property names are case insensitive.

Parameters:
name - the name of the application property.
uri - the application or resource URI (may be null).
Returns:
the string value of the application property, or null if there is no property with that name.
Throws:
NullPointerException - if name is null.
IllegalArgumentException -
  • if uri is not null and is not a well-formed application or resource URI
  • or, if uri is not in the namespace of one of the applications from the current group context or is not in the standard service or event namespace.

getClientURI

public static String getClientURI()
Returns the URI identifying the client application of the most recently called shareable interface object invoked through one of its shareable interface methods.

The client of a shareable interface object is defined as follows:

If this method is called from a ServiceFactory.create() method during a service lookup, the client corresponds to the previously active application as determined by a call to getPreviousURI(), that is the application that requested the service from the Java Card RE. If this method is called from a EventNotificationListener.notify() method during an event's notification, this method returns null since notification is performed in a Java Card RE thread distinct from that of the application that requested the notification.

This method is typically used by a server application, while executing a shareable interface method to determine the identity of its client and thereby control access privileges.

Returns:
the URI identifying the client application, or null if none can be determined.

getServerURI

public static String getServerURI(Shareable sio)
Returns the URI identifying the server application exposing/owning the provided Shareable Interface Object.

Parameters:
sio - the Shareable Interface Object.
Returns:
the URI identifying the server application exposing/owning the provided SIO, or null if it is owned by the Java Card RE.
Throws:
NullPointerException - if sio is null.

getURI

public static String getURI()
Returns the URI identifying the currently executing application. This returns the application URI associated with the current thread (its active namespace URI). It corresponds to the application URI of the application that owns the entry point object (e.g., an SIO) the thread used to enter the current group context.

Returns:
the URI identifying the currently executing application, or null if its's an applet and the Applet.register() method has not yet been invoked.

getURI

public static String getURI(AID aid)
Returns the applet application URI corresponding to the instance of the AID object.

Parameters:
aid - the applet AID.
Returns:
the applet application URI corresponding to the provided applet AID, or null if it does not correspond to an applet currently registered.
Throws:
NullPointerException - if aid is null.

getPreviousURI

public static String getPreviousURI()
Returns the URI identifying the application in the most recently active group context. This may not correspond to the immediately preceding group context as it may be the Java Card RE context.

The returned URI is the application URI previously associated with the current thread (its most recently active namespace URI).

Note that it does not return the URI of the application owning the object from which the call was made as would be returned by the getPreviousContextAID() method of the classic JCSystem class.

If this method is called from a EventNotificationListener.notify() method during an event's notification, this method returns null since notification is performed in a Java Card RE thread distinct from that of the application that requested the notification.

Returns:
the URI identifying the application in the most recently active non-Java Card RE context, or null if no group context was previously active.

isClientInRole

public static boolean isClientInRole(String role,
                                     String rsrcURI)
Indicates whether the client application URI as returned by a call to getClientURI() is included in the specified logical "role" permitted to access the specified resource (e.g., SIO-based service or event) URI.

The role definition that applies is that of the application implicitly designated by the resource URI. If the resource URI does not designates an application, such as when the resource URI is a standard service or event URI, the role definition that applies is that of the current application.

If the client application is in the same group context as the current application (that is, getClientURI().equals( getURI())), this method returns true.

Roles and role membership can be defined using application descriptors.

Parameters:
role - the name of the role.
rsrcURI - the resource (e.g., SIO-based service or event) URI.
Returns:
true if:
  • the specified role is defined for the designated application and the client application URI is included in the role,
  • or, if the client application is in the same group context as the current application
false otherwise.
Throws:
NullPointerException - if role or rsrcURI is null.
IllegalArgumentException -
  • if rsrcURI is not a well-formed absolute resource URI
  • or, if rsrcURI is not in the namespace of one of the applications from the current group context or is not in the standard service or event namespace.

isTransferable

public static boolean isTransferable(Object object)
Tests whether an object is a direct instance of a transferable class.

Parameters:
object - the object to be tested for transferability.
Returns:
true if the object is a direct instance of an explicitly or implicitly transferable class.
Throws:
NullPointerException - if object is null.

isUserInRole

public static boolean isUserInRole(String role,
                                   String uri)
Indicates whether the authenticated user identity bound to the current thread is included in the specified logical "role" or if one of the users included in that role corresponds to a globally authenticated user - the card holder.

The role definition that applies is that of the application explicitly or implicitly designated by the provided application or resource URI. If the URI is null, is relative or does not designates an application, such as when it is a standard service or event URI, the role definition that applies is that of the current application.

Roles and role membership can be defined using application descriptors.

Parameters:
role - the name of the role.
uri - the application or resource URI (may be null).
Returns:
true if the specified role is defined for the designated application and either:
  • the user identity bound to the current thread is included in the role,
  • or, one of the users included in the role correspond to a globally authenticated user (i.e., card holder)
false otherwise.
Throws:
NullPointerException - if role is null.
IllegalArgumentException -
  • if uri is not null and is not a well-formed application or resource URI
  • or, if uri is not in the namespace of one of the applications from the current group context or is not in the standard service or event namespace.

transferOwnership

public static void transferOwnership(Object object)
Transfers ownership of the provided object from the server application's context to the context of the client application as determined by a call to getClientURI(). This method is typically used to transfer ownership of an object returned by a call to a server application's SIO. If the object is implicitly transferable or if the client application and server application are the same, the object's ownership is unchanged.

Parameters:
object - the object whose ownership is to be transferred.
Throws:
NullPointerException - if object is null.
SecurityException -
  • if transfer of ownership to the recipient context is not granted,
  • if the object is not a direct instance of a transferable class,
  • if the provided object does not belong to the current group context,
  • or, if no valid client application context could be determined

transferOwnership

public static void transferOwnership(Object object,
                                     Shareable sio)
Transfers ownership of the provided object to the context identified by the provided SIO. This method is typically used to transfer ownership of parameter values passed to a call to a server application's SIO. If the object is implicitly transferable or if the application owning the SIO is the current application, the object's ownership is unchanged.

Parameters:
object - the object whose ownership is to be transferred.
sio - the SIO from the recipient context.
Throws:
NullPointerException - if object or sio is null.
SecurityException -
  • if transfer of ownership to the recipient context is not granted,
  • or, if sio is owned by the Java Card RE
  • or, if the object is not a direct instance of a transferable class,
  • or, if the provided object does not belong to the current group context.

transferOwnership

public static void transferOwnership(Object object,
                                     String appURI)
Transfers ownership of the provided object to the context identified by the provided application URI. If the object is implicitly transferable or if the application identified by the application URI is the current application, the object's ownership is unchanged.

Parameters:
object - the object whose ownership is to be transferred.
appURI - the URI of the application from the recipient context.
Throws:
NullPointerException - if object or appURI is null.
IllegalArgumentException -
  • if appURI is not a well-formed application URI,
  • or, if appURI does not correspond to a registered application.
SecurityException -
  • if transfer of ownership to the recipient context is not granted,
  • if the object is not a direct instance of a transferable class,
  • or, if the provided object does not belong to the current group context.

copyTransferable

public static <T> T copyTransferable(T object)
Creates a shallow copy of the provided explicitly transferable object. If the object is implicitly transferable, the same object is returned.

Parameters:
object - the object to be copied.
Returns:
a copy of the provided object if it is an explicitly transferable object, or the object itself if it is an implicitly transferable object.
Throws:
NullPointerException - if object is null.
IllegalArgumentException - if the object is not a direct instance of a transferable class.
SecurityException - if the provided object does not belong to the current group context.

getCurrentTimeAccuracy

public static byte getCurrentTimeAccuracy()
Returns the accuracy of the time returned by System.currentTimeMillis().

Returns:
the accuracy of the time returned by System.currentTimeMillis().
See Also:
TIME_ACCURATE, TIME_DELTA_ACCURATE, TIME_DELTA_MIN_ACCURATE

synchronizeTime

public static void synchronizeTime()
Requests that the time as returned by System.currentTimeMillis() be synchronized with some external time reference. If supported, the Java Card VM makes a best effort to synchronize with an external time reference. If/when synchronization is successful, the Java Card RE fires a clock resynchronization event with its auxiliary data set as a Long object which encapsulates the delta that was applied to the system clock during the resynchronization.

A call to this method returns without waiting for the Java Card VM to synchronize with an external time reference.

See Also:
Event.EVENT_CLOCK_RESYNCED_URI


Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.