Chapter   1

Using the Object Deletion Mechanism, and Package and Applet Deletion

This chapter describes the object deletion mechanism, and the package and applet deletion features of Java Card platform.

Object Deletion Mechanism

The object deletion mechanism on the Java Card platform reclaims memory which is being used by “unreachable” objects. To be “unreachable”, an object can neither be pointed to by a static field nor by an object field. An applet object is reachable until successfully deleted.

The object deletion mechanism on the Java Card platform is not like garbage collection in standard Java due to space and time constraints. The amount of available RAM on the card is limited. In addition, since object deletion mechanism is applied to objects stored in persistent memory, it must be used sparingly. EEPROM writes are very time-consuming operations and only a limited number of writes can be performed on a card. Due to these limitations, the object deletion mechanism in Java Card technology is not automatic. It is performed only when an applet requests it. The object deletion mechanism should be used sparingly and only when other Java Card technology-based facilities are cumbersome or inadequate.

The object deletion mechanism on the Java Card platform is not meant to change the programming style in which programs for the Java Card platform are written.

Requesting the Object Deletion Mechanism

Only the runtime environment for the Java Card platform (“Java Card Runtime Environment” or “Java Card RE”) can start the object deletion mechanism, although any applet on the card can request it. The applet requests the object deletion mechanism with a call to the JCSystem.requestObjectDeletion() method.

For example, the following method updates the buffer capacity to the given value. If it is not empty, the method creates a new buffer and removes the old one by requesting the object deletion mechanism.

/** 
* The following method updates the buffer size by removing 
* the old buffer object from the memory by requesting 
* object deletion and creates a new one with the 
* required size. 
*/ 
void updateBuffer(byte requiredSize){ 
     try{ 
         if(buffer != null && buffer.length == requiredSize){ 
             //we already have a buffer of required size 
             return; 
         } 
         JCSystem.beginTransaction(); 
         byte[] oldBuffer = buffer; 
         buffer = new byte[requiredSize]; 
         if (oldBuffer != null) 
             JCSystem.requestObjectDeletion(); 
         JCSystem.commitTransaction(); 
     }catch(Exception e){ 
         JCSystem.abortTransaction(); 
     } 
} 

Guidelines on Using the Object Deletion Mechanism

The object deletion mechanism on the Java Card platform is not to be confused with garbage collection in the standard Java programming language. The following guidelines describe the possible scenarios when the object deletion mechanism may or may not be used:

When throwing exceptions, avoid creating new exception objects and relying on the object deletion mechanism to perform clean-up. Try to use existing exception objects.
Similarly try not to create objects in method or block scope. This is acceptable in standard Java, but is an incorrect use of the object deletion mechanism in Java Card technology-based applications.
Use the object deletion mechanism when a large object, such as a certificate or key, must be replaced with a new one. In this case, instead of updating the old object in a transaction, create a new object and update its pointer within the transaction. Then, use the object deletion mechanism to remove the old object.
Use the object deletion mechanism when object re-sizing is required, as shown in the example in "Requesting the Object Deletion Mechanism" .

Package and Applet Deletion

Version 2.2.1 of the Java Card platform provides the ability to delete package and applet instances from the card’s memory. Requests for deletion are sent in the form of an APDU from the terminal to the smart card. Requests to delete an applet or package cannot be sent from an applet on the card.

In version 2.2.1 of the Java Card platform, the Installer deletes packages and applets. Once the Installer is selected, it can receive requests from the terminal to delete packages and applets. The following sections describe programming guidelines that will help your packages and applets to be more easily removed.

Guidelines for Developing Removable Packages

Package deletion refers to removing all of a package’s code from the card’s memory. To be eligible for deletion, nothing on the card should have dependencies on the package to be deleted. This includes:

packages that are dependent on the package to be deleted.
applet instances or objects that either belong to the package, or that belong to a package that depends on the package to be deleted.

Package deletion will not succeed if:

a reachable instance of a class belonging to the package exists on the card.
another package on the card depends on the package.
a reset or power failure occurs after the deletion process is begun, but before it is completed.

To ensure that a package can be removed from the card easily, avoid writing and downloading other packages that might be dependent on the package. If there are other packages on the card that depend on this package, then you must remove all of the dependent packages before you can remove this package from the card memory.

Guidelines for Writing Removable Applets

Deleting an applet means that the applet and all of its child objects are deleted. Applet deletion will not succeed if:

any object owned by the applet instance is referenced by an object owned by another applet instance on the card.
any object owned by the applet instance is referenced from a static field in any package on the card.
the applet is active on the card.

If you are writing an applet that is deemed to be short-lived and is to be removed from the card after performing some operations, follow these guidelines to ensure that the applet can be removed easily:

try to write cooperating applets if shareable objects are required. To reduce coupling between applets, try to obtain shareable objects on a per-use basis.
if interdependent applets are required, try to make sure that these applets can be deleted simultaneously.
when static reference type fields exist:
Ensure there is a mechanism available in the applet to disassociate itself from these fields before applet deletion is attempted, or
Ensure that the applet instance and code can be removed from the card simultaneously (that is, by using applet and package deletion).

Using the AppletEvent.uninstall method

When an applet needs to perform some important actions prior to deletion, it may implement the uninstall method of the AppletEvent interface. An applet may find it useful to implement this method for the following types of functions:

release resources such as shared keys and static objects.
backup data into another applet's space.
notify other dependent applets.

Calling uninstall does not guarantee that the applet will be deleted. The applet may not be deleted after the completion of the uninstall method if, for example:

other applets or packages are still dependent on this applet.
another applet which needs to be deleted simultaneously cannot be deleted at this time.
the package which needs to be deleted simultaneously cannot be deleted at this time.
a tear occurs before the deletion elements are processed.

To ensure that the applets are deleted, implement the uninstall method defensively. Write your applet such that:

the applet continues to function consistently and securely if deletion fails.
the applet can withstand a possible tear during the execution.
the uninstall method can be called again if deletion is reattempted.

The following example shows such an implementation:

public class TestApp1 extends Applet implements AppletEvent{ 
 
    // field set to true after uninstall 
    private boolean disableApp = false; 
 
    ... 
    public void uninstall(){ 
        if (!disableApp){ 
            JCSystem.beginTransaction();  //to protect against tear 
            disableApp = true;            //mark as uninstalled 
            TestApp2SIO.removeDependency(); 
            JCSystem.commitTransaction(); 
        } 
    } 
 
    public boolean select(boolean appInstAlreadyActive) { 
        // refuse selection if in uninstalled state 
        if (disableApp) return false; 
        return true; 
    } 
    ... 
 
}