Java Card Preview Features

Summary

A Java Card Preview Feature is a new feature of the Java Card Platform whose design, specification, and implementation are complete, and yet impermanent, which means that the feature may exist in a different form or not at all in future releases of the Java Card Platform Specification.

The main purpose of introducing a preview feature is to enable application developers to use this feature in real context and provide feedback.

Developer feedback helps determine whether the feature has any design mistakes, which includes hard technical errors (such as a flaw in the type system), soft usability problems (such as a surprising interaction with an older feature), or poor architectural choices (such as one that forecloses on directions for future features). Through this feedback, the feature's strengths and weaknesses are evaluated to determine if the feature has a long-term role in the Java Card Platform, and if so, whether it needs refinement. Consequently, the feature may be granted final and permanent status (with or without refinements), or undergo a further preview period (with or without refinements), or else be removed.

Goals

• Define a model for partitioning new Java Card Platform features based on whether they are permanent or impermanent (that is, whether they will exist in the same form for all future releases, or will exist in a different form or not at all).
• Communicate the intent that code which uses preview features will not necessarily compile or run on a newer release.
• Allow technology implementers to develop and include such features in their products in order to get feedback from developers.
• Accelerate the release process of individual features for early adopters or implementers that cannot wait for the next version of the specification.

Non-Goals

• Not all JCVM, JCRE and JCAPI features need to be available initially as preview features.
• Does not include any specific mechanisms for collecting and evaluating developer feedback about preview features.
• Must not be interpreted as encouraging or allowing fragmentation of the Java Card Platform.

Motivation

Evolving the Java Card platform has always faced the following challenges:

• A (too) long time to introduce new features

  The average time between two releases is quite long, primarily due to external constraints. Some industries operate on extended cycles due to factors such as dependencies on other standards, regulatory requirements, the complexity of security certification programs, or the need to integrate changes into long-term evolution programs spanning several years. This limits our ability to release new versions frequently, slowing down the introduction of new features. This creates fragmentation with the introduction of proprietary API to bridge gaps, introducing additional constraints for future platform versions.

• Limited feedback challenges API evolution

  The evolution of the Java Card Platform specification is driven by feedback from the industry and implementers. However, due to the long cycles mentioned above, input from application developers often arrives too late, once features are fully defined in the specification and implemented in products. This delay limits our ability to refine or improve features, as we must maintain backward compatibility once the specification is published.

Introducing Preview Features would help to:

• Build confidence in the correctness and completeness of a new feature, and address any issues before it reaches its final and permanent status in the specification.
• Provide public exposure for a new feature, generate greater demand from application developers, and ultimately gather more feedback.
• Offer a solution for implementers that cannot wait for the next version of the specification.

Description

A Java Card Preview Feature is a new feature of the Java Card API, the Java Card Runtime Environment or the Java Card Virtual Machine whose design, specification, and implementation are complete, and yet impermanent. After a period of broad exposure and evaluation, a Java Card Preview feature may either be upgraded to permanent feature and included in a new version of the Java Card platform specification, or refined and benefit from another preview period, or be completely withdrawn.

Java Card Preview Features have the following properties:

• Integral. Java Card Preview Features are an integral part of the Java Card Platform specification. The list of Preview Features defined by the specification is amended twice a year. Nevertheless, the version of the JCAPI, JCRE and JCVM defining final and permanent features remains unchanged.

• Controlled by Oracle. Being part of the Java Card Platform specification, Java Card Preview Features can only be introduced by Oracle.

• Available. Java Card Preview Features are available in the Java Card Development Kit (JCDK) which is released when the amended list of Preview Features is published.
  JCDK implements all, and only, Java Card Preview Features defined in an amended Platform specification. They are disabled by default and all enabled at once.
  Licensee's implementation of an amended Java Card Platform specification may implement a subset of Java Card Preview Features for the purpose of providing early access, even though these features are non-final and may be updated or withdrawn in a future version of the Platform Specification.

• Full-fledged. A Java Card Preview Feature must be complete, stable, and developed with the same level of technical excellence and finesse as a final and permanent feature of the Java Card Platform.
  It must not be experimental, risky, incomplete, unstable, or not compatible with another platform feature. The preview feature could credibly achieve final and permanent status with no further changes. This implies an extremely high degree of confidence in the concepts which underpin the feature, but does not completely rule out making "surface level" changes in response to feedback. This is especially relevant for an API, which necessarily exposes concepts via a larger surface area than a JCVM feature; a semantically stable API might undergo considerable syntactic polishing (e.g., renaming classes, adding helper methods) during its preview period, before achieving final status.

Each version of the Java Card Development Kit is released with the corresponding documentation, including the javadoc for the JCAPI, containing both the permanent API from the platform version used as reference, and using an annotation to highlight all preview features made available in this version of the Java Card Development Kit. Similarly, an annotated version of the JCVM and JCRE are also released when Preview Features impact these documents.

Java Card Preview Features Lifecycle

Java Card Preview Features represent features that are candidates for inclusion in the next version $N+1 of the Java Card Platform Specification. Not all features that will be included in the final version of $N+1 are previewed; some are introduced directly as permanent when version $N+1 is officially released.

A preview feature may go through multiple review iterations. In each iteration, the feature can be refined based on feedback and then reissued as a preview for further evaluation.

Once a preview feature has completed its review period and qualifies to become permanent, it may be published as a finalized preview feature until it is included, unmodified, as a permanent feature of version $N+1. Alternatively, it can be incorporated directly as a permanent feature in version $N+1.

Until version $N+1 is officially released, a licensee may choose to implement a product with the permanent features of version $N, along with a subset of Preview Features targeted for version $N+1.

When version $N+1 is officially released:

• Finalized preview features are included in version $N+1 as permanent.

• Other preview features are either extended for another preview period and retargeted for version $N+2, or withdrawn.

• The Java Card Development Kit is updated to support all permanent features from version $N+1, along with all Preview Features targeted for $N+2.

Design of Java Card Preview Features

A Java Card Preview Feature has the following design constraints:

• a Preview JCVM feature may add and modify elements of the CAP file or Export file format and may extend and modify the JCVM instruction set.

• a Preview JCRE feature may add and modify a behavior defined by the JCRE

• a Preview JCAPI may add binary compatible changes to existing API in javacard.* or javacardx.*, and add a new package(s).

Relationship of Preview JCVM/JCRE Features and Preview JCAPI

Most Preview JCAPI features are standalone features with no connection to Preview JCVM or Preview JCRE features.

In contrast, some Preview JCAPI may be co-developed with Preview JCVM or Preview JCRE features either because the preview API is essential to use the preview JCVM or JCRE feature, or convenient to assist usage of the preview JCVM or JCRE feature.

• Essential. The preview API exists because code cannot enjoy the preview JCVM or JCRE feature without it.

• Convenient. The preview API is a collection of useful classes, interfaces, and methods that promote or assist usage of the preview JCVM or JCRE feature but are not essential for it.

Use of Java Card Preview Features

Because preview features have not achieved final and permanent status in the Java Card Platform, they are unavailable by default at convert time. Developers who wish to use preview features and APIs in their programs must explicitly enable preview features in the Java Card converter.

The Java Card preview features cannot be enabled on an individual basis since all preview features have equal status in the Java Card platform.

The Java Card Development Kit Tools are using the -enable-preview command-line flag to enable all preview features and accept this flag only for the latest (default) JCAPI version or in combination with -target $N where $N is the version of the latest Java Card platform release. The JCDK Tools supporting up to the $N+1 Java Card version cannot be expected to support the preview features defined by $N, since they may have been changed or dropped since Java Card $N.

• Compilation and Conversion

  To compile source code that refers to a preview API, the following JAR files must be used:

  • api-classic-preview-final.jar includes only API for finalized preview features.

  • api-classic-preview.jar includes API for both evolving and finalized preview features.

  To convert class files into a CAP file, it is possible to enable preview features using the following command-line options:

  • -enable-preview final enables only the features that have reached their final state and will be included permanently in the next specification version.

  • -enable-preview [all] (default) enables both evolving and finalized preview features.

  When using the converter tool, the handling of preview features depends on whether they are enabled or not:

  • If preview features are disabled, any attempt to use them results in a conversion error. In this case, the error message specifies which feature is being used incorrectly.

  • If preview features are enabled, a warning message is issued to remind developers that their code may rely on preview features, which may not be present on the targeted platform, and may exist in a different form or be removed in a future release.

• Verification

  To verify a CAP file, preview features can be enabled using the following command-line options:

  • -enable-preview final enables only the features that have reached their final state and will be included permanently in the next specification version.

  • -enable-preview [all] (default) enables both evolving and finalized preview features.

  When using the verifier tool, the handling of preview features depends on whether they are enabled:

  • If the preview features are disabled, any attempt to use them results in a verification error. In this case, the error message specifies which feature is being used incorrectly.

  • If the preview features are enabled, a warning is issued to remind developers that their code may rely on preview features, which may not be present on the targeted platform, and may exist in a different form or be removed in a future release.

• At Runtime

  Enabling preview features in the JCDK simulator requires the use of -enable-preview on the command line.

  Support for any preview feature in a licensee's implementation is optional. If supported, the way preview features are enabled is implementation dependent and outside the scope of this specification. For example, a product may enable preview features by default or require a specific permission such as granting access only to applications installed in a designated Security Domain.

Versioning of packages with Preview Features

• Versioning for non-finalized packages

  To enforce strict version control for preview features and clearly separate them from published package versions, the following versioning scheme applies:

  • The four most-significant bits of the major version are reserved to encode the preview feature version, allowing up to fifteen preview versions for a given package. The remaining bits retain the major version of the original package (without preview features). If there is no prior version, these bits must be set to 1, meaning new packages start at version 1.0. These reserved bits have never been used in previous platform package versions, ensuring backward compatibility with existing specifications.

  • The value encoded by these bits must be incremented for each new preview version of this package.

  Example: if an existing package has version 1.7, the first preview version will be 0x11.7, the second preview version will be 0x21.7, and the third preview version should be 0x31.7.

  This ensures that a CAP file using preview features cannot be loaded on a platform that does not support them, whether the platform complies with previous specifications or newer ones where the package version continues to evolve.

• Versioning for finalized packages

  When a Preview Feature has completed its review period and is considered final, the version of the corresponding package(s) can follow the default versioning scheme, with the four most-significant bits of the major version reset to 0. This standard versioning must be used when the finalized feature is intended to become permanent in the next Java Card Platform Specification version $N+1, and when it is important that applications importing this package do not require re-conversion once $N+1 is released.

  Example: If an existing package has version 1.7, and the latest preview version (e.g., 0x31.7) is ready to be finalized, then, provided it is backward compatible with version 1.7, the version of the finalized package can be set to 1.8.

Compatibility rules when a platform supports Preview Features

The compatibility rules defined in JCVM 4.5.2 are modified for platforms that accept loading CAP files using preview versions. When a platform supports preview features for a given package, two cases must be considered:

• The loaded code does not use any preview features.

  When a CAP file imports a standard package (with preview version bits set to 0), the preview version bits in the major version of the resident package are ignored during compatibility verification, and standard compatibility rules apply.

  Example: A platform with a resident package version 0x11.7 (first preview of package version 1.7) must successfully load any CAP file importing versions 1.0 to 1.7 of that package. However, it must reject a CAP file importing version 1.8 or higher.

• The loaded code uses preview features.

  When a CAP file imports a preview package (with preview version bits > 0), the package version imported by the loaded CAP file must exactly match the version of the resident package.

  This exact match is required because a previous preview version has either been made a permanent feature (increasing the minor version) or extended for another preview period (increasing the preview version bits). As a result, consecutive preview versions are not considered binary-compatible.

  Example: A platform with a resident package version 0x11.7 (first preview of package version 1.7) must:

  • successfully load a CAP file importing version 0x11.7 of that package,
  • reject CAP files importing version 0x11.6 (first preview of package version 1.6),
  • reject CAP files importing version 0x21.7 (second preview of package version 1.7).