JavaCard CAP Components
All 13 component tags Oracle's JCVM 3.2 specification defines for a JavaCard CAP file: the original eleven, Debug (CAP format 2.2) and Static Resources (CAP format 2.3, Java Card 3.1). Which ones every CAP file must carry, which appear only when the package needs them, and what each holds.
| Tag | Component | Presence | Detail |
|---|---|---|---|
| 1 # | Header.cap | Required | CAP format version, flags (ACC_INT, ACC_EXPORT, ACC_APPLET, ACC_EXTENDED) and package AID (§6.4). |
| 2 # | Directory.cap | Required | Size of every component; a component that is absent is listed with size 0 (§6.5). |
| 3 # | Applet.cap | Conditional | Applet AIDs and install method offsets. Present only if the CAP file defines one or more applets (§6.6). |
| 4 # | Import.cap | Required | Imported packages with their AIDs and major / minor versions (§6.7). |
| 5 # | ConstantPool.cap | Required | Class, method and field references used by the bytecode (§6.8). |
| 6 # | Class.cap | Required | Class and interface hierarchy, instance-field and method-table metadata (§6.9). |
| 7 # | Method.cap[x] | Required | JCVM bytecode for all methods; uses a 4-byte size (Method.capx) in Extended-format CAP files (§6.10). |
| 8 # | StaticField.cap | Required | Static field image and initial values (§6.11). |
| 9 # | RefLocation.cap[x] | Required | Offsets in the Method component that must be relocated at link time (§6.12). |
| 10 # | Export.cap | Conditional | Elements that other CAP files may import. Present only for public packages that export them (§6.13). |
| 11 # | Descriptor.cap[x] | Required | Types and offsets used to parse and verify the CAP file. Must be in the file; loading it onto the card is optional (§6.3, §6.14). |
| 12 # | Debug.cap[x] | Optional | Since CAP format 2.2. Off-card debugging metadata; not intended for download to the device (§6.3, §6.15). |
| 13 # | StaticResources.capx | Conditional | Since CAP format 2.3 (Java Card 3.1). Static resources the application reads at runtime. Present only if the CAP file embeds static resources; always Extended format (§6.16). |
What this reference covers
Spec
Oracle JCVM Specification 3.2, Chapter 6 (Tables 6-1 and 6-2).
Companion tool
Reading
What this reference does not cover
The component list describes the CAP file format, not the loading process. How a package actually reaches a card is a GlobalPlatform matter: INSTALL for load, a sequence of LOAD blocks, then INSTALL for install, all inside an authenticated secure channel. A structurally valid CAP file will still be refused if that sequence or its keys are wrong.
Nor does it cover on-card resource limits, which are what most deployment problems come down to. Persistent storage is small and has finite write endurance, transient memory is smaller still, and a package that converts cleanly can exhaust either. Size the applet against the target chip before treating a failed install as a format problem.
Frequently asked questions
What is a CAP file?
The deployment unit of a JavaCard applet: a set of components carrying converted class data in the form the card installer consumes.
How many CAP components are there?
Oracle's JCVM 3.2 specification defines 13 component tags. Tags 1 to 11 are the original set, Debug (tag 12) arrived with CAP format 2.2, and Static Resources (tag 13) with CAP format 2.3 in Java Card 3.1. A given CAP file carries only the ones that apply, so a file without applets, exports, debug data or static resources has nine.
Which components can be left out?
Only Debug is a build-time choice: it is optional and not meant to be downloaded to the card. Applet, Export and Static Resources appear or not depending on what the package contains. Descriptor must be in the CAP file, but loading it onto the card is optional, so a loader may skip it to save storage.
What does the Import component do?
Lists the packages this one depends on by AID and version. A version mismatch against the card is a common cause of installation failures that look like file corruption.
How does a CAP file differ from a JAR?
A JAR holds class files for a full JVM. A CAP file holds a converted, linked, space-optimised form for the JavaCard VM, which has no class loader and very little memory.