Java Card Exceptions and Exception Handling

An exception is an event that interrupts the normal flow of instructions during the execution of a program. Exceptions are an important component of the Java language. They provide a simple and elegant method of error handling in programs.

The Java Card platform supports all Java programming language constructs related to exceptions. In Java Card applets, you can use the keywords throw, try, catch and finally. They work exactly the same as on the Java platform.
Exceptions are raised by the JCRE classes and the Java Card Virtual Machine in the event of internal problems being detected or as a result of program requests from applets. Despite the fact that the Java Card platform fully supports Java exceptions, there are some differences in their use, which are due to the limited resources of smart cards. This chapter is devoted to the exceptions of the Java Card platform. It discusses ways to raise and handle exceptions in applets.

The Java Card platform does not support all types of exceptions that can be found in basic Java packages, because many of them are not applicable for smart cards. For example, the Java Card platform does not support streams. Therefore, it does not include any exceptions related to threads.

However, the java.lang package of the Java Card platform includes support for certain exception classes included in its full version for the Java platform. For all supported exception classes, only a constructor without parameters and the equals method inherited from the root Object class are provided. Table 6.1 shows the exception classes included in the java.lang package of the Java Card platform.
The Throwable class defines the direct ancestor of all exception classes of the Java Card form. This class also ensures that all Java Card exceptions have the same semantics as their Java platform counterparts. For example, applets

The Exception class is an extension of the Throwable class. As in the case of the Java platform, this is the root class of the Java Card platform for all checked exceptions. The RuntimeException class is generated from the Exception class and is the root class for all unchecked exceptions of the Java Card platform. The concept of verifiable and unchecked exceptions is defined in the Java language specification. Their definition is given later in this chapter.
The other classes in Table 6.1 are unchecked exceptions. The exception classes available in the java.lang package provide basic language support for the Java exception infrastructure. They are triggered by the Java Card virtual bus in case of an error due to a violation of the rules of the Java language.

The Java Card platform provides a class inheritance hierarchy for both verifiable and unchecked exceptions.
The exceptions being checked are subclasses of the Exceptionn class and must either be explicitly handled in the method, or be defined after the throws keyword in the method header. This requirement is checked by the Java compiler. All checked Java Card exceptions come from the CardException class, which, in turn, comes from the Exception class.
All checked exceptions must eventually be handled by the up-summer. There are two reasons for this. Firstly, the checked exceptions occur due to an error in the applet, and the applet must correct this error.

Secondly, the checked exceptions are an important component of interaction with the method. Due to the fact that the applet methods contained in the API do not declare exceptions after the throws keyword, the Java compiler issues an error message if the applet does not provide for handling the exception being checked. Unchecked exceptions are often referred to as runtime exceptions. They are subclasses of the RuntimeException class and do not need to be processed by the program or declared in the throws section. Unchecked exceptions usually occur due to unexpected execution time issues, program errors, or errors in processing APDU commands. Such exceptions are handled by the closest external JCRE layers. All unchecked exceptions of the Java Card platform are inherited from the class
CardRuntimeException, which inherits from the RuntimeException class. Why do we need the CardException and CardRuntimeException classes? They
provide a resource-saving mechanism that allows you to reuse exception objects.

Java Card Exception Reason Code

Java exception classes provide a message string that serves to explain the cause of a specific error. The String class is not supported by the Java Card form, so exceptions cannot contain text messages. Alternatively, exception classes implemented on the Java Card platform provide a numeric code for the reason for the exception. The exception reason code is used to describe additional details needed when handling an exception. The exception reason code field is of type short.
The reason code is defined as a field of the CardException and Card-RuntimeException classes. It is inherited by their subclasses. In addition, two publicly available methods are defined in both classes – getReason and setReason, which allow you to read and set the reason code.

Raising exceptions in Java Card

To trigger an exception in the Java system, the applet creates an instance of the exception class. The code looks something like this:

throw new MyException(«a specific error message»);

Of course, the Java Card platform allows you to create a new exception object at any time. However, when programming for smart cards, it is always necessary to consider that their resources are very limited. If the applet creates an object every time an exception is raised, as a result, there will be many unused exception instances in the EEPROM memory, which has a limited amount, over time.
To optimize memory usage, it is necessary to create all exception objects during initialization and permanently store references to them. If an exception occurs, instead of creating a new exception object, the applet must perform the following actions:

  1. Find a reference to the necessary exception object for its reuse.
  2. Assign the desired value to the field of the object’s reason code.
  3. Activate the object.
    To support the reuse of exception objects, the JCRE runtime creates instances of each exception type in advance for Java Card program interfaces. The CardException and CardRuntimeException classes, as well as all their subclasses, provide the throwIt method, which allows applets to reuse instances of exception objects:

Public static void throwIt (short reason)

The throwIt method handles an exception instance every time it is raised by JCRE. The exception reason code in the throwIt method fills in the applet. For example, to reject an APDU command, an applet can trigger an ISOException and specify the reason code “invalid command”:


The applet can create its own exception objects. During initialization, the applet creates such an exception object and stores a reference to it in a constant field. Then, if necessary, the applet uses this instance to handle the exception.

ISOException is a special unchecked exception that is provided in Java Card programming interfaces. It occurs during execution and signals a warning or error. The ISO 7816 response status word is specified as the ISOException exception reason code.
The ISOException exception provides efficient error handling by the applet. If the command processing was completed successfully, the method returns the usual value. But in case of an error, the method throws an ISOException exception by writing the corresponding status word in its field.
Usually the applet does not handle the ISOException exception. Finally, the ISOException exception is handled by JCRE. In this case, the ISO status word is returned to the host application. That is why the word ISO is present in the name of this class of exceptions.

The ISO status word is an integral part of the APDU protocol. It provides a mechanism that allows the smart card to inform the host application about the states that occur when processing an APDU command. The Java Card platform provides a javacard interface.framework.ISO7816, which defines the most commonly used constants for the designation of state words related to ISO 7816-3 and ISO 7816-4 standards. Applet can generate any other status word and pass it to the host application, causing an ISOException exception.


If a program error occurs during the execution of the applet, which the applet must fix, it raises a UserException exception. Unlike the ISOException exception, the UserException exception is verifiable. It is inherited from the CardException class and therefore can be processed in the up-summer. If the applet needs to create additional exception types, it can inherit them from the UserException class.