Runtime Environment Specification, Java Card Platform, v3.0.1, Connected Edition Table Of ContentsPrevious ChapterNext ChapterBook Index

C H A P T E R  4
APDU-based Application Environment

This chapter describes the interactions and dependencies between the platform, the applet container and APDU-based applet applications:

4.1 Applet Application Overview

The two applet application models, classic and extended, support an application programming environment suitable for smart card programs which interact with off-card client applications using the ISO 7816-4 specification defined Application Protocol Data Unit (APDU) synchronous communication paradigm. An applet application receives a command APDU, processes the command, and sends a response APDU containing the result of the processing back to the off-card client. The processing of APDU commands is sequential, meaning, a subsequent APDU command may only be processed from the same off-card client across the I/O interface by an applet application after the first APDU response is returned.

The execution lifecycles of the applet application models are designed to correspond to the specification Identification Cards - Integrated circuit cards - Part 4: organization, security and commands for interchange (ISO 7816-4). An applet application MUST be selected before it can receive APDU commands. An applet application is selected when the ISO 7816-4 defined SELECT command containing the applet application’s Application Identifier (AID) is processed by the applet container or implicitly as a default application. See Section 4.3.1, Applet Lifecycle Methods and the “Logical Channels and Applet Selection” chapter of the Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition. The applet application is deselected when another application is selected to replace it or when the I/O communication interface to the off-card client is reset or a power loss occurs.

The applet container manages two types of applet applications:

An applet that implements the javacard.framework.Multiselectable interface is deemed multi-selectable and allows itself to be selected when another instance from the same application group is already selected on the card. Either all the applets within an application group MUST be multi-selectable or none.

4.2 Applet Application Lifecycle

Applet application modules are the logical units of assembly of applet applications. All the components of an applet application MUST be assembled into an applet application module. See Section 8.4.1.2, Extended Applet Application Module Distribution Format, and Section 8.4.1.3, Classic Applet Application Module Distribution Format for details on the structure of applet application modules.

When being deployed, an applet application will typically go through the following lifecycle:

1. Loading of the applet application module, see Section 4.2.1, Application Module Loading.

2. Creation of an instance of the applet application, see Section 4.2.2, Application Instance Identification and Section 4.2.3, Application Instance Creation. An applet application instance corresponds to the instantiation of one of the applet classes from the applet application module.

3. Execution of an applet application instance:

4. Restart upon platform reset, see Section 4.2.6, Restart Upon Platform Reset.

5. Deletion of the applet application instance, see Section 4.2.4, Application Instance Deletion.

6. Unloading of the applet application module, see Section 4.2.5, Applet Application Module Unloading.

The applet container MUST support multi-instantiation of applet applications. Multiple applet classes defined in the an applet application module may be instantiated and coexist concurrently. In addition, the same applet class defined in an applet application module may be instantiated multiple times and coexist concurrently.

4.2.1 Application Module Loading

When an applet application module is being loaded, the following requirements MUST be implemented by the Java Card Platform:

Any error during loading, especially module format errors, descriptor format errors, descriptor and code consistency errors, MUST result in the loading of the application module to fail and the application module to be rejected.

Refer to Section 8.6, Loading Application Modules for the other generic requirements that MUST be implemented by the Java Card Platform when an application module is loaded.

4.2.2 Application Instance Identification

Every applet instance MUST be identified by its Application Identifier (AID). The ISO 7816-5 specifications define the AID format and its use for the unique identification of card applications (and files in card file systems). The AID format used in Java Card technology for the identification of an applet instance (as well as applet classes) uses the Category ‘D’ format.

The AID format used by the Java Card platform is an array of bytes that can be interpreted as two distinct pieces, as shown in TABLE 4-1. The first piece is a 5-byte value known as a RID (resource identifier). The second piece is a variable length value known as a PIX (proprietary identifier extension). A PIX can be from 0 to 11 bytes in length. Thus an AID can be from 5 to 16 bytes in total length.


TABLE 4-1 AID Format

RID (5 bytes)

PIX (0-11 bytes)


ISO controls the assignment of RIDs to companies, with each company obtaining its own unique RID from the ISO. Companies manage assignment of PIXs for AIDs using their own RIDs.

Applet instances are selected for APDU communication using the ISO 7816-4 defined SELECT command containing AID information to identify the applet instance. Once selected, APDU commands may be routed to the applet instance by the applet container.

Internal to the card, every applet instance is named with a relative URI - its application URI - that uses the aid registry-based authority and whose path component corresponds exactly to its AID (See Section 2.3.1, Unified Naming Scheme). This application URI defines the root of a dedicated namespace within which all its resources, including SIO-based services, events and files, MUST be named.


Note - To maximize portability, an extended applet application developer should name or refer to the applet application’s resources both in code and descriptors using relative URIs.

4.2.3 Application Instance Creation

When an applet application instance is being created, the following requirements MUST be implemented by the Java Card Platform:

1. The applet class’ static install method MUST be called with installation parameter data to initiate application instance creation.

The format of the installation parameter data passed to the target applet’s install method MUST be in the format described in the API description of the method in Application Programming Interface Specification, Java Card Platform, Version 3.0.1, Connected Edition.

2. The applet instance which is created by the applet’s install method must be registered by the application via the applet’s register method.

The registered applet instance MUST be rooted at the application-URI corresponding to the applet instance AID in the applet container’s namespace. This instance of the applet MUST serve as the logical root of persistence for the application instance, see Section 4.2.8, Container-managed Object Lifetime and Persistence.

3. The class-path resources in the module’s APPLET-INF/classes directory are shared among all applet instances from the applet application module and MUST be made available to the application’s code using the Class.getResourceAsStream method.

4. The applet container MAY start dispatching APDU commands as per Section 4.2.8, Container-managed Object Lifetime and Persistence.


Note - Because an applet application may be instantiated multiple times from the same loaded module code, the developer must account for static fields and initializers not being reset or re-run at each instantiation.

Refer to Section 8.8, Creation of Application Instances for the other generic requirements, such as assignment to the proper group context and protection domain, that MUST be implemented by the Java Card Platform when an application instance is created.

4.2.4 Application Instance Deletion

When an applet application instance is being deleted, the following requirements MUST be implemented by the Java Card Platform:

1. Before firing the application instance deletion request event, event:///standard/app/deleting, the Java Card RE MUST ensure that the applet instance being deleted is not currently selected for APDU communication on the card. If so, deletion MUST NOT be attempted and the operation fails.

2. Before firing the application instance deletion request event, the Java Card RE MUST inform each of the applets of potential deletion by invoking, if implemented, the applet instance's uninstall method of the AppletEvent interface.

3. Upon successful deletion:

a. The applet instance’s AID corresponding to its application URI MUST be released.

b. The applet application’s temporary storage directory and its content MUST be removed.

The applet instance’s AID MUST only be reassigned when the application instance is considered effectively deleted, see Section 8.9, Deletion of Application Instance.

Refer to Section 8.9, Deletion of Application Instance for the other generic requirements that MUST be implemented by the Java Card Platform when an application instance is deleted.

4.2.5 Applet Application Module Unloading

When an applet application module is being unloaded, the following requirements MUST be implemented by the Java Card Platform:

Refer to Section 8.10, Unloading of Deployment Units for the other generic requirements that MUST be implemented by the Java Card Platform when an application module is unloaded.

4.2.6 Restart Upon Platform Reset

There are no applet application environment-specific steps required before any APDU command can be dispatched to an applet application instance after a platform reset.

Refer to Chapter 5 for the other generic requirements that MUST be implemented by the Java Card Platform after a platform reset.

4.2.7 Dispatching APDU Commands

The applet container is responsible for managing the selection of applet instances and dispatching APDU commands to selected applet instances.

The Java Card Platform, v3.0.1, Connected Edition MAY support more than one I/O interface, across which APDU commands are received. Each of these I/O interfaces MUST support the ISO 7816-4 specification-defined APDU communication protocol. Over each of these interfaces, the platform MAY support up to 20 ISO 7816-4 defined logical channels of APDU communication. The applet container MUST either configure a supported logical channel to have a default applet instance or MUST designate the logical channel as having no associated default applet instance.

The process of management of logical channels and applet selection over an I/O interface is described in the “Logical Channels and Applet Selection” chapter of the Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition.

The applet container MAY manage multiple APDU command dispatcher threads. The multithreading issues around managing separate dispatcher threads for each I/O interface is described in Section 4.3.4, Multithreading Issues For Applets.

4.2.8 Container-managed Object Lifetime and Persistence

When an applet instance of an applet application is instantiated, the APDU application container MUST invoke the Applet.install() method, which in turn creates an instance of applet (instance of application-defined subclass of the javacard.framework.Applet class). This instance MUST be promoted to become a persistent object by virtue of being reachable from a persistent APDU container managed object. This instance of the Applet serves as the logical root of persistence for the newly instantiated applet instance of the applet application. This instance of Applet is deleted only when the applet instance of the applet application is deleted.

When executing an applet application, the container MUST instantiate container-managed objects, that is, objects created by the container as per its operating principles. Container-managed objects include instances of the javacard.framework.APDU class. These instances are Java Card RE entry point object instance, see Section 2.4.2.1, Java Card RE Entry Point Objects.

All container-managed objects created on behalf of the application MUST be Java Card RE entry point objects (see Section 2.4.2.1, Java Card RE Entry Point Objects).

Specific lifetime and persistence requirements of some container-managed objects are described in the following sections. Any container-managed object which is not called out specifically MAY have implementation assigned lifetime and persistence characteristics.

4.2.8.1 Applet Lifetime

The following container-managed object MUST be a persistent object. It is created when an applet instance of the applet application is instantiated and can be garbage collected only when the applet instance of the applet application is deleted.

4.2.8.2 Command/Response Object Lifetime

The following container-managed objects MUST be volatile objects:


Note - Container-managed volatile command/response objects SHOULD be referenced via reachability disrupting objects from the container object itself.

4.2.8.3 Behavior Upon Platform Reset

Upon card reset, all volatile objects MUST be garbage collected. All references to volatile objects in reachability disrupting objects MUST be reset to null.

4.3 Lifecycle and Entry Point Method Invocation

4.3.1 Applet Lifecycle Methods

The applet container invokes the applet’s methods to manage all aspects of the applet’s lifecycle. The methods correspond to application creation, selection, APDU message processing and application deletion. The following sections describe each lifecycle state.

4.3.1.1 Applet Application Instance Creation

The applet container invokes the applet’s static install method to initiate application instance creation. The application typically processes the initialization parameter information, creates and initializes applet application resources, and finally registers the newly created applet instance with the applet container via the Applet.register method.

A successful completion of the Applet.register method results in the successful completion of the applet application instance. Upon successful instantiation, and following any additional applet instance initialization, the applet container MUST mark the applet instance as available for selection.

The applet container MUST invoke the applet’s install method with a transaction in progress. The applet container MUST abort this transaction, if the instantiation is unsuccessful.

4.3.1.2 Applet Application Selection

The applet container invokes one of the applet instance’s select methods to inform the applet instance upon becoming selected on a logical channel for APDU communication. Upon successful selection, the applet instance is deemed as being active on the card. The choice of select method used by the applet container is as follows:

Applet selection fails if the select method returns false or throws an uncaught exception.

If applet selection fails, the applet container MUST mark the corresponding logical channel as having no applet selected. If the applet selection was initiated by the SELECT APDU Command or the MANAGE CHANNEL APDU Command, the applet container MUST send an APDU Response to the off-card client with status code equal to 0x6999 (javacard.framwork.ISO7816.SW_APPLET_SELECT_FAILED).

If the applet selection is successful and the selection was initiated by the SELECT APDU command, the applet container MUST dispatch the SELECT APDU command to the newly selected applet for processing via the Applet.process method.

The applet container MUST abort the transaction in progress, if any, upon normal return or uncaught exception from the process method. When the applet container aborts the transaction, it proceeds as if an uncaught exception was thrown.

The step-by-step processing requirements of the SELECT APDU command and MANAGE APDU command are described in the sections “Opening and Closing Logical Channels” and “Applet Selection” in the chapter “Logical Channels and Applet Selection” of the Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition.

4.3.1.3 Applet Application Execution

The applet container MUST dispatch APDU commands received over a logical channel to the applet instance currently selected on that logical channel for processing. The applet container MUST call the Applet.process method with the APDU object parameter containing the incoming APDU command.

If there is no applet selected on the logical channel, the applet container MUST send an APDU response to the off-card client with status code equal to 0x6999 (javacard.framwork.ISO7816.SW_APPLET_SELECT_FAILED).

Upon normal return from the process method, the applet container MUST send an APDU response to the off-card client with status code equal to 0x9000 (javacard.framwork.ISO7816.SW_NO_ERROR) along with any accumulated response data in the APDU object.

If the process method throws an uncaught ISOException exception, the applet container MUST send an APDU response to the off-card client with status code equal to the reason code contained in the ISOException object, along with any accumulated response data in the APDU object.

If the process method throws any other uncaught exception, the applet container MUST send an APDU response to the off-card client with status code equal to 0x6F00 (javacard.framwork.ISO7816.SW_UNKNOWN), along with any accumulated response data in the APDU object.


Note - In some cases of ISO 7816 protocol, partially accumulated response data must be filled out, with zeros, to account for the previously set applet response length, before being sent to the off-card client. For more details, see “API Topics - The APDU Class” section of the “Logical Channels and Applet Selection” chapter in Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition.

The applet container MUST abort the transaction in progress, if any, upon normal return or uncaught exception from the process method. When the applet container aborts the transaction, it proceeds as if an uncaught exception was thrown.

The specifics of APDU command decoding to determine which logical channel to dispatch an incoming APDU command is described in the sections “Forwarding APDU Commands to a Logical Channel” and “Other Command Processing” of the chapter “Logical Channels and Applet Selection” in Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition.

4.3.1.4 Applet Application Deselection

The applet container invokes one of the applet instance’s deselect methods to inform the applet instance upon becoming deselected on a logical channel for APDU communication. The choice of deselect method used by the applet container is as follows:

Components of transient array objects of type CLEAR_ON_DESELECT associated with the applet instances from their application group MUST be cleared.

The applet container MUST abort the transaction in progress, if any, upon normal return or uncaught exception from the deselect method.

The step-by-step processing requirements of applet deselection are described in the section “Applet Deselection” in the chapter “Logical Channels and Applet Selection” of Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition.

4.3.1.5 Applet Application Deletion

The applet container invokes the AppletEvent.uninstall interface method of the applet instance, if implemented, to inform the applet instance that there is a request to delete it. The applet typically performs clean up activities including removing any dependencies which might restrict its deletion.

The applet container MUST abort the transaction in progress, if any, upon normal return or uncaught exception from the uninstall method.

4.3.2 SIO, Event and Restartable Task Entry Point Methods

Shareable interface methods, create methods of SIO-based service factories, notify methods of event listeners and run methods of restartable tasks, constitute as many additional entry points into applet applications:

See Section 4.3.4, Multithreading Issues For Applets.

4.3.3 Use of Volatile and Persistent Objects

Components of transient array objects of type CLEAR_ON_DESELECT MUST be cleared whenever an applet instance is deselected (explicitly or implicitly) and no applet instances from the application group are active on the card.

See Section 2.8.2.1, Reachability Disrupting Objects for more details.

4.3.4 Multithreading Issues For Applets

This section describes multithreading issues that apply to the extended applet application environment. The extended applet application environment MAY be multithreaded. Extended applet applications MUST be thread-aware and MUST, therefore, account for concurrent processing.

Classic applet applications are not thread-aware. Therefore, the classic applet application environment MUST guarantee the thread-safety of classic applet applications. See Section 4.4.2, SIO Synchronization Proxy Classes.

An extended applet application’s code may be concurrently executed by multiple threads. These threads can be categorized as follows:

The applet application container MAY use multiple threads to concurrently manage the lifecycle of applets and to process incoming APDU commands concurrently over several interfaces. These threads are referred to in this specification as Java Card RE-managed threads or container-managed threads. The applet container MAY handle APDU commands concurrently over each of the contacted and the contactless interfaces, but MUST handle only one command at a time per interface. Because thread safety must be ensured for classic applets, the applet container MUST guarantee that only one APDU command received over any of the interfaces is processed by a classic applet at a particular time. Extended applets, by contrast, may process concurrently one command over each interface. Each command is handled by a different thread.

Some applet application container implementations MAY limit the number of concurrent container-managed threads. This may, therefore, limit the number of APDU commands that may be processed concurrently.

Extended applet applications may create new threads. A Java Card Platform implementation MAY restrict the creation of such application-managed threads to ensure that other components of the platform are not negatively impacted. Extended applet applications are responsible for managing the lifecycle of threads they create. They must account for restarting such threads, if needed, after platform resets.

4.3.4.1 Thread Safety

The applet container MUST handle concurrent APDU commands to the same extended applet by concurrently executing the process() method in different threads.

The applet container MAY use a single instance of the APDU object and APDU buffer array per interface being concurrently serviced. The applet container MUST use a different instance of the APDU object and APDU buffer array for each of the APDU commands being concurrently handled.

APDU objects are temporary Java Card RE entry point objects (see Section 2.4.2.1, Java Card RE Entry Point Objects) and the associated APDU buffers are global array objects (see Section 2.4.2.2, Global Arrays). References to these temporary objects cannot be stored in class variables, in instance variables, or in array components (see Section 2.4, Context Isolation Basics). These objects can, therefore, only be used within the scope of the command handling thread and the call of the process() method. No reference to such objects can be given to objects executing in other threads. The thread safety of such objects is, therefore, not required.

The applet container MUST guarantee that only one APDU command received over any of the interfaces is processed by a classic applet at a particular time.

The following requirements dictate that extended applet application developers handle the related thread safety issues explicitly:

Classic applet application developers do not have to specifically account for thread safety.


caution icon Caution - Although the classic applet application environment is thread safe, a classic applet invoking Shareable Interface Objects methods of an extended applet application or web application, such as on a SIO-based service, may encounter unexpected behavior. For example, this could occur if the state of the service concurrently changes while within the scope of the same process() method invocation. This is because that same SIO-based service object may be concurrently accessed by other extended applet or web applications.

4.3.4.2 Thread Ownership

All applet container-managed threads MUST be owned by the Java Card RE. This includes all APDU command handling threads and other applet application component lifecycle handling threads. See Section 2.7.4, Thread Ownership for more details on the restrictions that apply to Java Card RE-owned threads.

Threads created by an extended applet application MUST be owned by that application.

4.4 Classic Applet Application Support

The term classic application is applied to an applet application that may also be executed on the Java Card 3 Platform Classic Edition. The Java Card 3 Platform Classic Edition supports a more restrictive runtime environment and a more restrictive set of core and framework libraries than the Connected Edition. However, the applet container MUST guarantee the same functional behavior of a classic application on the Java Card 3 Platform Connected Edition provided that the classic application meets the following requirements:

4.4.1 Backward Compatibility

The Java Card 3 Platform Connected Edition, along with off-card compatibility tools, MUST ensure that Java applications programmed for the Java Card Platform, Version 2.2.2, run unchanged. These applications are also classic applications and may be executed on both the Java Card 3 Platform Connected and Classic Editions.

Classic applications on the Java Card 3 Platform Connected Edition MUST:

4.4.2 SIO Synchronization Proxy Classes

The Java Card RE uses SIO synchronization proxy classes to ensure that only one application thread is executing any classic application or classic library. An SIO synchronization proxy instance is substituted in place of the actual SIO instance of the classic application whenever it becomes accessible to an extended applet or a web application. This SIO synchronization proxy instance for an SIO instance of a classic application synchronizes with the singleton classic applet container mutex object before entering the SIO instance of the classic application. Additionally, an SIO synchronization proxy instance is substituted in place of the actual SIO instance of the extended or web application whenever it becomes accessible to a classic application. This SIO synchronization proxy instance for an SIO instance of an extended applet or a web application ensures that any SIO instances of a classic application that are passed as a parameters to the extended applet or web application are substituted with suitable SIO synchronization proxy instances.

The SIO proxy class MUST be a concrete implementation class which extends the javacardx.framework.ClassicSIOProxy abstract class, and implements the referenced shareable interfaces. The proxy class SHOULD implement the delegation software programming pattern for all the shareable interface methods. The ClassicSIOProxy class has a setSIO method that takes the SIO instance as a parameter and stores it internally for delegation. The getSIO method returns the SIO instance.

The classic application or classic library MUST include SIO proxy classes[1] in a subpackage named proxy of the classic application or classic library package for all the shareable interfaces referenced by the package. The proxy classes in the subpackage are named Proxy1, Proxy2, and so forth. For each Shareable Interface Object implementation class in the classic application or library, there SHOULD be a proxy class which implements exactly the same set of Shareable interfaces. Additional proxy classes SHOULD implement as many combinations of referenced shareable interfaces as possible without method signature conflicts or duplication. The complete set of additional proxy classes SHOULD span all the referenced shareable interfaces in as few classes as possible. The set of proxy classes implemented MAY be customized for the classic application or library module to address the programming pattern used in the module.

These proxy classes are dynamically loaded by the Java Card RE on behalf of the application by the SIO proxy generation mechanism implemented by the Java Card RE and MUST therefore be declared in the dynamically-loaded-classes element of the Java Card Platform-specific Application descriptor. See Section 8.5.3, Java Card Platform-specific Application Descriptor.

FIGURE 4-1 depicts the relationships and interactions between the components and actors of the SIO synchronization proxy mechanism. The numbering indicates a typical interaction sequence. Colors indicate common ownership of interacting objects.

FIGURE 4-1 SIO Synchronization Proxy Mechanism (Collaboration Diagram)


The SIO proxy class is instantiated by the SIO Proxy generation mechanism via its default constructor. The SIO proxy class MUST invoke each corresponding shareable interface method of the SIO object within a synchronized block, only after obtaining a lock on the singleton classic applet container mutex object obtained via the static field CLASSIC_APPLET_CONTAINER_MUTEX of the ClassicSIOProxy class. If the shareable interface method returns an object, the equivalent SIO proxy class method MUST call the ClassicSIOProxy.processReturn method to process the object and substitute a proxy for the object, if required, before returning from the shareable interface method. If the shareable interface method has an object as a parameter, the equivalent SIO proxy class method MUST call the ClassicSIOProxy.processParam method to process the object and substitute a proxy for the object, if required, prior to passing it to the shareable interface method.

The SIO Proxy generation mechanism implemented by the Java Card RE MUST search for a suitable SIO synchronization proxy class corresponding to the specific SIO object, within the Proxy subpackage of the classic applet application package or classic library package. The SIO Proxy generation mechanism is used by the ClassicSIOProxy.processReturn and the ClassicSIOProxy.processParam methods as well as by the ServiceRegistry.lookup and the JCSystem.getAppletShareableObject SIO discovery methods.

Two shareable interfaces defined by the classic server application, WalletSI and BalanceSI, and one shareable interface defined by the client, AccSI, as well as their associated SIO proxy classes in the proxy subpackage are shown below:


CODE EXAMPLE 4-1 SIO Synchronization Proxy Classes Example 
package com.sun.testServer;
/*shareable interface in classic server application/library package*/
public interface WalletSI extends Shareable {
	BalanceSI getBalance(AccSI acc);
	short getVersion();
}
 
package com.sun.testServer;
/*shareable interface in classic server application/library package*/
public interface BalanceSI extends Shareable {
	int getHi();
	int getLo();
	short getVersion();
}
 
package com.sun.testClient;
/* shareable interface in client application/library package*/
public interface AccSI extends Shareable {
	short getAccNum();
	byte getVersion();
}
 
package com.sun.testServer.proxy;
/* First SIO Proxy Class in proxy subpackage of server application or library implements 2 out of 3 referenced shareable interfaces*/
 
public class Proxy1 extends ClassicSIOProxy
		implements WalletSI, BalanceSI{
	public BalanceSI getBalance(AccSI acc) {
		try {
			 synchronized (CLASSIC_APPLET_CONTAINER_MUTEX) {
				return (BalanceSI)(processReturn(((WalletSI)getSIO()).
								getBalance((AccSI)processParam(acc))));
			 }
		} catch (ClassNotFoundException e) {
				throw new RuntimeException("SIO Synchronization Proxy 				Error: Class Not Found”);
		} catch (InstantiationException e) {
				throw new RuntimeException("SIO Synchronization Proxy Error: Instantiation Exception”);
		}
	}
 
	public int getHi(){
		synchronized (CLASSIC_APPLET_CONTAINER_MUTEX){ 
			return ((BalanceSI)getSIO()).getHi();
		}
	}
 
	public int getLo(){
		synchronized (CLASSIC_APPLET_CONTAINER_MUTEX){ 
			return ((BalanceSI)getSIO()).getLow();
		}
	}
 
	public short getVersion() {
		synchronized (CLASSIC_APPLET_CONTAINER_MUTEX){
			if (getSIO() instanceof BalanceSI){
				return ((BalanceSI)getSIO()).getVersion();
			} else if (getSIO() instanceof WalletSI){
				return ((WalletSI)getSIO()).getVersion();
			} else{ 
				throw new RuntimeException(“SIO Synchronization Proxy 			
											 Error”);
			}
		}
	}
 

package com.sun.testServer.proxy;
/* Second SIO Proxy Class in proxy subpackage of server application or library implements 1 out of 3 referenced shareable interfaces*/
public class Proxy2 extends ClassicSIOProxy
		implements AccSI{
	public short getAccNum(){
		synchronized (CLASSIC_APPLET_CONTAINER_MUTEX){ 
			return ((AccSI)getSIO()).getAccNum();
		}
	}
	public byte getVersion() {
		synchronized (CLASSIC_APPLET_CONTAINER_MUTEX){ 
			return ((AccSI)getSIO()).getVersion();
		}
	}
}


caution icon Caution - An extended applet application or web application that defines a SIO implementation class must not pass the SIO instance to its classic applet client via another intermediary classic applet application which obscures visibility into the actual shareable interfaces implemented by the SIO instance by simply declaring the SIO instance obtained from the extended applet application as a generic javacard.framework.Shareable Interface type. The SIO proxy class created for a SIO object class defined in an extended applet or web application may correspond only to the subinterfaces of the javacard.framework.Shareable Interface referenced by the classic applet application.

Caution - The SIO proxy class for a SIO object class defined in an extended applet or web application is created within the classic application client’s proxy subpackage and corresponds only to the subinterfaces of the javacard.framework.Shareable Interface referenced by the classic application. These SIO proxy classes may implement more shareable interfaces than those implemented by the original SIO instance. In this case, the classic application may encounter a false positive indication when performing “instance of” checks on the interfaces implemented by the substituted proxy object.

4.4.2.1 Single Threaded Runtime Environment

To ensure that classic applications and classic libraries execute in a single threaded environment, the following requirements MUST be supported:

If the getShareableInterfaceObject method of the javacard.framework.Applet class of the classic application returns an SIO synchronization proxy instance for an SIO object owned by an extended applet or web application, the contained SIO object MUST be substituted instead.

If the getShareableInterfaceObject method of the javacard.framework.Applet class of the extended application returns an SIO synchronization proxy instance for an SIO object owned by an classic applet, the contained SIO object MUST be substituted instead.

4.4.3 Restricted Visibility on Classic Library

Classic libraries MUST be loaded by the classic library class loader, which is in the delegation hierarchy of classic applet applications only (Section 6.7.1, Class Loader Delegation Hierarchy). This ensures that classic library code always executes in a single threaded environment.

4.4.4 Classic Transaction Model

Classic applications MUST be restricted to use the transaction model and facilities described in the chapter “Transactions and Atomicity” of the Runtime Environment Specification, Java Card Platform, v3.0.1, Classic Edition.

To ensure the properties of the classic transaction model, all classes of a classic application or classic library MUST be annotated with the TransactionType - SUPPORTS[2]. This ensures that transitions from one method to another when a classic transaction is in progress, continue the ongoing transaction.

4.4.5 Special Security Restrictions

All classic applications are associated with the classic application platform protection domain. The classic application platform protection domain is the security configuration for all classic applications and specifies the security permissions that are included and those that are not included (Section 6.2.2, Protection Domains).

The special security restrictions for classic applications ensure that classic applications do not encounter unexpected behavior or security attacks in the presence of thread-aware extended applet and web applications.

 

1 (Footnote) Off-card pre-processing tools which process classic applications--Converter and Normalizer--typically insert these SIO Proxy Classes.
2 (Footnote) Off-card pre-processing tools which process classic applications--Converter and Normalizer--typically insert these transaction annotations.


Runtime Environment Specification, Java Card Platform, v3.0.1, Connected Edition 5-30-09 Table Of ContentsPrevious ChapterNext ChapterBook Index

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.