JCSystem (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacardx.framework
Class JCSystem

    java.lang.Object
      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:

- `Boolean`
- `Byte`
- `Character`
- `Class` (only `Class` instances corresponding to system API, promoted shareable interfaces, extension library and classic library classes)
- `Throwable` and API-defined subclasses thereof
- `Integer`
- `Long`
- `Short`
- `String` (only literal and interned String objects)

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:

- `String` (newly created strings, strings computed at run time)
- arrays

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 the shareable interface method was called by another application from a group context distinct from that of the server application (the owner of the SIO) or if no shareable interface method was called, the client corresponds to the previously active application, if any, as determined by a call to `getPreviousURI()`.
  - If the shareable interface method was called by an application (including the server application) from within the same group context as that of the server application (the owner of the SIO), the client corresponds to the currently active application as determined by a call to `getURI()`.
  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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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