Site Tools


Smart Card Solution

User Manual

JavaCard API Samples

Java Card Specification

Knowledge Sharing


4.4 Binary Compatibility

In the Java programming language the granularity of binary compatibility can be between classes since binaries are stored in individual class files. In Java Card systems Java packages are processed as a single unit, and therefore the granularity of binary compatibility is between packages. In Java Card systems the binary of a package is represented in a CAP file, and the API of a package is represented in an export file.

In a Java Card system, a change to a type in a Java package results in a new CAP file. A new CAP file is binary compatible with (equivalently, does not break compatibility with) a preexisting CAP file if another CAP file converted using the export file of the preexisting CAP file can link with the new CAP file without errors.

shows an example of binary compatible CAP files, p1 and p1'. The preconditions for the example are: the package p1 is converted to create the p1 CAP file and p1 export file, and package p1 is modified and converted to create the p1' CAP file. Package p2 imports package p1, and therefore when the p2 CAP file is created the export file of p1 is used. In the example, p2 is converted using the original p1 export file. Because p1' is binary compatible with p1, p2 may be linked with either the p1 CAP file or the p1' CAP file.

FIGURE 4-2 Binary Compatibility Example

Any modification that causes binary incompatibility in the Java programming language also causes binary incompatibility in Java Card systems. These modifications are described as causing a potential error in The Java Language Specification. Any modification that does not cause binary incompatibility in the Java programming language does not cause binary incompatibility in a Java Card system, except under the following conditions:

  • The value of a token assigned to an element in the API of a package is changed.
  • The value of an externally visible final static field (compile-time constant) is changed.
  • An externally visible virtual method that does not override a preexisting method is added to a non-final public class.
  • An externally visible interface method that does not override a preexisting method is added to a public interface.

Tokens are used to resolve references to imported elements of a package. If a token value is modified, a linker on a device is unable to associate the new token value with the previous token value of the element, and therefore is unable to resolve the reference correctly.

Compile-time constants are not stored as fields in CAP files. Instead their values are recorded in export files and placed inline in the bytecodes in CAP files. These values are said to be pre-linked in a CAP file of a package that imports those constants. During execution, information is not available to determine whether the value of an inlined constant is the same as the value defined by the binary of the imported package.

As described above, tokens assigned to public and protected virtual methods are scoped to the hierarchy of a class. Tokens assigned to public and protected virtual methods introduced in a subclass have values starting at one greater than the maximum token value assigned in a superclass. If a new, non-override, public or protected virtual method is introduced in a superclass it is assigned a token value that would otherwise have been assigned in a subclass. Therefore, two unique virtual methods could be assigned the same token value within the same class hierarchy, making resolution of a reference to one of the methods ambiguous.

The addition of an externally visible, non-override method to a public interface is a binary incompatible change. It allows classes which are not themselves abstract to contain an abstract method. For example, consider the case of an interface I implemented by a class C that is not abstract, where I and C reside in different packages. If a new method is added to I, creating I', then C cannot link with the new version of I' because this would result in the class C containing an abstract method without the class C being abstract. The fact that C can not link with I' means that I and I' are not binary compatible.

javacard/jcvm/4.4_binary_compatibility.txt · Last modified: 2017/05/13 04:11 (external edit)