Java CardÔ 2.2 Virtual Machine Specification

Java CardÔ 2.2 Virtual Machine Specification
Java CardÔ 2.2 Virtual
Machine Specification
Sun Microsystems, Inc.
901 San Antonio Road
Palo Alto, CA 94303 USA
650 960-1300
fax 650 969-9131
June, 2002
Java CardTM 2.2 Virtual Machine Specification ("Specification")
Version: 2.2
Status: FCS
Release: May 13, 2002
Copyright 2002 Sun Microsystems, Inc.
4150 Network Circle, Santa Clara, California 95054, U.S.A
All rights reserved.
NOTICE
The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending
applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior
written authorization of Sun Microsystems, Inc. ("Sun") and its licensors, if any. Any use of the Specification and the information described therein will be
governed by the terms and conditions of this license and the Export Control Guidelines as set forth in the Terms of Use on Sun's website. By viewing,
downloading or otherwise copying the Specification, you agree that you have read, understood, and will comply with all of the terms and conditions set forth
herein.
Subject to the terms and conditions of this license, Sun hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the
right to sublicense) under Sun's intellectual property rights to review the Specification internally solely for the purposes of designing and developing your
implementation of the Specification and designing and developing your applets and applications intended to run on the Java Card platform. Other than this
limited license, you acquire no right, title or interest in or to the Specification or any other Sun intellectual property. You acknowledge that any commercial or
productive use of an implementation of the Specification requires separate and appropriate licensing agreements. The Specification contains the proprietary
information of Sun and may only be used in accordance with the license terms set forth herein. This license will terminate immediately without notice from
Sun if you fail to comply with any provision of this license. Upon termination or expiration of this license, you must cease use of or destroy the Specification.
TRADEMARKS
No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun's licensors is granted hereunder. Sun, Sun Microsystems, the
Sun logo, Java, Java Card, and Java Card Compatible are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL
NOT BE CORRECTED BY SUN. SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF
THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT
INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to
release or implement any portion of the Specification in any product.
THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO
THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY
MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME.
Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT
LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING,
MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
You will indemnify, hold harmless, and defend Sun and its licensors from any claims arising or resulting from: (i) your use of the Specification; (ii) the use or
distribution of your Java applications or applets; and/or (iii) any claims that later versions or releases of any Specification furnished to you are incompatible
with the Specification provided to you under this license.
RESTRICTED RIGHTS LEGEND
If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the
Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201
through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
REPORT
You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To
the extent that you provide Sun with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and
(ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to
incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test
suites thereof. (LFI#113310/Form ID#011801)
Contents
Preface
xi
Who Should Use This Specification? xi
Before You Read This Specification xii
How This Book Is Organized xii
Prerequisites xii
Related Documents xiii
Sun Documentation xiii
What Typographic Changes Mean xiii
Acknowledgements xiv
1.
2.
Introduction
1
1.1
Motivation
1.2
The Java Card Virtual Machine
1.3
Java Language Security
1.4
Java Card Runtime Environment Security
1
2
4
A Subset of the Java Virtual Machine
2.1
Why a Subset is Needed
2.2
Java Card Language Subset
2.3
Java Card VM Subset
4
7
7
7
17
Contents
iii
3.
Structure of the Java Card Virtual Machine
3.1
Data Types and Values
3.2
Words
3.3
Runtime Data Areas
3.4
Contexts
3.5
Frames
3.6
Representation of Objects
3.7
Special Initialization Methods
3.8
Exceptions
3.9
Binary File Formats
27
28
28
28
29
29
30
30
3.10 Instruction Set Summary
4.
5.
Binary Representation
35
4.1
Java Card File Formats
4.2
AID-based Naming
4.3
Token-based Linking
39
4.4
Binary Compatibility
45
4.5
Package Versions
The Export File Format
35
37
47
49
5.1
Export File Name
5.2
Containment in a Jar File
5.3
Ownership
5.4
Hierarchies Represented
5.5
Export File
5.6
Constant Pool
5.7
Classes and Interfaces
5.8
Fields
5.9
Methods
50
50
50
51
51
53
57
61
5.10 Attributes
iv
30
63
65
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
29
27
6.
The CAP File Format
67
6.1
Component Model
6.2
Installation
6.3
Header Component
6.4
Directory Component
6.5
Applet Component
77
6.6
Import Component
80
6.7
Constant Pool Component
6.8
Class Component
6.9
Method Component
68
70
72
75
81
88
101
6.10 Static Field Component
107
6.11 Reference Location Component
6.12 Export Component
114
6.13 Descriptor Component
6.14 Debug Component
7.
8.
111
117
125
Java Card Virtual Machine Instruction Set
135
7.1
Assumptions: The Meaning of “Must”
135
7.2
Reserved Opcodes
7.3
Virtual Machine Errors
7.4
Security Exceptions
7.5
The Java Card Virtual Machine Instruction Set
Tables of Instructions
Glossary
Index
136
136
137
137
267
273
281
Contents
v
vi
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Figures
FIGURE 1-1 Java Card Package Conversion
2
FIGURE 1-2 Java Card Package Installation 3
FIGURE 4-1 AID Format
38
FIGURE 4-2 Mapping package identifiers to AIDs
38
FIGURE 4-3 Tokens for Instance Fields 43
FIGURE 4-4 Binary compatibility example
45
FIGURE 7-1 An example instruction page
138
Figures
vii
viii
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Tables
TABLE 2-1
Unsupported Java constant pool tags 18
TABLE 2-2
Supported Java constant pool tags.
TABLE 2-3
Support of Java checked exceptions 23
TABLE 2-4
Support of Java runtime exceptions
TABLE 2-5
Support of Java errors
TABLE 3-1
Type support in the Java Card Virtual Machine Instruction Set
TABLE 3-2
Storage types and computational types
TABLE 4-1
Token Range, Type and Scope
TABLE 5-1
Export file constant pool tags
TABLE 6-1
CAP file component tags 68
TABLE 6-2
CAP file component file names
TABLE 6-3
Reference component install order
19
24
25
32
33
41
53
69
71
TABLE 6-14 Segments of a static field image 108
TABLE 6-15 Static field sizes
108
TABLE 6-22 Class access and modifier flags
TABLE 6-23 Field access and modifier flags
127
129
TABLE 8-1
Instructions by Opcode Value
268
TABLE 8-2
Instructions by Opcode Mnemonic 270
Tables
ix
x
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Preface
Java CardÔ technology combines a subset of the Java programming language with a
runtime environment optimized for smart cards and similar small-memory
embedded devices. The goal of Java Card technology is to bring many of the benefits
of Java software programming to the resource-constrained world of devices such as
smart cards.
The Java Card platform is defined by three specifications: this Java CardÔ 2.2 Virtual
Machine Specification, the Java CardÔ 2.2 Application Programming Interface, and the
Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
This specification describes the required behavior of the Java Card 2.2 Virtual
Machine (VM) that developers should adhere to when creating an implementation. An
implementation within the context of this document refers to a licensee’s
implementation of the Java Card Virtual Machine (VM), Application Programming
Interface (API), Converter, or other component, based on the Java Card technology
specifications. A Reference Implementation is an implementation produced by Sun
Microsystems, Inc. Application software written for the Java Card platform is
referred to as a Java Card applet.
Who Should Use This Specification?
This document is for licensees of the Java Card technology to assist them in creating
an implementation, developing a specification to extend the Java Card technology
specifications, or in creating an extension to the Java Card Runtime Environment
(JCRE). This document is also intended for Java Card applet developers who want a
more detailed understanding of the Java Card technology specifications.
Preface
xi
Before You Read This Specification
Before reading this document, you should be familiar with the Java programming
language, the Java Card technology specifications, and smart card technology. A
good resource for becoming familiar with Java technology and Java Card technology
is the Sun Microsystems, Inc. website, located at: http://java.sun.com.
How This Book Is Organized
Chapter 1, “Introduction,” provides an overview of the Java Card Virtual Machine
architecture.
Chapter 2, “A Subset of the Java Virtual Machine,” describes the subset of the Java
programming language and Virtual Machine that is supported by the Java Card
specification.
Chapter 3, “Structure of the Java Card Virtual Machine,” describes the differences
between the Java Virtual Machine and the Java Card Virtual Machine.
Chapter 4, “Binary Representation,” provides information about how Java Card
programs are represented in binary form.
Chapter 5, “The Export File Format,” describes the export file used to link code
against another package.
Chapter 6, “The CAP File Format,” describes the format of the CAP file.
Chapter 7, “Java Card Virtual Machine Instruction Set,” describes the byte codes
(opcodes) that comprise the Java Card Virtual Machine instruction set.
Chapter 8, “Tables of Instructions,” summarizes the Java Card Virtual Machine
instructions in two different tables: one sorted by Opcode Value and the other sorted
by Mnemonic.
“Glossary” provides definitions of selected terms in this specification.
Prerequisites
This specification is not intended to stand on its own; rather it relies heavily on
existing documentation of the Java platform. In particular, two books are required
for the reader to understand the material presented here.
The JavaÔ Language Specification by James Gosling, Bill Joy, and Guy L. Steele
(Addison-Wesley, 1996) ISBN 0-201-31008-2 – contains the definitive definition of the
Java programming language. The Java Card 2.2 language subset defined here is
based on the language specified in this book.
xii
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
The Java™ Virtual Machine Specification Second Edition by Tim Lindholm and Frank
Yellin. (Addison-Wesley, 1999) ISBN 0-201-43294-3 – defines the standard operation
of the Java Virtual Machine. The Java Card virtual machine presented here is based
on the definition specified in this book.
Related Documents
References to various documents or products are made in this manual. You should
have the following documents available:
•
Java CardÔ 2.2 Application Programming Interface (Sun Microsystems, Inc., 2002)
•
Java CardÔ 2.2 Runtime Environment (JCRE) Specification (Sun Microsystems,
Inc., 2002)
•
The JavaÔ Language Specification by James Gosling, Bill Joy, and Guy L. Steele
(Addison-Wesley, 1996).
•
The Java™ Virtual Machine Specification (Second Edition) by Tim Lindholm, and Frank
Yellin (Addison-Wesley, 1999).
•
The Java Class Libraries: An Annotated Reference, Second Edition (Java Series) by
Patrick Chan, Rosanna Lee and Doug Kramer (Addison-Wesley, 1999).
•
The Java Remote Method Invocation Specification, Revision 1.7, Sun Microsystems,
Inc.
•
ISO 7816 International Standard, First Edition 1987-07-01,
(http://www.iso.org).
Sun Documentation
This URL links you to technical information covering all aspects of the Java
platform.
http://developer.java.sun.com/developer/infodocs/
What Typographic Changes Mean
The following table describes the typographic changes used in this book.
Preface
xiii
Typeface
Meaning
Examples
AaBbCc123
The names of commands, files,
and directories; on-screen
computer output
Edit your .login file.
Use ls -a to list all files.
% You have mail.
bytecode
Java language bytecodes
invokespecial
AaBbCc123
What you type, when
contrasted with on-screen
computer output
% su
Password:
Procedural steps
1. Run cref in a new window.
Book titles, new words or terms,
words to be emphasized
Read Chapter 6 in the User’s Guide.
These are called class options.
You must be superuser to do this.
Command-line variable; replace
with a real name or value
To delete a file, type rm filename.
AaBbCc123
Acknowledgements
Java Card technology is based on Java technology. This specification could not exist
without all the hard work that went into the development of the Java platform
specifications. In particular, this specification is based significantly on the JavaÔ
Virtual Machine Specification. In order to maintain consistency with that specification,
as well as to make differences easier to notice, we have, where possible, used the
words, the style, and even the visual design of that book. Many thanks to Tim
Lindholm and Frank Yellin for providing a solid foundation for our work.
xiv
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
1
Introduction
1.1
Motivation
Java Card technology enables programs written in the Java programming language
to be run on smart cards and other small, resource-constrained devices. Developers
can build and test programs using standard software development tools and
environments, then convert them into a form that can be installed onto a Java Card
technology enabled device. Application software for the Java Card platform is called
an applet, or more specifically, a Java Card applet or card applet (to distinguish it
from browser applets).
While Java Card technology enables programs written in the Java programming
language to run on smart cards, such small devices are far too under-powered to
support the full functionality of the Java platform. Therefore, the Java Card platform
supports only a carefully chosen, customized subset of the features of the Java
platform. This subset provides features that are well-suited for writing programs for
small devices and preserves the object-oriented capabilities of the Java programming
language.
A simple approach to specifying a Java Card virtual machine would be to describe
the subset of the features of the Java virtual machine that must be supported to
allow for portability of source code across all Java Card technology enabled devices.
Combining that subset specification and the information in the Java Virtual Machine
Specification, smart card manufacturers could construct their own Java Card
implementations. While that approach is feasible, it has a serious drawback. The
resultant platform would be missing the important feature of binary portability of
Java Card applets.
The standards that define the Java platform allow for binary portability of Java
programs across all Java platform implementations. This “write once, run anywhere”
quality of Java programs is perhaps the most significant feature of the platform. Part
1
of the motivation for the creation of the Java Card platform was to bring just this
kind of binary portability to the smart card industry. In a world with hundreds of
millions or perhaps even billions of smart cards with varying processors and
configurations, the costs of supporting multiple binary formats for software
distribution could be overwhelming.
This Java CardÔ 2.2 Virtual Machine Specification is the key to providing binary
portability. One way of understanding what this specification does is to compare it
to its counterpart in the Java platform. The Java Virtual Machine Specification defines a
Java virtual machine as an engine that loads Java class files and executes them with
a particular set of semantics. The class file is a central piece of the Java architecture,
and it is the standard for the binary compatibility of the Java platform. The Java
CardÔ 2.2 Virtual Machine Specification also defines a file format that is the standard
for binary compatibility for the Java Card platform: the CAP file format is the form in
which software is loaded onto devices which implement a Java Card virtual
machine.
1.2
The Java Card Virtual Machine
The role of the Java Card virtual machine is best understood in the context of the
process for production and deployment of Java Card software. There are several
components that make up a Java Card system, including the Java Card virtual
machine, the Java Card Converter, a terminal installation tool, and an installation
program that runs on the device, as shown in Figures 1-1 and 1-2.
Development System
class
files
Converter
export
files
FIGURE 1-1
2
Java Card Package Conversion
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CAP file
Terminal
Device
CAP file
Installer
Installation
Tool
FIGURE 1-2
Virtual
Machine
Program Memory
Java Card Package Installation
Development of a Java Card applet begins as with any other Java program: a
developer writes one or more Java classes, and compiles the source code with a Java
compiler, producing one or more class files. The applet is run, tested and debugged
on a workstation using simulation tools to emulate the device environment. Then,
when an applet is ready to be downloaded to a device, the class files comprising
the applet are converted to a CAP (converted applet) file using a Java Card Converter.
The Java Card Converter takes as input all of the class files which make up a Java
package. A package that contains one or more applets is refered to as an applet
package. Otherwise the package is refered to as a library package. The Java Card
Converter also takes as input one or more export files. An export file contains
name and link information for the contents of other packages that are imported by
the classes being converted. When an applet or library package is converted, the
converter can also produce an export file for that package.
After conversion, the CAP file is copied to a card terminal, such as a desktop
computer with a card reader peripheral. Then an installation tool on the terminal
loads the CAP file and transmits it to the Java Card technology enabled device. An
installation program on the device receives the contents of the CAP file and prepares
the applet to be run by the Java Card virtual machine. The virtual machine itself
need not load or manipulate CAP files; it need only execute the applet code found in
the CAP file that was loaded onto the device by the installation program.
The division of functionality between the Java Card virtual machine and the
installation program keeps both the virtual machine and the installation program
small. The installation program may be implemented as a Java program and
executed on top of the Java Card virtual machine. Since Java Card instructions are
denser than typical machine code, this may reduce the size of the installer. The
modularity may enable different installers to be used with a single Java Card virtual
machine implementation.
Chapter 1
Introduction
3
1.3
Java Language Security
One of the fundamental features of the Java virtual machine is the strong security
provided in part by the class file verifier. Many devices that implement the Java
Card platform may be too small to support verification of CAP files on the device
itself. This consideration led to a design that enables verification on a device but
does not rely on it. The data in a CAP file that is needed only for verification is
packaged separately from the data needed for the actual execution of its applet. This
allows for flexibility in how security is managed in an implementation.
There are several options for providing language-level security on a Java Card
technology enabled device. The conceptually simplest is to verify the contents of a
CAP file on the device as it is downloaded or after it is downloaded. This option
might only be feasible in the largest of devices. However, some subset of verification
might be possible even on smaller devices. Other options rely on some combination
of one or more of: physical security of the installation terminal, a cryptographically
enforced chain of trust from the source of the CAP file, and pre-download verification
of the contents of a CAP file.
The Java Card platform standards say as little as possible about CAP file installation
and security policies. Since smart cards must serve as secure processors in many
different systems with different security requirements, it is necessary to allow a great
deal of flexibility to meet the needs of smart card issuers and users.
1.4
Java Card Runtime Environment
Security
The standard runtime environment for the Java Card platform is the Java Card
Runtime Environment (JCRE). The JCRE consists of an implementation of the Java
Card virtual machine along with the Java Card API classes. While the Java Card
virtual machine has responsibility for ensuring Java language-level security, the
JCRE imposes additional runtime security requirements on devices that implement
the JCRE, which results in a need for additional features on the Java Card virtual
machine. Throughout this document, these additional features are designated as
JCRE-specific.
4
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
The basic runtime security feature imposed by the JCRE enforces isolation of applets
using what is called an applet firewall. The applet firewall prevents the objects that
were created by one applet from being used by another applet. This prevents
unauthorized access to both the fields and methods of class instances, as well as the
length and contents of arrays.
Isolation of applets is an important security feature, but it requires a mechanism to
allow applets to share objects in situations where there is a need to interoperate. The
JCRE allows such sharing using the concept of shareable interface objects. These
objects provide the only way an applet can make its objects available for use by
other applets. For more information about using shareable interface objects, see the
description of the interface javacard.framework.Shareable in the Java CardÔ 2.2
Application Programming Interface specification. Some descriptions of firewall-related
features will make reference to the Shareable interface.
The applet firewall also protects from unauthorized use the objects owned by the
JCRE itself. The JCRE can use mechanisms not reflected in the Java Card API to
make its objects available for use by applets. A full description of the JCRE-related
isolation and sharing features can be found in the Java CardÔ 2.2 Runtime
Environment (JCRE) Specification.
Chapter 1
Introduction
5
6
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
2
A Subset of the Java Virtual Machine
This chapter describes the subset of the Java virtual machine and language that is
supported in the Java Card 2.2 platform.
2.1
Why a Subset is Needed
It would be ideal if programs for smart cards could be written using all of the Java
programming language, but a full implementation of the Java virtual machine is far
too large to fit on even the most advanced resource-constrained devices available
today.
A typical resource-constrained device has on the order of 1.2K of RAM, 16K of nonvolatile memory (EEPROM or flash) and 32K of ROM. The code for implementing
string manipulation, single and double-precision floating point arithmetic, and
thread management would be larger than the ROM space on such a device. Even if it
could be made to fit, there would be no space left over for class libraries or
application code. RAM resources are also very limited. The only workable option is
to implement Java Card technology as a subset of the Java platform.
2.2
Java Card Language Subset
Applets written for the Java Card platform are written in the Java programming
language. They are compiled using Java compilers. Java Card technology uses a
subset of the Java language, and familiarity with the Java platform is required to
understand the Java Card platform.
7
The items discussed in this section are not described to the level of a language
specification. For complete documentation on the Java programming language, see
The Java Language Specification.
2.2.1
Unsupported Items
The items listed in this section are elements of the Java programming language and
platform that are not supported by the Java Card platform.
2.2.1.1
Unsupported Features
Dynamic Class Loading
Dynamic class loading is not supported in the Java Card platform. An
implementation of the Java Card platform is not able to load classes dynamically.
Classes are either masked into the card during manufacturing or downloaded
through an installation process after the card has been issued. Programs executing
on the card may only refer to classes that already exist on the card, since there is no
way to download classes during the normal execution of application code.
Security Manager
Security management in the Java Card platform differs significantly from that of the
Java platform. In the Java platform, there is a Security Manager class
(java.lang.SecurityManager) responsible for implementing security features. In
the Java Card platform, language security policies are implemented by the virtual
machine. There is no Security Manager class that makes policy decisions on whether
to allow operations.
Finalization
Finalization is also not supported. finalize() will not be called automatically by
the Java Card virtual machine.
Threads
The Java Card virtual machine does not support multiple threads of control. Java
Card programs cannot use class Thread or any of the thread-related keywords in the
Java programming language.
8
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Cloning
The Java Card platform does not support cloning of objects. Java Card API class
Object does not implement a clone method, and there is no Cloneable interface
provided.
Access Control in Java Packages
The Java Card language subset supports the package access control defined in the
Java language. However, the cases that are not supported are as follows.
2.2.1.2
■
If a class implements a method with package access visibility, a subclass cannot
override the method and change the access visibility of the method to protected
or public.
■
A public class cannot contain a public or protected field of type reference to a
package-visible class.
■
A public class cannot contain a public or protected method with a return type of
type reference to a package-visible class.
■
A public or protected method in a public class cannot contain a formal parameter
of type reference to a package-visible class.
■
A package-visible class that is extended by a public class cannot define any public
or protected methods or fields.
■
A package-visible interface that is implemented by a public class cannot define
any fields.
■
A package-visible interface cannot be extended by an interface with public access
visibility.
Keywords
The following keywords indicate unsupported options related to native methods,
threads, floating point, and memory management.
native
strictfp
2.2.1.3
synchronized
transient
volatile
Unsupported Types
The Java Card platform does not support types char, double, float and long. It
also does not support arrays of more than one dimension.
Chapter 2
A Subset of the Java Virtual Machine
9
2.2.1.4
Classes
In general, none of the Java core API classes are supported in the Java Card
platform. Some classes from the java.lang package are supported (see §2.2.2.4), but
none of the rest are. For example, classes that are not supported are String, Thread
(and all thread-related classes), wrapper classes such as Boolean and Integer, and
class Class.
System
Class java.lang.System is not supported. Java Card technology supplies a class
javacard.framework.JCSystem, which provides an interface to system behavior.
2.2.2
Supported Items
If a language feature is not explicitly described as unsupported, it is part of the
supported subset. Notable supported features are described in this section.
2.2.2.1
Features
Packages
Software written for the Java Card platform follows the standard rules for the Java
platform packages. Java Card API classes are written as Java source files, which
include package designations. Package mechanisms are used to identify and control
access to classes, static fields and static methods. Except as noted in “Access Control
in Java Packages” (§2.2.1.1), packages in the Java Card platform are used exactly the
way they are in the Java platform.
Dynamic Object Creation
The Java Card platform programs supports dynamically created objects, both class
instances and arrays. This is done, as usual, by using the new operator. Objects are
allocated out of the heap.
A Java Card virtual machine will not necessarily garbage collect objects. Any object
allocated by a virtual machine may continue to exist and consume resources even
after it becomes unreachable. See section §2.2.3.2 for more information regarding
support for an optional object deletion mechanism.
10
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Virtual Methods
Since Java Card objects are Java programming language objects, invoking virtual
methods on objects in a program written for the Java Card platform is exactly the
same as in a program written for the Java platform. Inheritance is supported,
including the use of the super keyword.
Interfaces
Java Card classes may define or implement interfaces as in the Java programming
language. Invoking methods on interface types works as expected. Type checking
and the instanceof operator also work correctly with interfaces.
Exceptions
Java Card programs may define, throw and catch exceptions, as in Java programs.
Class Throwable and its relevant subclasses are supported. Some Exception and
Error subclasses are omitted, since those exceptions cannot occur in the Java Card
platform. See §2.3.3 for specification of errors and exceptions.
2.2.2.2
Keywords
The following keywords are supported. Their use is the same as in the Java
programming language.
abstract
boolean
break
byte
case
catch
class
continue
2.2.2.3
default
do
else
extends
final
finally
for
goto
if
implements
import
instanceof
int
interface
new
package
private
protected
public
return
short
static
super
switch
this
throw
throws
try
void
while
Types
Java programming language types boolean, byte, short, and int are supported.
Objects (class instances and single-dimensional arrays) are also supported. Arrays
can contain the supported primitive data types, objects, and other arrays.
Some Java Card implementations might not support use of the int data type. (Refer
to §2.2.3.1)
Chapter 2
A Subset of the Java Virtual Machine
11
2.2.2.4
Classes
Most of the classes in the java.lang package are not supported in Java Card. The
following classes from java.lang are supported on the card in a limited form.
Object
Java Card classes descend from java.lang.Object, just as in the Java programming
language. Most of the methods of Object are not available in the Java Card API, but
the class itself exists to provide a root for the class hierarchy.
Throwable
Class Throwable and its subclasses are supported. Most of the methods of
Throwable are not available in the Java Card API, but the class itself exists to
provide a common ancestor for all exceptions.
2.2.3
Optionally Supported Items
This section describes the optional features of the Java Card platform. An optional
feature is not required to be supported in a Java Card compatible implementation.
However, if an implementation does include support for an optional feature, it must
be supported fully, and exactly as specified in this document.
2.2.3.1
Integer Data Type
The int keyword and 32-bit integer data type need not be supported in a Java Card
implementation. A Java Card virtual machine that does not support the int data
type will reject programs which use the int data type or 32-bit intermediate values.
The result of an arithmetic expression produced by a Java Card virtual machine
must be equal to the result produced by a Java virtual machine, regardless of the
input values. A Java Card virtual machine that does not support the int data type
must reject expressions that could produce a different result.
2.2.3.2
Object Deletion Mechanism
Java Card 2.2 technology offers an optional, object deletion mechanism. Applications
designed to run on these implementations can use the facility by invoking the
appropriate API. See Java CardÔ 2.2 Application Programming Interface. But, the
12
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
facility is only suitable for updating large objects such as certificates and keys
atomically. Therefore, application programmers should conserve on the allocation of
objects.
2.2.4
Limitations of the Java Card Virtual Machine
The limitations of resource-constrained hardware prevent Java Card virtual
machines from supporting the full range of functionality of certain Java platform
features. The features in question are supported, but a particular virtual machine
may limit the range of operation to less than that of the Java platform.
To ensure a level of portability for application code, this section establishes a
minimum required level for partial support of these language features.
The limitations here are listed as maximums from the application programmer’s
perspective. Java packages that do not violate these maximum values can be
converted into Java Card CAP files, and will be portable across all Java Card
implementations. From the Java Card virtual machine implementer’s perspective,
each maximum listed indicates a minimum level of support that will allow
portability of applets.
2.2.4.1
Packages
Package References
A package can reference at most 128 other packages.
Package Name
The fully qualified name of a package may contain a maximum of 255 characters.
The package name size is further limited if it contains one or more characters which,
when represented in UTF-8 format, requires multiple bytes.
2.2.4.2
Classes
Classes in a Package
A package can contain at most 255 classes and interfaces.
Chapter 2
A Subset of the Java Virtual Machine
13
Interfaces
A class can implement at most 15 interfaces, including interfaces implemented by
superclasses.
An interface can inherit from at most 14 superinterfaces.
Static Fields
A class in an applet package can have at most 256 public or protected static non-final
fields. A class in a library package can have at most 255 public or protected static
non-final fields. There is no limit on the number of static final fields (constants)
declared in a class.
Static Methods
A class in an applet package can have at most 256 public or protected static methods.
A class in a library package can have at most 255 public or protected static methods.
2.2.4.3
Objects
Methods
A class can implement a maximum of 128 public or protected instance methods, and
a maximum of 128 instance methods with package visibility. These limits include
inherited methods.
Class Instances
Class instances can contain a maximum of 255 fields, where an int data type is
counted as occupying two fields.
Arrays
Arrays can hold a maximum of 32767 fields.
14
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
2.2.4.4
Methods
The maximum number of variables that can be used in a method is 255. This limit
includes local variables, method parameters, and, in the case of an instance method
invocation, a reference to the object on which the instance method is being invoked
(i.e. this). An int data type is counted as occupying two local variables.
A method can have at most 32767 Java Card virtual machine bytecodes. The number
of Java Card bytecodes may differ from the number of Java bytecodes in the Java
virtual machine implementation of that method.
The maximum depth of an operand stack associated with a method is 255 16-bit
cells.
2.2.4.5
Switch Statements
The format of the Java Card virtual machine switch instructions limits switch
statements to a maximum of 65536 cases. This limit is far greater than the limit
imposed by the maximum size of methods (§2.2.4.4).
2.2.4.6
Class Initialization
The Java Card virtual machine contains limited support for class initialization
because there is no general mechanism for executing <clinit> methods. Support for
<clinit> methods is limited to the initialization of static field values with the
following constraints:
■
Static fields of applet packages may only be initialized to primitive compile-time
constant values, or arrays of primitive compile-time constants.
■
Static fields of user libraries may only be initialized to primitive compile-time
constant values.
■
Only static fields declared in the current class may be initialized in the <clinit>
method.
Primitive constant data types include boolean, byte, short, and int.
Given Java source files that adhere to these language-level constraints on static field
initialization, it is expected that reasonable Java compilers will:
■
■
Inline constants in the bytecodes that reference static final primitive fields that are
initialized in the declaration statement.
Produce only the following bytecodes:
■
load a value on the stack: iconst_[m1,0-5], [b|s]ipush, ldc, ldc_w,
aconst_null
■
create an array: newarray([byte|short|boolean|int] )
Chapter 2
A Subset of the Java Virtual Machine
15
2.2.5
■
duplicate items on the stack: dup
■
store values in arrays or static fields: [b|i|s]astore, putstatic
■
return from method: return
Multiselectable Applets Restrictions
Applets that implement the javacard.framework.Multiselectable interface are
called multiselectable applets. For more details on multiselection, please see the Java
CardÔ 2.2 Runtime Environment (JCRE) Specification.
All applets within a package shall be multiselectable, or none shall be.
2.2.6
Java Card Remote Method Invocation (RMI)
Restrictions
This section defines the subset of the RMI system that is supported by Java Card
RMI (JCRMI).
2.2.6.1
Remote Classes and Remote Interfaces
A class is remote if it or any of its superclasses implements a remote interface.
A remote interface is an interface which satisfies the following requirements:
■
■
■
The interface name is java.rmi.Remote or the interface extends, directly or
indirectly, the interface java.rmi.Remote.
Each method declaration in the remote interface or its super-interfaces includes
the exception java.rmi.RemoteException (or one of its superclasses) in its
throws clause.
In a remote method declaration, if a remote object is declared as a return type, it
is declared as the remote interface, not the implementation class of that interface.
In addition, JCRMI imposes additional constraints on the definition of remote
methods. These constraints are as a result of the Java Card language subset and
other feature limitations. For more information, see sections §2.2.6.2 and §2.2.6.3.
2.2.6.2
Access Control of Remote Interfaces
The Java RMI system supports the package access control defined in the Java
language. However, JCRMI does not support package-visible remote interfaces.
16
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
2.2.6.3
Parameters and Return Values
The parameters of a remote method must only include parameters of the following
types:
■
■
any primitive type supported by Java Card technology (boolean, byte, short,
int),
any single-dimension array type of an primitive type supported by Java Card
technology (boolean[], byte[], short[], int[]).
The return type of a remote method must only be one of the following types:
■
■
■
■
2.3
any primitive type supported by Java Card (boolean, byte, short, int),
any single-dimension array type of an primitive type supported by Java Card
(boolean[], byte[], short[], int[]),
any remote interface type
type void
Java Card VM Subset
Java Card technology uses a subset of the Java virtual machine, and familiarity with
the Java platform is required to understand the Java Card virtual machine.
The items discussed in this section are not described to the level of a virtual machine
specification. For complete documentation on the Java virtual machine, refer to the
The Java™ Virtual Machine Specification.
2.3.1
class File Subset
The operation of the Java Card virtual machine can be defined in terms of standard
Java platform class files. Since the Java Card virtual machine supports only a subset
of the behavior of the Java virtual machine, it also supports only a subset of the
standard class file format.
2.3.1.1
Not Supported in Class Files
Field Descriptors
Field descriptors may not contain BaseType characters C, D, F or J. ArrayType
descriptors for arrays of more than one dimension may not be used.
Chapter 2
A Subset of the Java Virtual Machine
17
Constant Pool
Constant pool table entries with the following tag values are not supported.
Constant Type
Value
CONSTANT_String
8
CONSTANT_Float
4
CONSTANT_Long
5
CONSTANT_Double
6
TABLE 2-1
Unsupported Java constant pool tags
Fields
In field_info structures, the access flags ACC_VOLATILE and ACC_TRANSIENT are
not supported.
Methods
In method_info structures, the access flags ACC_SYNCHRONIZED, ACC_STRICT, and
ACC_NATIVE are not supported.
2.3.1.2
Supported in Class Files
ClassFile
All items in the ClassFile structure are supported.
Field Descriptors
Field descriptors may contain BaseType characters B, I, S and Z, as well as any
ObjectType. ArrayType descriptors for arrays of a single dimension may also be
used.
Method Descriptors
All forms of method descriptors are supported.
18
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Constant pool
Constant pool table entry with the following tag values are supported.
Constant Type
Value
CONSTANT_Class
7
CONSTANT_Fieldref
9
CONSTANT_Methodref
10
CONSTANT_InterfaceMethodref
11
CONSTANT_Integer
3
CONSTANT_NameAndType
12
CONSTANT_Utf8
1
TABLE 2-2
Supported Java constant pool tags.
Fields
In field_info structures, the supported access flags are ACC_PUBLIC, ACC_PRIVATE,
ACC_PROTECTED, ACC_STATIC and ACC_FINAL.
The remaining components of field_info structures are fully supported.
Methods
In method_info structures, the supported access flags are ACC_PUBLIC,
ACC_PRIVATE, ACC_PROTECTED, ACC_STATIC, ACC_FINAL and ACC_ABSTRACT.
The remaining components of method_info structures are fully supported.
Attributes
The attribute_info structure is supported. The Code, ConstantValue,
Exceptions, LocalVariableTable, Synthetic, InnerClasses, and Deprecated
attributes are supported.
Chapter 2
A Subset of the Java Virtual Machine
19
2.3.2
Bytecode Subset
The following sections detail the bytecodes that are either supported or unsupported
in the Java Card platform. For more details, refer to Chapter 7, “Java Card Virtual
Machine Instruction Set.”
2.3.2.1
Unsupported Bytecodes
lconst_<l>
lload
fload_<n>
daload
dstore
lastore
ladd
fsub
dmul
lrem
fneg
lushr
i2l
l2f
d2i
lcmp
dcmpg
monitorenter
jsr_w
20
fconst_<f>
fload
dload_<n>
caload
lstore_<n>
fastore
fadd
dsub
ldiv
frem
dneg
land
i2f
l2d
d2l
fcmpl
lreturn
monitorexit
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
dconst_<d>
dload
laload
lstore
fstore_<n>
dastore
dadd
lmul
fdiv
drem
lshl
lor
i2d
f2i
d2f
fcmpg
freturn
multianewarray
ldc2_w2
lload_<n>
faload
fstore
dstore_<n>
castore
lsub
fmul
ddiv
lneg
lshr
lxor
l2i
f2d
i2c
dcmpl
dreturn
goto_w
2.3.2.2
Supported Bytecodes
nop
sipush
aload
aaload
astore
aastore
pop2
dup2
iadd
irem
ishr
iinc
ificmp_<cond>
ret
areturn
getfield
invokestatic
anewarray
instanceof
2.3.2.3
aconst_null
ldc
iload_<n>
baload
istore_<n>
bastore
dup
dup2_x1
isub
ineg
iushr
i2b
ifacmp_<cond>
tableswitch
return
putfield
invokeinterface
arraylength
wide
iconst_<i>
ldc_w
aload_<n>
saload
astore_<n>
sastore
dup_x1
dup2_x2
imul
ior
iand
i2s
goto
lookupswitch
getstatic
invokevirtual
new
athrow
ifnull
bipush
iload
iaload
istore
iastore
pop
dup_x2
swap
idiv
ishl
ixor
if<cond>
jsr
ireturn
putstatic
invokespecial
newarray
checkcast
ifnonnull
Static Restrictions on Bytecodes
A class file must conform to the following restrictions on the static form of
bytecodes.
ldc, ldc_w
The ldc and ldc_w bytecodes can only be used to load integer constants. The
constant pool entry at index must be a CONSTANT_Integer entry. If a program
contains an ldc or ldc_w instruction that is used to load an integer value less than
-32768 or greater than 32767, that program will require the optional int instructions
(§2.2.3.1).
Chapter 2
A Subset of the Java Virtual Machine
21
lookupswitch
The value of the npairs operand must be less than 65536. This limit is far greater than
the limit imposed by the maximum size of methods (§2.2.4.4). If a program contains
a lookupswitch instruction that uses keys of type int, that program will require
the optional int instructions (§2.2.3.1). Otherwise, key values must be in the range
-32768 to 32767.
tableswitch
The bytecode can contain at most 65536 cases. This limit is far greater than the limit
imposed by the maximum size of methods (§2.2.4.4). If a program does not use the
optional int instructions (§2.2.3.1), the values of the high and low operands must
both be at least -32768 and at most 32767.
wide
The wide bytecode can only be used with an iinc instruction.
2.3.3
Exceptions
Java Card provides full support for the Java platform’s exception mechanism. Users
can define, throw and catch exceptions just as in the Java platform. Java Card also
makes use of the exceptions and errors defined in The Java Language Specification. An
updated list of the Java platform’s exceptions is provided in the JDK documentation.
Not all of the Java platform’s exceptions are supported in Java Card. Exceptions
related to unsupported features are naturally not supported. Class loader exceptions
(the bulk of the checked exceptions) are not supported.
Note that some exceptions may be supported to the extent that their error conditions
are detected correctly, but classes for those exceptions will not necessarily be present
in the API.
The supported subset is described in the tables below.
22
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
2.3.3.1
Uncaught and Uncatchable Exceptions
In the Java platform, uncaught exceptions and errors will cause the virtual machine’s
current thread to exit. As the Java Card virtual machine is single-threaded, uncaught
exceptions or errors will cause the virtual machine to halt. Further response to
uncaught exceptions or errors after halting the virtual machine is an
implementation-specific policy, and is not mandated in this document.
Some error conditions are known to be unrecoverable at the time they are thrown.
Throwing a runtime exception or error that cannot be caught will also cause the
virtual machine to halt. As with uncaught exceptions, implementations may take
further responses after halting the virtual machine. Uncatchable exceptions and
errors which are supported by the Java Card platform may not be reflected in the
Java Card API, though the Java Card platform will correctly detect the error
condition.
2.3.3.2
Checked Exceptions
Exception
Supported
TABLE 2-3
Not Supported
·
·
·
·
·
·
·
ClassNotFoundException
CloneNotSupportedException
IllegalAccessException
InstantiationException
InterruptedException
NoSuchFieldException
NoSuchMethodException
Support of Java checked exceptions
Chapter 2
A Subset of the Java Virtual Machine
23
2.3.3.3
Runtime Exceptions
Runtime Exception
Supported
ArithmeticException
ArrayStoreException
ClassCastException
·
·
·
IllegalArgumentException
IllegalThreadStateException
NumberFormatException
IllegalMonitorStateException
IllegalStateException
IndexOutOfBoundsException
ArrayIndexOutOfBoundsException
StringIndexOutOfBoundsException
NegativeArraySizeException
NullPointerException
SecurityException
TABLE 2-4
24
·
·
·
·
·
·
·
·
·
·
·
Support of Java runtime exceptions
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Not Supported
2.3.3.4
Errors
Error
Supported
LinkageError
ClassCircularityError
ClassFormatError
·
·
·
ExceptionInInitializerError
IncompatibleClassChangeError
AbstractMethodError
IllegalAccessError
InstantiationError
NoSuchFieldError
NoSuchMethodError
NoClassDefFoundError
UnsatisfiedLinkError
VerifyError
ThreadDeath
VirtualMachineError
InternalError
OutOfMemoryError
StackOverflowError
UnknownError
·
·
·
·
·
·
·
·
·
·
TABLE 2-5
Not Supported
·
·
·
·
·
·
Support of Java errors
Chapter 2
A Subset of the Java Virtual Machine
25
26
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
3
Structure of the Java Card Virtual
Machine
The specification of the Java Card virtual machine is in many ways quite similar to
that of the Java Virtual Machine. This similarity is of course intentional, as the design
of the Java Card virtual machine was based on that of the Java Virtual Machine.
Rather than reiterate all the details of this specification which are shared with that of
the Java Virtual Machine, this chapter will mainly refer to its counterpart in the Java
Virtual Machine Specification, 2nd Edition, providing new information only where the
Java Card virtual machine differs.
3.1
Data Types and Values
The Java Card virtual machine supports the same two kinds of data types as the Java
Virtual Machine: primitive types and reference types. Likewise, the same two kinds of
values are used: primitive values and reference values.
The primitive data types supported by the Java Card virtual machine are the numeric
types, the boolean type, and the returnAddress type. The numeric types consist only
of these types:
■
■
byte, whose values are 8-bit signed two’s complement integers
short, whose values are 16-bit signed two’s complement integers
Some Java Card virtual machine implementations may also support an additional
integral type:
■
int, whose values are 32-bit signed two’s complement integers
Support for the boolean type is identical to that in the Java Virtual Machine. The
value 1 is used to represent true and the value of 0 is used to represent false.
Support for reference types is identical to that in the Java Virtual Machine.
27
3.2
Words
The Java Card virtual machine is defined in terms of an abstract storage unit called a
word. This specification does not mandate the actual size in bits of a word on a
specific platform. A word is large enough to hold a value of type byte, short,
reference or returnAddress. Two words are large enough to hold a value of type
int.
The actual storage used for values in an implementation is platform-specific. There
is enough information present in the descriptor component of a CAP file to allow an
implementation to optimize the storage used for values in variables and on the
stack.
3.3
Runtime Data Areas
The Java Card virtual machine can support only a single thread of execution. Any
runtime data area in the Java Virtual Machine which is duplicated on a per-thread
basis will have only one global copy in the Java Card virtual machine.
The Java Card virtual machine's heap is not required to be garbage collected. Objects
allocated from the heap will not necessarily be reclaimed.
This specification does not include support for native methods, so there are no
native method stacks.
Otherwise, the runtime data areas are as documented for the Java Virtual Machine.
3.4
Contexts
Each applet running on a Java Card virtual machine is associated with an execution
context. The Java Card virtual machine uses the context of the current frame to
enforce security policies for inter-applet operations.
There is a one-to-one mapping between contexts and packages in which applets are
defined. An easy way to think of a context is as the runtime equivalent of a package,
since Java packages are compile-time constructs and have no direct representation at
runtime. As a consequence, all applet instances from the same package will share the
same context.
28
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
The Java Card Runtime Environment also has its own context. Framework objects
execute in this JCRE context.
The context of the currently executing method is known as the current context. Every
object in a Java Card virtual machine is owned by a particular context. The owning
context is the context that was current when the object was created.
When a method in one context successfully invokes a method on an object in another
context, the Java Card virtual machine performs a context switch. Afterwards the
invoked method's context becomes the current context. When the invoked method
returns, the current context is switched back to the previous context.
3.5
Frames
Java Card virtual machine frames are very similar to those defined for the Java
Virtual Machine. Each frame has a set of local variables and an operand stack.
Frames also contain a reference to a constant pool, but since all constant pools for all
classes in a package are merged, the reference is to the constant pool for the current
class’ package.
Each frame also includes a reference to the context in which the current method is
executing.
3.6
Representation of Objects
The Java Card virtual machine does not mandate a particular internal structure for
objects or a particular layout of their contents. However, the core components in a
CAP file are defined assuming a default structure for certain runtime structures (such
as descriptions of classes), and a default layout for the contents of dynamically
allocated objects. Information from the descriptor component of the CAP file can be
used to format objects in whatever way an implementation requires.
3.7
Special Initialization Methods
The Java Card virtual machine supports instance initialization methods exactly as does
the Java Virtual Machine.
Chapter 3
Structure of the Java Card Virtual Machine
29
The Java Card virtual machine includes only limited support for class or interface
initialization methods. There is no general mechanism for executing <clinit>
methods on a Java Card virtual machine. Instead, a CAP file includes information for
initializing class data as defined in section §2.2.4.6, “Class Initialization”.
3.8
Exceptions
Exception support in the Java Card virtual machine is identical to support for
exceptions in the Java Virtual Machine.
3.9
Binary File Formats
This specification defines two binary file formats which enable platformindependent development, distribution and execution of Java Card software.
The CAP file format describes files that contain executable code and can be
downloaded and installed onto a Java Card enabled device. A CAP file is produced
by a Java Card Converter tool, and contains a converted form of an entire package of
Java classes. This file format's relationship to the Java Card virtual machine is
analogous to the relationship of the class file format to the Java Virtual Machine.
The export file format describes files that contain the public linking information of
Java Card packages. A package's export file is used when converting client
packages of that package.
3.10
Instruction Set Summary
The Java Card virtual machine instruction set is quite similar to the Java Virtual
Machine instruction set. Individual instructions consist of a one-byte opcode and zero
or more operands. The pseudo-code for the Java Card virtual machine's instruction
fetch-decode-execute loop is the same. Multi-byte operand data is also encoded in
big-endian order.
There are a number of ways in which the Java Card virtual machine instruction set
diverges from that of the Java Virtual Machine. Most of the differences are due to the
Java Card virtual machine's more limited support for data types. Another source of
divergence is that the Java Card virtual machine is intended to run on 8-bit and 16-
30
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
bit architectures, whereas the Java Virtual Machine was designed for a 32-bit
architecture. The rest of the differences are all oriented in one way or another toward
optimizing the size or performance of either the Java Card virtual machine or Java
Card programs. These changes include inlining constant pool data directly in
instruction opcodes or operands, adding multiple versions of a particular instruction
to deal with different datatypes, and creating composite instructions for operations
on the current object.
3.10.1
Types and the Java Card Virtual Machine
The Java Card virtual machine supports only a subset of the types supported by the
Java Virtual Machine. This subset is described in Chapter 2, “A Subset of the Java
Virtual Machine.” Type support is reflected in the instruction set, as instructions
encode the data types on which they operate.
Given that the Java Card virtual machine supports fewer types than the Java Virtual
Machine, there is an opportunity for better support for smaller data types. Lack of
support for large numeric data types frees up space in the instruction set. This extra
instruction space has been used to directly support arithmetic operations on the
short data type.
Some of the extra instruction space has also been used to optimize common
operations. Type information is directly encoded in field access instructions, rather
than being obtained from an entry in the constant pool.
TABLE 3-1 summarizes the type support in the instruction set of the Java Card
virtual machine. Only instructions that exist for multiple types are listed. Wide and
composite forms of instructions are not listed either. A specific instruction, with type
information, is built by replacing the T in the instruction template in the opcode
column by the letter representing the type in the type column. If the type column for
some instruction is blank, then no instruction exists supporting that operation on
that type. For instance, there is a load instruction for type short, sload, but there is
no load instruction for type byte.
Chapter 3
Structure of the Java Card Virtual Machine
31
opcode
byte
short
int
Tspush
Tipush
bspush
bipush
sspush
sipush
iipush
Tconst
Tload
Tstore
Tinc
Taload
Tastore
Tadd
Tsub
Tmul
Tdiv
Trem
Tneg
Tshl
Tshr
Tushr
Tand
Tor
Txor
s2T
i2T
Tcmp
if_TcmpOP
Tlookupswitch
Ttableswitch
Treturn
getstatic_T
putstatic_T
getfield_T
putfield_T
TABLE 3-1
32
baload
bastore
sconst
sload
sstore
sinc
saload
sastore
sadd
ssub
smul
sdiv
srem
sneg
sshl
sshr
sushr
sand
sor
sxor
s2b
i2b
i2s
getstatic_b
putstatic_b
getfield_b
putfield_b
if_scmpOP
slookupswitch
stableswitch
sreturn
getstatic_s
putstatic_s
getfield_s
putfield_s
iconst
iload
istore
iinc
iaload
iastore
iadd
isub
imul
idiv
irem
ineg
ishl
ishr
iushr
iand
ior
ixor
s2i
reference
aconst
aload
astore
aaload
aastore
icmp
if_acmpOP
ilookupswitch
itableswitch
ireturn
getstatic_i
putstatic_i
getfield_i
putfield_i
Type support in the Java Card Virtual Machine Instruction Set
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
areturn
getstatic_a
putstatic_a
getfield_a
putfield_a
The mapping between Java storage types and Java Card virtual machine
computational types is summarized in TABLE 3-2.
Java (Storage) Type
Size in
Bits
Computational
Type
byte
8
short
short
16
short
int
32
int
TABLE 3-2
Storage types and computational types
Chapter 7, “Java Card Virtual Machine Instruction Set,” describes the Java Card
virtual machine instruction set in detail.
Chapter 3
Structure of the Java Card Virtual Machine
33
34
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
4
Binary Representation
This chapter presents information about the binary representation of Java Card
programs. Java Card binaries are usually contained in files, therefore this chapter
addresses binary representation in terms of this common case.
Several topics relating to binary representation are covered. The first section
describes the basic organization of program representation in export and CAP files,
as well as the use of the Java Archive (JAR) file containers. The second section covers
how Java Card applets and packages are named using unique identifiers. The third
section presents the scheme used for naming and linking items within Java Card
packages. The fourth and fifth sections describe the constraints for upward
compatibility between different versions of a Java Card binary program file, and
versions assigned based upon that compatibility.
4.1
Java Card File Formats
Java programs are represented in compiled, binary form as class files. Java class
files are used not only to execute programs on a Java virtual machine, but also to
provide type and name information to a Java compiler. In the latter role, a class file
is essentially used to document the API of its class to client code. That client code is
compiled into its own class file, including symbolic references used to dynamically
link to the API class at runtime.
Java Card technology uses a different strategy for binary representation of programs.
Executable binaries and interface binaries are represented in two separate files.
These files are respectively called CAP files (for converted applet) and export files.
35
4.1.1
Export File Format
Export files are not used directly on a device that implements a Java Card virtual
machine. However, the information in an export file is critical to the operation of
the virtual machine on a device. An export file can be produced by a Java Card
converter when a package is converted. This package’s export file can be used later
to convert another package that imports classes from the first package. Information
in the export file is included in the CAP file of the second package, then is used on
the device to link the contents of the second package to items imported from the first
package.
A Java Card export file contains the public interface information for an entire
package of classes. This means that an export file only contains information about
the public API of a package, and does not include information used to link classes
within a package.
The name of an export file is the last portion of the package specification followed
by the extension ‘.exp’. For example, the name of the export file of the
javacard.framework package must be framework.exp. Operating systems that
impose limitations on file name lengths may transform an export file’s name
according to their own conventions.
For a complete description of the Java Card export file format, see Chapter 5.
4.1.2
CAP File Format
A Java Card CAP file contains a binary representation of a package of classes that can
be installed on a device and used to execute the package’s classes on a Java Card
virtual machine.
A CAP file is produced by a Java Card converter when a package of classes is
converted. A CAP file consists of a set of components, each of which describes a
different aspect of the contents. The set of components in a CAP file can vary,
depending on whether the file contains a library or applet definition(s).
For a complete description of the Java Card CAP file format, see Chapter 6.
4.1.3
JAR File Container
The JAR file format is used as the container format for CAP files. What this
specification calls a “CAP file” is just a JAR file that contains the required set of CAP
components (see Chapter 6).
36
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CAP file components are stored as files in a JAR file. Each CAP file component is
located in a subdirectory called javacard that is in a directory representing the
package. For example, the CAP file components of the package com.sun.framework
are located in the directory com/sun/framework/javacard.
An export file may also be contained in a JAR file, whether that JAR file contains
CAP file components or not. If an export file is included, it must be located in the
same directory as the components for that package would be.
The name of a JAR file containing CAP file components is not defined as part of this
specification. Other files, including CAP file components for another package, may
also reside in a JAR file that contains CAP file components.
4.2
AID-based Naming
This section describes the mechanism used for naming applets and packages in Java
Card CAP files and export files, and custom components in Java Card CAP files. Java
class files use Unicode strings to name Java packages. As the Java Card platform
does not include support for strings, an alternative mechanism for naming is
provided.
ISO 7816 is a multipart standard that describes a broad range of technology for
building smart card systems. ISO 7816-5 defines the AID (application identifier) data
format to be used for unique identification of card applications (and certain kinds of
files in card file systems). The Java Card platform uses the AID data format to
identify applets and packages. AIDs are administered by the International Standards
Organization (ISO), so they can be used as unique identifiers.
4.2.1
The AID Format
This section presents a minimal description of the AID data format used in Java
Card technology. For complete details, refer to ISO 7816-5, AID Registration
Category ‘D’ format.
Chapter 4
Binary Representation
37
The AID format used by the Java Card platform is an array of bytes that can be
interpreted as two distinct pieces, as shown in FIGURE 4-1. The first piece is a 5-byte
value known as a RID (resource identifier). The second piece is a variable length
value known as a PIX (proprietary identifier extension). A PIX can be from 0 to 11
bytes in length. Thus an AID can be from 5 to 16 bytes in total length.
RID (5 bytes)
FIGURE 4-1
PIX (0-11 bytes)
AID Format
ISO controls the assignment of RIDs to companies, with each company obtaining its
own unique RID from the ISO. Companies manage assignment of PIXs for AIDs
using their own RIDs.
4.2.2
AID Usage
In the Java platform, packages are uniquely identified using Unicode strings and a
naming scheme based on internet domain names. In the Java Card platform,
packages and applets are identified using AIDs.
Any package that is represented in an export file must be assigned a unique AID.
The AID for a package is constructed from the concatenation of the company’s RID
and a PIX for that package. This AID corresponds to the string name for the package,
as shown in FIGURE 4-2.
package com.sun.card.test;
Sun’s RID
FIGURE 4-2
com.sun.card.test PIX
Mapping package identifiers to AIDs
Each applet installed on a Java Card technology enabled device must also have a
unique AID. This AID is constructed similarly to a package AID. It is a
concatenation of the applet provider’s RID and PIX for that applet. An applet AID
must not have the same value as the AID of any package or the AID of any other
applet. If a CAP file defines multiple applets, all applet AIDs in that CAP file must
have the same RID.
Custom components defined in a CAP file are also identified using AIDs. Like AIDs
for applets and packages, component AIDs are formed by concatenating a RID and a
PIX.
38
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
4.3
Token-based Linking
This section describes a scheme that allows downloaded software to be linked
against APIs on a Java Card technology enabled device. The scheme represents
referenced items as opaque tokens, instead of Unicode strings as are used in Java
class files. The two basic requirements of this linking scheme are that it allows
linking on the device, and that it does not require internal implementation details of
APIs to be revealed to clients of those APIs. Secondary requirements are that the
scheme be efficient in terms of resource use on the device, and have acceptable
performance for linking. And of course, it must preserve the semantics of the Java
language.
4.3.1
Externally Visible Items
Classes (including Interfaces) in Java packages may be declared with public or
package visibility. A class’s methods and fields may be declared with public,
protected, package or private visibility. For purposes of this document, we define
public classes, public or protected fields, and public or protected methods to be
externally visible from the package.
Each externally visible item must have a token associated with it to enable references
from other packages to the item to be resolved on a device. There are six kinds of
items in a package that require external identification.
■
■
■
■
■
■
4.3.2
Classes (including Interfaces)
Static Fields
Static Methods
Instance Fields
Virtual Methods
Interface Methods
Private Tokens
Items that are not externally visible are internally visible. Internally visible items are
not described in a package’s export file, but some such items use private tokens to
represent internal references. External references are represented by public tokens.
There are three kinds of items that can be assigned private tokens.
■
■
■
Instance Fields
Virtual Methods
Packages
Chapter 4
Binary Representation
39
4.3.3
The Export File and Conversion
An export file contains entries for externally visible items in the package. Each
entry holds the item’s name and its token. Some entries may include additional
information as well. For detailed information on the export file format, see
Chapter 5, “The Export File Format.”
The export file is used to map names for imported items to tokens during package
conversion. The Java Card converter uses these tokens to represent references to
items in an imported package.
For example, during the conversion of the class files of applet A, the export file of
javacard.framework is used to find tokens for items in the API that are used by the
applet. Applet A creates a new instance of framework class OwnerPIN. The
framework export file contains an entry for javacard.framework.OwnerPIN that
holds the token for this class. The converter places this token in the CAP file’s
constant pool to represent an unresolved reference to the class. The token value is
later used to resolve the reference on a device.
4.3.4
References – External and Internal
In the context of a CAP file, references to items are made indirectly through a
package’s constant pool. References to items in other packages are called external,
and are represented in terms of tokens. References to items in the same CAP file are
called internal, and are represented either in terms of tokens, or in a different internal
format.
An external reference to a class is composed of a package token and a class token.
Together those tokens specify a certain class in a certain package. An internal
reference to a class is a 15-bit value that is a pointer to the class structure’s location
within the CAP file.
An external reference to a static class member, either a field or method, consists of a
package token, a class token, and a token for the static field or static method. An
internal reference to a static class member is a 16-bit value that is a pointer to the
item’s location in the CAP file.
References to instance fields, virtual methods and interface methods consist of a
class reference and a token of the appropriate type. The class reference determines
whether the reference is external or internal.
40
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
4.3.5
Installation and Linking
External references in a CAP file can be resolved on a device from token form into the
internal representation used by the virtual machine.
A token can only be resolved in the context of the package that defines it. Just as the
export file maps from a package’s externally visible names to tokens, there is a set
of link information for each package on the device that maps from tokens to resolved
references.
4.3.6
Token Assignment
Tokens for an API are assigned by the API’s owner and published in the package
export file(s) for that API. Since the name-to-token mappings are published, an API
owner may choose any order for tokens (subject to the constraints listed below).
A particular device platform can resolve tokens into whatever internal
representation is most useful for that implementation of a Java Card virtual machine.
Some tokens may be resolved to indices. For example, an instance field token may be
resolved to an index into a class instance’s fields. In such cases, the token value is
distinct from and unrelated to the value of the resolved index.
4.3.7
Token Details
Each kind of item in a package has its own independent scope for tokens of that
kind. The token range and assignment rules for each kind are listed in TABLE 4-1.
Token Type
Range
Type
Scope
Package
Class
Static Field
Static Method
Instance Field
Virtual Method
0
0
0
0
0
0
Private
Public
Public
Public
Public or Private
Public or Private
Interface Method
0 - 127
Package
Package
Class
Class
Class
Class
Hierarchy
Class
TABLE 4-1
-
127
254
255
255
255
127
Public
Token Range, Type and Scope
Chapter 4
Binary Representation
41
4.3.7.1
Package
All package references from within a CAP file are assigned private package tokens.
Package token values must be in the range from 0 to 127, inclusive. The tokens for all
the packages referenced from classes in a CAP file are numbered consecutively
starting at zero. The ordering of package tokens is not specified.
4.3.7.2
Classes and Interfaces
All externally visible classes and interfaces in a package are assigned public class
tokens. Class token values must be in the range from 0 to 254, inclusive. The tokens
for all the public classes and interfaces in a package are numbered consecutively
starting at zero. The ordering of class tokens is not specified.
Package-visible classes and interfaces are not assigned tokens.
4.3.7.3
Static Fields
All externally visible static fields in a package are assigned public static field tokens.
The tokens for all externally visible static fields in a class are numbered
consecutively starting at zero. Static fields token values must be in the range from 0
to 255, inclusive. The ordering of static field tokens is not specified.
Package-visible and private static fields are not assigned tokens. In addition, no
tokens are assigned for final static fields that are initialized to primitive, compiletime constants, as these fields are never represented as fields in CAP files.
4.3.7.4
Static Methods and Constructors
All externally visible static methods and constructors in a package are assigned
public static method tokens. Constructors are included in this category because they
are statically bound. Static method token values must be in the range from 0 to 255,
inclusive. The tokens for all the externally visible static methods and constructors in
a class are numbered consecutively starting at zero. The ordering of static method
tokens is not specified.
Package-visible and private static methods as well as package-visible and private
constructors are not assigned tokens.
42
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
4.3.7.5
Instance Fields
All instance fields defined in a package are assigned either public or private instance
field tokens. The scope of a set of instance field tokens is limited to the class that
declares the instance fields, not including the fields declared by superclasses of that
class.
Instance field token values must be in the range from 0 to 255, inclusive. Public and
private tokens for instance fields are assigned from the same namespace. The tokens
for all the instance fields in a class are numbered consecutively starting at zero,
except that the token after an int field is skipped and the token for the following
field is numbered two greater than the token of the int field.
Within a class, tokens for externally visible fields must be numbered less than the
tokens for package and private fields. For public tokens, the tokens for reference
type fields must be numbered greater than the tokens for primitive type fields. For
private tokens, the tokens for reference type fields must be numbered less than the
tokens for primitive type fields. Beyond that, the ordering of instance field tokens in
a class is not specified.
Visibility
public and
protected fields
(public tokens)
Category
Type
Token Value
primitive
boolean
byte
short
byte[]
Applet
short[]
Object
int
0
short
9
reference
reference
package and
private fields
(private tokens)
FIGURE 4-3
4.3.7.6
primitive
1
2
3
4
5
6
7
Tokens for Instance Fields
Virtual Methods
Virtual methods are instance methods that are resolved dynamically. The set
includes all public, protected and package-visible instance methods. Private instance
methods and all constructors are not virtual methods, but instead are resolved
statically during compilation.
Chapter 4
Binary Representation
43
All virtual methods defined in a package are assigned either public or private virtual
method tokens. Virtual method token values must be in the range from 0 to 127,
inclusive. Public and private tokens for virtual methods are assigned from different
namespaces. The high bit of the byte containing a virtual method token is set to one
if the token is a private token.
Public tokens for the externally visible (public or protected) introduced virtual
methods in a class are numbered consecutively starting at one greater than the
highest numbered public virtual method token of the class’s superclass. If a method
overrides a method implemented in the class’s superclass, that method is assigned
the same token number as the method in the superclass. The high bit of the byte
containing a public virtual method token is always set to zero, to indicate it is a
public token. The ordering of public virtual method tokens in a class is not specified.
Private virtual method tokens are assigned to package-visible virtual methods. They
are assigned differently from public virtual method tokens. If a class and its
superclass are defined in the same package, the tokens for the package-visible
introduced virtual methods in that class are numbered consecutively starting at one
greater than the highest numbered private virtual method token of the class’s
superclass. If the class and its superclass are defined in different packages, the
tokens for the package-visible introduced virtual methods in that class are numbered
consecutively starting at zero. If a method overrides a method implemented in the
class’s superclass, that method uses the same token number as the method in the
superclass. The definition of the Java programming language specifies that
overriding a package-visible virtual method is only possible if both the class and its
superclass are defined in the same package. The high bit of the byte containing a
virtual method token is always set to one, to indicate it is a private token. The
ordering of private virtual method tokens in a class is not specified.
4.3.7.7
Interface Methods
All interface methods defined in a package are assigned public interface method
tokens, as interface methods are always public. Interface methods tokens values must
be in the range from 0 to 127, inclusive. The tokens for all the interface methods
defined in or inherited by an interface are numbered consecutively starting at zero.
The token value for an interface method in a given interface is unrelated to the token
values of that same method in any of the interface’s superinterfaces. Each interface
includes its own token values for all the methods inherited from super-interfaces as
well as its defined methods. The high bit of the byte containing an interface method
token is always set to zero, to indicate it is a public token. The ordering of interface
method tokens is not specified.
44
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
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.
FIGURE 4-4 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.
convert
with
p1
Export File
p2
CAP file
p1
CAP File
link with
(either)
p1'
CAP File
binary
compatible
with
FIGURE 4-4
Binary compatibility example
Chapter 4
Binary Representation
45
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.
46
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
4.5
Package Versions
Each implementation of a package in a Java Card system is assigned a pair of major
and minor version numbers. These version numbers are used to indicate binary
compatibility or incompatibility between successive implementations of a package.
4.5.1
Assigning
The major and minor versions of a package are assigned by the package provider. It
is recommended that the initial implementation of a package be assigned a major
version of 1 and a minor version of 0. However, any values may be chosen. It is also
recommended that when either a major or a minor version is incremented, it is
incremented exactly by 1.
A major version must be changed when a new implementation of a package is not
binary compatible with the previous implementation. The value of the new major
version must be greater than the major version of the previous implementation.
When a major version is changed, the associated minor version must be assigned the
value of 0.
When a new implementation of a package is binary compatible with the previous
implementation, it must be assigned a major version equal to the major version of
the previous implementation. The minor version assigned to the new
implementation must be greater than the minor version of the previous
implementation.
4.5.2
Linking
Both an export file and a CAP file contain the major and minor version numbers of
the package described. When a CAP file is installed on a Java Card enabled device a
resident image of the package is created, and the major and minor version numbers
are recorded as part of that image. When an export file is used during preparation
of a CAP file, the version numbers indicated in the export file are recorded in the CAP
file.
During installation, references from the package of the CAP file being installed to an
imported package can be resolved only when the version numbers indicated in the
export file used during preparation of the CAP file are compatible with the version
numbers of the resident image. They are compatible when the major version
numbers are equal and the minor version of the export file is less than or equal to
the minor version of the resident image.
Chapter 4
Binary Representation
47
48
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
5
The Export File Format
This chapter describes the export file format. Compliant Java Card Converters must
be capable of producing and consuming all export files that conform to the
specification provided in this chapter.
An export file consists of a stream of 8-bit bytes. All 16-bit and 32-bit quantities are
constructed by reading in two and four consecutive 8-bit bytes, respectively.
Multibyte data items are always stored in big-endian order, where the high-order
bytes come first.
This chapter defines its own set of data types representing Java Card export file
data: the types u1, u2, and u4 represent an unsigned one-, two-, and four-byte
quantities, respectively.
The Java Card export file format is presented using pseudo structures written in a
C-like structure notation. To avoid confusion with the fields of Java Card virtual
machine classes and class instances, the contents of the structures describing the Java
Card export file format are referred to as items. Unlike the fields of a C structure,
successive items are stored in the Java Card file sequentially, without padding or
alignment.
Variable-sized tables, consisting of variable-sized items, are used in several export
file structures. Although we will use C-like array syntax to refer to table items, the
fact that tables are streams of varying-sized structures means that it is not possible to
directly translate a table index into a byte offset into the table.
In a data structure that is referred to as an array, the elements are equal in size.
49
5.1
Export File Name
As described in §4.1.1, the name of a export file must be the last portion of the
package specification followed by the extension ‘.exp’. For example, the name of the
export file of the javacard.framework package must be framework.exp. Operating
systems that impose limitations on file name lengths may transform an export file’s
name according to its conventions.
5.2
Containment in a Jar File
As described in §4.1.3, Java Card CAP files are contained in a JAR file. If an export
file is also stored in a JAR file, it must also be located in a directory called javacard
that is a subdirectory of the package’s directory. For example, the framework.exp
file would be located in the subdirectory javacard/framework/javacard.
5.3
Ownership
An export file is owned by the entity that owns the package it represents. The
owner of a package defines the API of that package, and may or may not provide all
implementations of that package. All implementations, however, must conform to
the definition provided in the export file provided by the owner.
A particular example of export file ownership is the Java Card API packages. Sun
defines these packages. Sun also provides the export files for these packages. All
implementations of the Java Card API packages must conform to the definitions
provided by Sun, and comply with the token assignments provided in these export
files.
50
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
5.4
Hierarchies Represented
Classes and interfaces represented in an export file include public elements defined
within their respective hierarchies. For example, instead of indicating the immediate
superclass or superinterface, all public superclasses or superinterfaces are listed.
This design concept is applied not only to superclasses or superinterfaces, but also to
virtual methods and implemented interfaces.
5.5
Export File
An export file is defined by the following structure:
ExportFile {
u4 magic
u1 minor_version
u1 major_version
u2 constant_pool_count
cp_info constant_pool[constant_pool_count]
u2 this_package
u1 export_class_count
class_info classes[export_class_count]
}
The items in the ExportFile structure are as follows:
magic
The magic item contains the magic number identifying the ExportFile format; it has the value 0x00FACADE.
minor_version, major_version
The minor_version and major_version items are the minor and major version numbers of this export file. Together, a major and a minor version number determine the version of the export file format. If an export file has the
major version number of M and minor version number of m, the version of the
export file’s format is M.m.
A change in the major version number indicates a major incompatibility
change, one that requires a fundamentally different Java Card virtual machine.
A Java Card virtual machine is not required to support export files with different major version numbers. A Java Card virtual machine is required to support
export files having a given major version number and all valid minor version
numbers in the range 0 through some particular minor_version where a valid
Chapter 5
The Export File Format
51
minor version number is a minor version number that has been defined in a
version of the Java Card Virtual Machine Specification.
In this specification, the major version of the export file format has the value 2
and the minor version has the value 2. Only Sun Microsystems, Inc. may define
the meaning and values of new export file format versions.
constant_pool_count
The constant_pool_count item is a non-zero, positive value that indicates
the number of constants in the constant pool.
constant_pool[]
The constant_pool is a table of variable-length structures representing various string constants, class names, field names and other constants referred to
within the ExportFile structure.
Each of the constant_pool table entries, including entry zero, is a variablelength structure whose format is indicated by its first “tag” byte.
There are no ordering constrains on entries in the constant_pool table.
this_package
The value of this_package must be a valid index into the constant_pool
table. The constant_pool entry at that index must be a
CONSTANT_Package_info (§5.6.1) structure representing the package defined
by this ExportFile.
export_class_count
The value of the export_class_count item gives the number of elements in
the classes table.
classes[]
Each value of the classes table is a variable-length class_info structure
(§5.7) giving the description of a publicly accessible class or interface declared
in this package. If the ACC_LIBRARY flag item in the CONSTANT_Package_info
(§5.6.1) structure indicated by the this_package item is set, the classes
table has an entry for each public class and interface declared in this package.
If the ACC_LIBRARY flag item is not set, the classes table has an entry for each
public shareable interface declared in this package.1
1. This restriction of exporting only shareable interfaces in non-library packages is imposed by the firewall
defined in the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
52
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
5.6
Constant Pool
All constant_pool table entries have the following general format:
cp_info {
u1 tag
u1 info[]
}
Each item in the constant_pool must begin with a 1-byte tag indicating the kind of
cp_info entry. The content of the info array varies with the value of tag. The valid
tags and their values are listed in TABLE 5-1. Each tag byte must be followed by two
or more bytes giving information about the specific constant. The format of the
additional information varies with the tag value.
Constant Type
Value
CONSTANT_Package
13
CONSTANT_Classref
7
CONSTANT_Integer
3
CONSTANT_Utf8
1
TABLE 5-1
Export file constant pool tags
Chapter 5
The Export File Format
53
5.6.1
CONSTANT_Package
The CONSTANT_Package_info structure is used to represent a package:
CONSTANT_Package_info {
u1 tag
u1 flags
u2 name_index
u1 minor_version
u1 major_version
u1 aid_length
u1 aid[aid_length]
}
The items of the CONSTANT_Package_info structure are the following:
tag
The tag item has the value of CONSTANT_Package (13).
flags
The flags item is a mask of modifiers that apply to this package. The flags
modifiers are shown in the following table.
Flags
Value
ACC_LIBRARY
0x01
TABLE 5-2
Export file package flags
The ACC_LIBRARY flag has the value of one if this package does not define and
declare any applets. In this case it is called a library package. Otherwise
ACC_LIBRARY has the value of zero.
If the package is not a library package this export file can only contain shareable interfaces.1 A shareable interface is either the
javacard.framework.Shareable interface or an interface that extends the
javacard.framework.Shareable interface.
All other flag values are reserved. Their values must be zero.
1. This restriction is imposed by the firewall defined in the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification.
54
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
name_index
The value of the name_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing a valid Java package
name.
As in Java class files, ASCII periods (‘.’) that normally separate the identifiers
in a package name are replaced by ASCII forward slashes (‘/’). For example,
the package name javacard.framework is represented in a
CONSTANT_Utf8_info structure as javacard/framework.
minor_version, major_version
The minor_version and major_version items are the minor and major version numbers of this package. These values uniquely identify the particular
implementation of this package and indicate the binary compatibility between
packages. See §4.5 for a description of assigning and using package version
numbers.
aid_length
The value of the aid_length item gives the number of bytes in the aid array.
Valid values are between 5 and 16, inclusive.
aid[]
The aid array contains the ISO AID of this package (§4.2).
5.6.2
CONSTANT_Classref
The CONSTANT_Classref_info structure is used to represent a class or interface:
CONSTANT_Classref_info {
u1 tag
u2 name_index
}
The items of the CONSTANT_Classref_info structure are the following:
tag
The tag item has the value of CONSTANT_Classref (7).
name_index
The value of the name_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing a valid fully qualified
Java class or interface name. This name is fully qualified since it may represent
a class or interface defined in a package other than the one described in the
Chapter 5
The Export File Format
55
export file.
As in Java class files, ASCII periods (‘.’) that normally separate the identifiers
in a class or interface name are replaced by ASCII forward slashes (‘/’). For
example, the interface name javacard.framework.Shareable is represented
in a CONSTANT_Utf8_info structure as javacard/framework/Shareable.
5.6.3
CONSTANT_Integer
The CONSTANT_Integer_info structure is used to represent four-byte numeric (int)
constants:
CONSTANT_Integer_info {
u1 tag
u4 bytes
}
The items of the CONSTANT_Integer_info structure are the following:
tag
The tag item has the value of CONSTANT_Integer (3).
bytes
The bytes item of the CONSTANT_Integer_info structure contains the value
of the int constant. The bytes of the value are stored in big-endian (high byte
first) order.
The value of a boolean type is 1 to represent true and 0 to represent false.
5.6.4
CONSTANT_Utf8
The CONSTANT_Utf8_info structure is used to represent constant string values. UTF8 strings are encoded in the same way as described in The JavaÔ Virtual Machine
Specification (§ 4.4.7).
The CONSTANT_Utf8_info structure is:
CONSTANT_Utf8_info {
u1 tag
u2 length
u1 bytes[length]
}
The items of the CONSTANT_Utf8_info structure are the following:
56
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
tag
The tag item has the value of CONSTANT_Utf8 (1).
length
The value of the length item gives the number of bytes in the bytes array (not
the length of the resulting string). The strings in the CONSTANT_Utf8_info
structure are not null-terminated.
bytes[]
The bytes array contains the bytes of the string. No byte may have the value
(byte)0 or (byte)0xF0-(byte)0xFF.
5.7
Classes and Interfaces
Each class and interface is described by a variable-length class_info structure. The
format of this structure is:
class_info {
u1 token
u2 access_flags
u2 name_index
u2 export_supers_count
u2 supers[export_supers_count]
u1 export_interfaces_count
u2 interfaces[export_interfaces_count]
u2 export_fields_count
field_info fields[export_fields_count]
u2 export_methods_count
method_info methods[export_methods_count]
}
The items of the class_info structure are as follows:
token
The value of the token item is the class token (§4.3.7.2) assigned to this class or
interface.
access_flags
The value of the access_flags item is a mask of modifiers used with class
and interface declarations. The access_flags modifiers are shown in the fol-
Chapter 5
The Export File Format
57
lowing table.
Name
Value
Meaning
Used By
ACC_PUBLIC
0x0001
Class,
interface
ACC_FINAL
0x0010
ACC_INTERFACE
ACC_ABSTRACT
0x0200
0x0400
ACC_SHAREABLE
0x0800
ACC_REMOTE
0x1000
Is public; may be
accessed from
outside its package
Is final; no
subclasses allowed.
Is an interface
Is abstract; may not
be instantiated
Is shareable; may be
shared between Java
Card applets.
Is remote; may be
accessed by JCRMI
TABLE 5-3
Class
Interface
Class,
interface
Class,
interface
Class,
interface
Export file class access and modifier flags
The ACC_SHAREABLE flag indicates whether this class or interface is shareable.1
A class is shareable if it implements (directly or indirectly) the
javacard.framework.Shareable interface. An interface is shareable if it is or
extends (directly or indirectly) the javacard.framework.Shareable interface.
The ACC_REMOTE flag indicates whether this class or interface is remote. The
value of this flag must be one if and only if the class or interface satisfies the
requirements defined in §2.2.6.1.
All other class access and modifier flags are defined in the same way and with
the same restrictions as described in The JavaÔ Virtual Machine Specification.
Since all classes and interfaces represented in an export file are public, the
ACC_PUBLIC flag must always be set.
All other flag values are reserved. Their values must be zero.
name_index
The value of the name_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Classref_info (§5.6.2) structure representing a valid, fully qualified Java class or interface name.
1. The ACC_SHAREABLE flag is defined to enable Java Card virtual machines to implement the firewall
restrictions defined by the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
58
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
export_supers_count
The value of the export_supers_count item indicates the number of entries
in the supers array.
supers[]
The super array contains an entry for each public superclass of this class or
interface. It does not include package visible superclasses.
Each value in the supers array must be a valid index into the constant_pool
table. The constant_pool entry at each value must be a
CONSTANT_Classref_info (§5.6.2) structure representing a valid, fully qualified Java class or interface name. Entries in the supers array may occur in any
order.
export_interfaces_count
The value of the export_interfaces_count item indicates the number of
entries in the interfaces array.
interfaces[]
The interfaces array contains an entry for each public interface implemented
by this class or interface. It does not include package visible interfaces. It does
include all public superinterfaces in the hierarchies of public interfaces implemented by this class or interface.
Each value in the interfaces array must be a valid index into the
constant_pool table. The constant_pool entry at each value must be a
CONSTANT_Classref_info (§5.6.2) structure representing a valid, fully qualified Java interface name. Entries in the interfaces array may occur in any
order.
export_fields_count
The value of the export_fields_count item gives the number of entries in
the fields table.
fields[]
Each value in the fields table is a variable-length field_info (§5.8) structure. The field_info contains an entry for each publicly accessible field, both
class variables and instance variables, declared by this class or interface. It does
not include items representing fields that are inherited from superclasses or
superinterfaces.
export_methods_count
The value of the export_methods_count item gives the number of entries in
the methods table.
methods[]
Each value in the methods table is a method_info (§5.9) structure. The
Chapter 5
The Export File Format
59
method_info structure contains an entry for each publicly accessible class
(static or constructor) method defined by this class, and each publicly accessible instance method defined by this class or its superclasses, or defined by this
interface or its super-interfaces.
60
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
5.8
Fields
Each field is described by a variable-length field_info structure. The format of this
structure is:
field_info {
u1 token
u2 access_flags
u2 name_index
u2 descriptor_index
u2 attributes_count
attribute_info attributes[attributes_count]
}
The items of the field_info structure are as follows:
token
The token item is the token assigned to this field. There are three scopes for
field tokens: final static fields of primitive types (compile-time constants),
all other static fields, and instance fields.
If this field is a compile-time constant, the value of the token item is 0xFF.
Compile-time constants are represented in export files, but are not assigned
token values suitable for late binding. Instead Java Card Converters must
replace bytecodes that reference final static fields with bytecodes that load
the constant value of the field.1
If this field is static, but is not a compile-time constant, the token item represents a static field token (§4.3.7.3).
If this field is an instance field, the token item represents an instance field token
(§4.3.7.5).
1. Although Java compilers ordinarily replace references to final static fields of primitive types with primitive
constants, this functionality is not required.
Chapter 5
The Export File Format
61
access_flags
The value of the access_flags item is a mask of modifiers used with fields.
The access_flags modifiers are shown in the following table.
Name
Value
Meaning
Used By
ACC_PUBLIC
0x0001
Any field
ACC_PROTECTED
0x0004
ACC_STATIC
0x0008
Is public; may be
accessed from outside
its package.
Is protected; may be
accessed within
subclasses.
Is static.
ACC_FINAL
0x0010
TABLE 5-4
Is final; no further
overriding or
assignment after
initialization.
Class field
Instance field
Class field
Interface field
Any field
Export file field access and modifier flags
Field access and modifier flags are defined in the same way and with the same
restrictions as described in The JavaÔ Virtual Machine Specification.
Since all fields represented in an export file are either public or protected,
exactly one of the ACC_PUBLIC or ACC_PROTECTED flag must be set.
The Java Card virtual machine reserves all other flag values. Their values must
be zero.
name_index
The value of the name_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing a valid Java field name
stored as a simple (not fully qualified) name, that is, as a Java identifier.
descriptor_index
The value of the descriptor_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing a valid Java field descriptor.
Representation of a field descriptor in an export file is the same as in a Java
class file. See the specification described in The JavaÔ Virtual Machine Specification (§4.3.2).
If this field is a reference-type, the class referenced must be a public class.
62
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
attributes_count
The value of the attributes_count item indicates the number of additional
attributes of this field. The only field_info attribute currently defined is the
ConstantValue attribute (§5.10.1). For static final fields of primitive types,
the value must be 1; that is, when both the ACC_STATIC and ACC_FINAL bits in
the flags item are set an attribute must be present. For all other fields the value
of the attributes_count item must be 0.
attributes[]
The only attribute defined for the attributes table of a field_info structure
by this specification is the ConstantValue attribute (§5.10.1). This must be
defined for static final fields of primitive types (boolean, byte, short, and
int).
5.9
Methods
Each method is described by a variable-length method_info structure. The format of
this structure is:
method_info {
u1 token
u2 access_flags
u2 name_index
u2 descriptor_index
}
The items of the method_info structure are as follows:
token
The token item is the token assigned to this method. If this method is a static
method or constructor, the token item represents a static method token
(§4.3.7.4). If this method is a virtual method, the token item represents a virtual method token (§4.3.7.6). If this method is an interface method, the token
item represents an interface method token (§4.3.7.7).
Chapter 5
The Export File Format
63
access_flags
The value of the access_flags item is a mask of modifiers used with methods. The access_flags modifiers are shown in the following table.
Name
Value
Meaning
Used By
ACC_PUBLIC
0x0001
Any method
ACC_PROTECTED
0x0004
ACC_STATIC
0x0008
Is public; may be
accessed from outside its
package.
Is protected; may be
accessed within
subclasses.
Is static.
ACC_FINAL
0x0010
ACC_ABSTRACT
0x0400
TABLE 5-5
Is final; no further
overriding or assignment
after initialization.
Is abstract; no
implementation is
provided
Class/
instance
method
Class/
instance
method
Class/
instance
method
Any method
Export file method access and modifier flags
Method access and modifier flags are defined in the same way and with the
same restrictions as described in The JavaÔ Virtual Machine Specification.
Since all methods represented in an export file are either public or protected,
exactly one of the ACC_PUBLIC or ACC_PROTECTED flag must be set.
Unlike in Java class files, the ACC_NATIVE flag is not supported in export files.
Whether a method is native is an implementation detail that is not relevant to
importing packages. The Java Card virtual machine reserves all other flag values. Their values must be zero.
name_index
The value of the name_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing either the special internal
method name for constructors, <init>, or a valid Java method name stored as
a simple (not fully qualified) name.
descriptor_index
The value of the descriptor_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing a valid Java method
descriptor.
64
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Representation of a method descriptor in an export file is the same as in a Java
class file. See the specification described in The JavaÔ Virtual Machine Specification (§4.3.3).
All classes referenced in a descriptor must be public classes.
5.10
Attributes
Attributes are used in the field_info (§5.8) structure of the export file format. All
attributes have the following general format:
attribute_info {
u2 attribute_name_index
u4 attribute_length
u1 info[attribute_length]
}
5.10.1
ConstantValue Attribute
The ConstantValue attribute is a fixed-length attribute used in the attributes
table of the field_info structures. A ConstantValue attribute represents the value
of a final static field (compile-time constant); that is, both the ACC_STATIC and
ACC_FINAL bits in the flags item of the field_info structure must be set. There can
be no more than one ConstantValue attribute in the attributes table of a given
field_info structure.
The ConstantValue attribute has the format:
ConstantValue_attribute {
u2 attribute_name_index
u4 attribute_length
u2 constantvalue_index
}
The items of the ConstantValue_attribute structure are as follows:
attribute_name_index
The value of the attribute_name_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must be a
CONSTANT_Utf8_info (§5.6.4) structure representing the string “ConstantValue.”
Chapter 5
The Export File Format
65
attribute_length
The value of the attribute_length item of a ConstantValue_attribute
structure must be 2.
constantvalue_index
The value of the constantvalue_index item must be a valid index into the
constant_pool table. The constant_pool entry at that index must give the
constant value represented by this attribute.
The constant_pool entry must be of a type CONSTANT_Integer (§5.6.3).
66
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
6
The CAP File Format
This chapter describes the Java Card CAP (converted applet) file format. Each CAP file
contains all of the classes and interfaces defined in one Java package. Java Card
Converters must be capable of producing CAP files that conform to the specification
provided in this chapter.
A CAP file consists of a stream of 8-bit bytes. All 16-bit and 32-bit quantities are
constructed by reading in two and four consecutive 8-bit bytes, respectively.
Multibyte data items are always stored in big-endian order, where the high-order
bytes come first. The first bit read of an 8-bit quantity is considered the high bit.
This chapter defines its own set of data types representing Java Card CAP file data:
the types u1, and u2 represent an unsigned one-, and two-byte quantities,
respectively. Some u1 types are represented as bitfield structures, consisting of arrays
of bits. The zeroeth bit in each bit array represents the most significant bit, or high
bit.
The Java Card CAP file format is presented using pseudo structures written in a Clike structure notation. To avoid confusion with the fields of Java Card virtual
machine classes and class instances, the contents of the structures describing the Java
Card CAP file format are referred to as items. Unlike the fields of a C structure,
successive items are stored in the Java Card file sequentially, without padding or
alignment.
Variable-sized tables, consisting of variable-sized items, are used in several CAP file
data structures. Although we will use C-like array syntax to refer to table items, the
fact that tables are streams of variable-sized structures means that it is not possible
to directly translate a table index into a byte offset into the table.
A data structure referred to as an array consists of items equal in size.
Some items in the structures of the CAP file format are describe using a C-like union
notation. The bytes contained in a union structure have one of the two formats.
Selection of the two formats is based on the value of the high bit of the structure.
67
6.1
Component Model
A Java Card CAP file consists of a set of components. Each component describes a set
of elements in the Java package defined, or an aspect of the CAP file. A complete CAP
file must contain all of the required components specified in this chapter. Three
components are optional: the Applet Component (§6.5), Export Component (§6.12),
and Debug Component (§6.14). The Applet Component is included only if one or
more Applets are defined in the package. The Export Component is included only if
classes in other packages may import elements in the package defined. The Debug
Component contains all of the data necessary for debugging a package.
The content of each component defined in a CAP file must conform to the
corresponding format specified in this chapter. All components have the following
general format:
component
u1
u2
u1
}
{
tag
size
info[]
Each component begins with a 1-byte tag indicating the kind of component. Valid
tags and their values are listed in TABLE 6-1. The size item indicates the number of
bytes in the info array of the component, not including the tag and size items.
The content and format of the info array varies with the type of component.
Component Type
COMPONENT_Header
1
COMPONENT_Directory
2
COMPONENT_Applet
3
COMPONENT_Import
4
COMPONENT_ConstantPool
5
COMPONENT_Class
6
COMPONENT_Method
7
COMPONENT_StaticField
8
COMPONENT_ReferenceLocation
9
COMPONENT_Export
10
COMPONENT_Descriptor
11
COMPONENT_Debug
12
TABLE 6-1
68
Value
CAP file component tags
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Sun may define additional components in future versions of this Java Card virtual
machine specification. It is guaranteed that additional components will have tag
values between 13 and 127, inclusive.
6.1.1
Containment in a JAR File
Each CAP file component is represented as a single file. The component file names
are enumerated in TABLE 6-2. These names are not case sensitive.
Component Type
File Name
COMPONENT_Header
Header.cap
COMPONENT_Directory
Directory.cap
COMPONENT_Applet
Applet.cap
COMPONENT_Import
Import.cap
COMPONENT_ConstantPool
ConstantPool.cap
COMPONENT_Class
Class.cap
COMPONENT_Method
Method.cap
COMPONENT_StaticField
StaticField.cap
COMPONENT_ReferenceLocation
RefLocation.cap
COMPONENT_Export
Export.cap
COMPONENT_Descriptor
Descriptor.cap
COMPONENT_Debug
Debug.cap
TABLE 6-2
CAP file component file names
All CAP file components are stored in a JAR file. As described in §4.1.3, the path to
the CAP file component files in a JAR file consists of a directory called javacard that
is in a subdirectory representing the package’s directory. For example, the CAP file
component files of the package javacard.framework are located in the subdirectory
javacard/framework/javacard. Other files, including other CAP files, may also
reside in a JAR file that contains CAP file component files.
The JAR file format provides a vehicle suitable for the distribution of CAP file
components. It is not intended or required that the JAR file format be used as the
load file format for loading CAP file components onto a Java Card enabled device.
See §6.2 for more information.
The name of a JAR file containing CAP file components is not defined as part of this
specification. The naming convention used by the Sun Microsystems, Inc. Java Card
Converter Tool is to append .cap to the simple (i.e. not fully qualified) package
name. For example, the CAP file produced for the package
com.sun.javacard.JavaLoyalty would be named JavaLoyalty.cap.
Chapter 6
The CAP File Format
69
6.1.2
Defining New Components
Java Card CAP files are permitted to contain new, or custom, components. All new
components not defined as part of this specification must not affect the semantics of
the specified components, and Java Card virtual machines must be able to accept
CAP files that do not contain new components. Java Card virtual machine
implementations are required to silently ignore components they do not recognize.
New components are identified in two ways: they are assigned both an ISO 7816-5
AID (§4.2) and a tag value. Valid tag values are between 128 and 255, inclusive. Both
of these identifiers are recorded in the custom_component item of the Directory
Component (§6.4).
The new component must conform to the general component format defined in this
chapter, with a tag value, a size value indicating the number of bytes in the
component (excluding the tag and size items), and an info item containing the
content of the new component.
A new component file is stored in a JAR file, following the same restrictions as those
specified in §4.1.3. That is, the file containing the new component must be located in
the <package_directory>/javacard subdirectory of the JAR file and must have the
extension .cap.
6.2
Installation
Installing a CAP file components onto a Java Card enabled device entails
communication between a Java Card enabled terminal and that device. While it is
beyond the scope of this specification to define a load file format or installation
protocol between a terminal and a device, the CAP file component order shown in
TABLE 6-3 is a reference load order suitable for an implementation with a simple
memory management model on a limited memory device.1
1. Both the Java Card Forum and Global Platform specification have adopted this component load order as a
standard to enhance interoperability. In both cases, loading the Descriptor Component is optional.
Furthermore, the Global Platform specification defines the format of packets (APDUs) used during
installation.
70
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Component Type
COMPONENT_Header
COMPONENT_Directory
COMPONENT_Import
COMPONENT_Applet
COMPONENT_Class
COMPONENT_Method
COMPONENT_StaticField
COMPONENT_Export
COMPONENT_ConstantPool
COMPONENT_ReferenceLocation
COMPONENT_Descriptor
(optional)
TABLE 6-3
Reference component install order
The component type COMPONENT_Debug is not intended for download to the device.
It is intended to be used off-card in conjunction with a suitably instrumented Java
Card virtual machine.
Chapter 6
The CAP File Format
71
6.3
Header Component
The Header Component contains general information about this CAP file and the
package it defines. It is described by the following variable-length structure:
header_component {
u1 tag
u2 size
u4 magic
u1 minor_version
u1 major_version
u1 flags
package_info package
package_name_info package_name
}
The items in the header_component structure are as follows:
tag
The tag item has the value COMPONENT_Header (1).
size
The size item indicates the number of bytes in the header_component structure, excluding the tag and size items. The value of the size item must be
greater than zero.
magic
The magic item supplies the magic number identifying the Java Card CAP file
format; it has the value 0xDECAFFED.
minor_version, major_version
The minor_version and major_version items are the minor and major version numbers of this CAP file. Together, a major and a minor version number
determine the version of the CAP file format. If a CAP file has the major version number of M and minor version number of m, the version of the CAP file’s
format is M.m.
A change in the major version number indicates a major incompatibility
change, one that requires a fundamentally different Java Card virutal machine.
A Java Card virtual machine is not required to support CAP files with different
major version numbers. A Java Card virtual machine is required to support
CAP files having a given major version number and all valid minor version
numbers in the range 0 through some particular minor_version where a valid
minor version number is a minor version number that has been defined in a
version of the Java Card Virtual Machine Specification.
72
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
In this specification, the major version of the CAP file format has the value 2
and the minor version has the value 2. Only Sun Microsystems, Inc. may define
the meaning and values of new CAP file format versions.
flags
The flags item is a mask of modifiers that apply to this package. The flags
modifiers are shown in the following table.
Flags
Value
ACC_INT
0x01
ACC_EXPORT
0x02
ACC_APPLET
0x04
TABLE 6-4
CAP file package flags
The ACC_INT flag has the value of one if the Java int type is used in this package. The int type is used if one or more of the following is present:
■
■
■
■
■
■
■
■
a parameter to a method of type int,
a parameter to a method of type int array,
a local variable of type int,
a local variable of type int array,
a field of type int,
a field of type int array,
an instruction of type int, or
an instruction of type int array.
Otherwise the ACC_INT flag has the value of 0.
The ACC_EXPORT flag has the value of one if an Export Component (§6.12) is
included in this CAP file. Otherwise it has the value of 0.
The ACC_APPLET flag has the value of one if an Applet Component (§6.5) is
included in this CAP file. Otherwise it has the value of 0.
All other bits in the flags item not defined in TABLE 6-4 are reserved for
future use. Their values must be zero.
package
The package item describes the package defined in this CAP file. It is represented as a package_info structure:
package_info {
u1 minor_version
u1 major_version
u1 AID_length
u1 AID[AID_length]
}
Chapter 6
The CAP File Format
73
The items in the package_info structure are as follows:
minor_version, major_version
The minor_version and major_version items are the minor and
major version numbers of this package. These values uniquely identify the particular implementation of this package and indicate the
binary compatibility between packages. See §4.5 for a description of
assigning and using package version numbers.
AID_length
The AID_length item represents the number of bytes in the AID item.
Valid values are between 5 and 16, inclusive.
AID[]
The AID item represents the Java Card name of the package. See ISO
7816-5 for the definition of an AID (§4.2).
package_name
The package_name item describes the name of the package defined in this CAP
file. It is represented as a package_name_info[] structure:
package_name_info {
u1 name_length
u1 name[name_length]
}
The items in the package_name_info[] structure are as follows:
name_length
The name_length item is the number of bytes used in the name item to
represent the name of this package in UTF-8 format. The value of this
item may be zero if and only if the package does not define any remote
interfaces or remote classes.
name[]
The name[] item is a variable length representation of the fully qualified name of this package in UTF-8 format. The fully qualified name is
represented in internal form as described in The JavaÔ Virtual Machine
Specification (§4.2).
74
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
6.4
Directory Component
The Directory Component lists the size of each of the components defined in this CAP
file. When an optional component is not included, such as the Applet Component
(§6.5), Export Component (§6.12), or Debug Component (§6.14), it is represented in
the Directory Component with size equal to zero. The Directory Component also
includes entries for new (or custom) components.
The Directory Component is described by the following variable-length structure:
directory_component {
u1 tag
u2 size
u2 component_sizes[12]
static_field_size_info static_field_size
u1 import_count
u1 applet_count
u1 custom_count
custom_component_info custom_components[custom_count]
}
The items in the directory_component structure are as follows:
tag
The tag item has the value COMPONENT_Directory (2).
size
The size item indicates the number of bytes in the directory_component
structure, excluding the tag and size items. The value of the size item must
be greater than zero.
component_sizes[]
The component_sizes item is an array representing the number of bytes in
each of the components in this CAP file. All of the 12 components defined in
this chapter are represented in the component_sizes array. The value of an
index into the array is equal to the value of the tag of the component represented at that entry, minus 1.
The value in each entry in the component_sizes array is the same as the size
item in the corresponding component. It represents the number of bytes in the
component, excluding the tag and size items.
The value of an entry in the component_sizes array is zero for components
not included in this CAP file. Components that may not be included are the
Applet Component (§6.5), the Export Component (§6.12), and the Debug Component (§6.14). For all other components the value is greater than zero.
Chapter 6
The CAP File Format
75
static_field_size
The static_field_size item is a static_field_size_info structure. The
structure is defined as:
static_field_size_info {
u2 image_size
u2 array_init_count
u2 array_init_size
}
The items in the static_field_size_info structure are the following:
image_size
The image_size item has the same value as the image_size item in
the Static Field Component (§6.10). It represents the total number of
bytes in the static fields defined in this package, excluding final
static fields of primitive types.
array_init_count
The array_init_count item has the same value as the
array_init_count item in the Static Field Component (§6.10). It represents the number of arrays initialized in all of the <clinit> methods in this package.
array_init_size
The array_init_size item represents the sum of the count items in
the array_init table item of the Static Field Component (§6.10). It is
the total number of bytes in all of the arrays initialized in all of the
<clinit> methods in this package.
import_count
The import_count item indicates the number of packages imported by classes
and interfaces in this package. This item has the same value as the count item
in the Import Component (§6.6).
applet_count
The applet_count item indicates the number of applets defined in this package. If an Applet Component (§6.5) is not included in this CAP file, the value of
the applet_count item is zero. Otherwise the value of the applet_count item
is the same as the value of the count item in the Applet Component (§6.5).
custom_count
The custom_count item indicates the number of entries in the
custom_components table. Valid values are between 0 and 127, inclusive.
custom_components[]
The custom_components item is a table of variable-length
custom_component_info structures. Each new component defined in this
76
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CAP file must be represented in the table. These components are not defined in
this standard.
The custom_component_info structure is defined as:
custom_component_info {
u1 component_tag
u2 size
u1 AID_length
u1 AID[AID_length]
}
The items in entries of the custom_component_info structure are:
component_tag
The component_tag item represents the tag of the component. Valid
values are between 128 and 255, inclusive.
size
The size item represents the number of bytes in the component,
excluding the tag and size items.
AID_length
The AID_length item represents the number of bytes in the AID item.
Valid values are between 5 and 16, inclusive.
AID[]
The AID item represents the Java Card name of the component. See
ISO 7816-5 for the definition of an AID (§4.2).
Each component is assigned an AID conforming to the ISO 7816-5
standard. Beyond that, there are no constraints on the value of an AID
of a custom component.
6.5
Applet Component
The Applet Component contains an entry for each of the applets defined in this
package. Applets are defined by implementing a non-abstract subclass, direct or
indirect, of the javacard.framework.Applet class.1 If no applets are defined, this
component must not be present in this CAP file.
The Applet Component is described by the following variable-length structure:
1. Restrictions placed on an applet definition are imposed by the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification.
Chapter 6
The CAP File Format
77
applet_component {
u1 tag
u2 size
u1 count
{ u1 AID_length
u1 AID[AID_length]
u2 install_method_offset
} applets[count]
}
The items in the applet_component structure are as follows:
tag
The tag item has the value COMPONENT_Applet (3).
size
The size item indicates the number of bytes in the applet_component structure, excluding the tag and size items. The value of the size item must be
greater than zero.
count
The count item indicates the number of applets defined in this package. The
value of the count item must be greater than zero.
applets[]
The applets item represents a table of variable-length structures each describing an applet defined in this package.
The items in each entry of the applets table are defined as follows:
AID_length
The AID_length item represents the number of bytes in the AID item.
Valid values are between 5 and 16, inclusive.
AID[]
The AID item represents the Java Card name of the applet.
Each applet is assigned an AID conforming to the ISO 7816-5 standard
(§4.2). The RID (first 5 bytes) of all of the applet AIDs must have the
same value. In addition, the RID of each applet AIDs must have the
same value as the RID of the package defined in this CAP file.
78
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
install_method_offset
The value of the install_method_offset item must be a 16-bit offset into the info item of the Method Component (§6.9). The item at
that offset must be a method_info structure that represents the static
install(byte[],short,byte) method of the applet.1 The
install(byte[],short,byte) method must be defined in a class
that extends the javacard.framework.applet class, directly or indirectly. The install(byte[],short,byte) method is called to initialize the applet.
1. Restrictions placed on the install(byte[],short,byte) method of an applet are imposed by the Java
CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 6
The CAP File Format
79
6.6
Import Component
The Import Component lists the set of packages imported by the classes in this
package. It does not include an entry for the package defined in this CAP file. The
Import Component is represented by the following structure:
import_component {
u1 tag
u2 size
u1 count
package_info packages[count]
}
The items in the import_component structure are as follows:
tag
The tag item has the value COMPONENT_Import (4).
size
The size item indicates the number of bytes in the import_component structure, excluding the tag and size items. The value of the size item must be
greater than zero.
count
The count item indicates the number of items in the packages table. The
value of the count item must be between 0 and 128, inclusive.
packages[]
The packages item represents a table of variable-length package_info structures as defined for package under §6.3. The table contains an entry for each of
the packages referenced in the CAP file, not including the package defined.
The major and minor version numbers specified in the package_info structure are equal to the major and minor versions specified in the imported package’s export file. See §4.5 for a description of assigning and using package
version numbers.
Components of this CAP file refer to an imported package by using a index in
this packages table. The index is called a package token (§4.3.7.1).
80
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
6.7
Constant Pool Component
The Constant Pool Component contains an entry for each of the classes, methods,
and fields referenced by elements in the Method Component (§6.9) of this CAP file.
The referencing elements in the Method Component may be instructions in the
methods or exception handler catch types in the exception handler table.
Entries in the Constant Pool Component reference elements in the Class Component
(§6.8), Method Component (§6.9), and Static Field Component (§6.10). The Import
Component (§6.6) is also accessed using a package token (§4.3.7.1) to describe
references to classes, methods and fields defined in imported packages. Entries in
the Constant Pool Component do not reference other entries internal to itself.
The Constant Pool Component is described by the following structure:
constant_pool_component {
u1 tag
u2 size
u2 count
cp_info constant_pool[count]
}
The items in the constant_pool_component structure are as follows:
tag
The tag item has the value COMPONENT_ConstantPool (5).
size
The size item indicates the number of bytes in the
constant_pool_component structure, excluding the tag and size items. The
value of the size item must be greater than zero.
count
The count item represents the number entries in the constant_pool[] array.
Valid values are between 0 and 65535, inclusive.
constant_pool[]
The constant_pool[] item represents an array of cp_info structures:
cp_info {
u1 tag
u1 info[3]
}
Chapter 6
The CAP File Format
81
Each item in the constant_pool[] array is a 4-byte structure. Each structure must
begin with a 1-byte tag indicating the kind of cp_info entry. The content and
format of the 3-byte info array varies with the value of the tag. The valid tags and
their values are listed in the following table.
Constant Type
Tag
CONSTANT_Classref
1
CONSTANT_InstanceFieldref
2
CONSTANT_VirtualMethodref
3
CONSTANT_SuperMethodref
4
CONSTANT_StaticFieldref
5
CONSTANT_StaticMethodref
6
TABLE 6-5
CAP file constant pool tags
Java Card constant types are more specific than those in Java class files. The
categories indicate not only the type of the item referenced, but also the manner in which it is referenced.
For example, in the Java constant pool there is one constant type for method
references, while in the Java Card constant pool there are three constant types
for method references: one for virtual method invocations using the invokevirtual bytecode, one for super method invocations using the invokespecial bytecode, and one for static method invocations using either the invokestatic or
invokespecial bytecode.1 The additional information provided by a constant
type in Java Card technologies simplifies resolution of references.
There are no ordering constraints on constant pool entries. It is recommended,
however, that CONSTANT_InstanceFieldref (§6.7.2) constants occur early in
the array to permit using getfield_T and putfield_T bytecodes instead of
getfield_T_w and putfield_T_w bytecodes. The former have 1-byte constant pool
index parameters while the latter have 2-byte constant pool index parameters.
The first entry in the constant pool can not be an exception handler class that is
referenced by a catch_type_index of an exception_handler_info structure. In such a case the value of the catch_type_index would be equal to 0,
but the value of 0 in a catch_type_index is reserved to indicate an
exception_handler_info structure that describes a finally block.
1. The constant pool index parameter of an invokespecial bytecode is to a CONSTANT_StaticMethodref when the
method referenced is a constructor or a private instance method. In these cases the method invoked is fully
known when the CAP file is created. In the cases of virtual method and super method references, the method
invoked is dependent upon an instance of a class and its hierarchy, both of which may be partially unknown
when the CAP file is created.
82
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
6.7.1
CONSTANT_Classref
The CONSTANT_Classref_info structure is used to represent a reference to a class or
an interface. The class or interface may be defined in this package or in an imported
package.
CONSTANT_Classref_info {
u1 tag
union {
u2 internal_class_ref
{ u1 package_token
u1 class_token
} external_class_ref
} class_ref
u1 padding
}
The items in the CONSTANT_Classref_info structure are the following:
tag
The tag item has the value CONSTANT_Classref (1).
class_ref
The class_ref item represents a reference to a class or interface. If the class or
interface is defined in this package the structure represents an
internal_class_ref and the high bit of the structure is zero. If the class or
interface is defined in another package the structure represents an
external_class_ref and the high bit of the structure is one.
internal_class_ref
The internal_class_ref structure represents a 16-bit offset into the
info item of the Class Component (§6.8) to an interface_info or
class_info structure. The interface_info or class_info structure
must represent the referenced class or interface.
The value of the internal_class_ref item must be between 0 and
32767, inclusive, making the high bit equal to zero.
external_class_ref
The external_class_ref structure represents a reference to a class
or interface defined in an imported package. The high bit of this structure is one.
package_token
The package_token item represents a package token
(§4.3.7.1) defined in the Import Component (§6.6) of this CAP
file. The value of this token must be a valid index into the
Chapter 6
The CAP File Format
83
packages table item of the import_component structure. The
package represented at that index must be the imported package.
The value of the package token must be between 0 and 127,
inclusive.
The high bit of the package_token item is equal to one.
class_token
The class_token item represents the token of the class or
interface (§4.3.7.2) of the referenced class or interface. It has
the value of the class token of the class as defined in the
Export file of the imported package.
padding
The padding item has the value zero. It is present to make the size of a
CONSTANT_Classref_info structure the same as all other constants in the
constant_pool[] array.
6.7.2
CONSTANT_InstanceFieldref,
CONSTANT_VirtualMethodref, and
CONSTANT_SuperMethodref
References to instance fields, and virtual methods are represented by similar
structures:
CONSTANT_InstanceFieldref_info {
u1 tag
class_ref class
u1 token
}
CONSTANT_VirtualMethodref_info {
u1 tag
class_ref class
u1 token
}
CONSTANT_SuperMethodref_info {
u1 tag
class_ref class
u1 token
}
84
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
The items in these structures are as follows:
tag
The tag item of a CONSTANT_InstanceFieldref_info structure has the value
CONSTANT_InstanceFieldref (2).
The tag item of a CONSTANT_VirtualMethodref_info structure has the value
CONSTANT_VirtualMethodref (3).
The tag item of a CONSTANT_SuperMethodref_info structure has the value
CONSTANT_SuperMethodref (4).
class
The class item represents the class associated with the referenced instance
field, virtual method, or super method invocation. It is a class_ref structure
(§6.7.1). If the referenced class is defined in this package the high bit is equal to
zero. If the reference class is defined in an imported package the high bit of this
structure is equal to one.
The class referenced in the CONSTANT_InstanceField_info structure must be
the class that contains the declaration of the instance field.
The class referenced in the CONSTANT_VirtualMethodref_info structure
must be a class that contains a declaration or definition of the virtual method.
The class referenced in the CONSTANT_SuperMethodref_info structure must
always be internal to the class that defines the method that contains the Java
language-level super invocation. The class must be defined in this package.
token
The token item in the CONSTANT_InstanceFieldref_info structure represents an instance field token (§4.3.7.5) of the referenced field. The value of the
instance field token is defined within the scope of the class indicated by the
class item.
The token item of the CONSTANT_VirtualMethodref_info structure represents the virtual method token (§4.3.7.6) of the referenced method. The virtual
method token is defined within the scope of the hierarchy of the class indicated
by the class item. If the referenced method is public or protected the high
bit of the token item is zero. If the referenced method is package-visible the
high bit of the token item is one. In this case the class item must represent a
reference to a class defined in this package.
The token item of the CONSTANT_SuperMethodref_info structure represents
the virtual method token (§4.3.7.6) of the referenced method. Unlike in the
CONSTANT_VirtualMethodref_info structure, the virtual method token is
defined within the scope of the hierarchy of the superclass of the class indicated by the class item. If the referenced method is public or protected the
Chapter 6
The CAP File Format
85
high bit of the token item is zero. If the referenced method is package-visible
the high bit of the token item is one. In the latter case the class item must represent a reference to a class defined in this package and at least one superclass
of the class that contains a definition of the virtual method must also be
defined in this package.
6.7.3
CONSTANT_StaticFieldref and
CONSTANT_StaticMethodref
References to static fields and methods are represented by similar structures:
CONSTANT_StaticFieldref_info {
u1 tag
union {
{ u1 padding
u2 offset
} internal_ref
{ u1 package_token
u1 class_token
u1 token
} external_ref
} static_field_ref
}
CONSTANT_StaticMethodref_info {
u1 tag
union {
{ u1 padding
u2 offset
} internal_ref
{ u1 package_token
u1 class_token
u1 token
} external_ref
} static_method_ref
}
The items in these structures are as follows:
tag
The tag item of a CONSTANT_StaticFieldref_info structure has the value
CONSTANT_StaticFieldref (5).
The tag item of a CONSTANT_StaticMethodref_info structure has the value
CONSTANT_StaticMethodref (6).
86
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
static_field_ref and static_method_ref
The static_field_ref and static_method_ref item represents a reference
to a static field or static method, respectively. Static method references
include references to static methods, constructors, and private virtual
methods.
If the referenced item is defined in this package the structure represents an
internal_ref and the high bit of the structure is zero. If the referenced item is
defined in another package the structure represents an external_ref and the
high bit of the structure is one.
internal_ref
The internal_ref item represents a reference to a static field or
method defined in this package. The items in the structure are:
padding
The padding item is equal to 0.
offset
The offset item of a CONSTANT_StaticFieldref_info
structure represents a 16-bit offset into the Static Field Image
defined by the Static Field component (§6.10) to this static
field.
The offset item of a CONSTANT_StaticMethodref_info
structure represents a 16-bit offset into the info item of the
Method Component (§6.9) to a method_info structure. The
method_info structure must represent the referenced
method.
external_ref
The external_ref item represents a reference to a static field or
method defined in an imported package. The items in the structure
are:
package_token
The package_token item represents a package token
(§4.3.7.1) defined in the Import Component (§6.6) of this CAP
file. The value of this token must be a valid index into the
packages table item of the import_component structure. The
package represented at that index must be the imported package.
The value of the package token must be between 0 and 127,
inclusive.
The high bit of the package_token item is equal to one.
Chapter 6
The CAP File Format
87
class_token
The class_token item represents the token (§4.3.7.2) of the
class of the referenced class. It has the value of the class token
of the class as defined in the Export file of the imported package.
The class indicated by the class_token item must define the
referenced field or method.
token
The token item of a CONSTANT_StaticFieldref_info structure represents a static field token (§4.3.7.3) as defined in the
Export file of the imported package. It has the value of the
token of the referenced field.
The token item of a CONSTANT_StaticMethodref_info
structure represents a static method token (§4.3.7.4) as
defined in the Export file of the imported package. It has the
value of the token of the referenced method.
6.8
Class Component
The Class Component describes each of the classes and interfaces defined in this
package. It does not contain complete access information and content details for each
class and interface. Instead, the information included is limited to that required to
execute operations associated with a particular class or interface, without
performing verification. Complete details regarding the classes and interfaces
defined in this package are included in the Descriptor Component (§6.13).
The information included in the Class Component for each interface is sufficient to
uniquely identify the interface and to test whether or not a cast to that interface is
valid.
The information included in the Class Component for each class is sufficient to
resolve operations associated with instances of a class. The operations include
creating an instance, testing whether or not a cast of the instance is valid,
dispatching virtual method invocations, and dispatching interface method
invocations. Also included is sufficient information to locate instance fields of type
reference, including arrays.
The classes represented in the Class Component reference other entries in the Class
Component in the form of superclass, superinterface and implemented interface
references. When a superclass, superinterface or implemented interface is defined in
an imported package the Import Component is used in the representation of the
reference.
88
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
The classes represented in the Class Component also contain references to virtual
methods defined in the Method Component (§6.9) of this CAP file. References to
virtual methods defined in imported packages are not explicitly described. Instead
such methods are located through a superclass within the hierarchy of the class,
where the superclass is defined in the same imported package as the virtual method.
The Constant Pool Component (§6.7), Export Component (§6.12), Descriptor
Component (§6.13) and Debug Component (§6.14) reference classes and interfaces
defined in the Class Component. No other CAP file components reference the Class
Component.
The Class Component is represented by the following structure:
class_component {
u1 tag
u2 size
u2 signature_pool_length
type_descriptor signature_pool[]
interface_info interfaces[]
class_info classes[]
}
The items in the class_component structure are as follows:
tag
The tag item has the value COMPONENT_Class (6).
size
The size item indicates the number of bytes in the class_component structure, excluding the tag and size items. The value of the size item must be
greater than zero.
signature_pool_length
The signature_pool_length item indicates the number of bytes in the
signature_pool[] item. The value of the signature_pool_length item
must be zero if the package does not define any remote interfaces or remote
classes.
signature_pool[]
The signature_pool[] item represents a list of variable-length
type_descriptor structures. These descriptors represent the signatures of the
remote methods.
interfaces[]
The interfaces item represents an array of interface_info structures. Each
interface defined in this package is represented in the array. The entries are
ordered based on hierarchy such that a superinterface has a lower index than
any of its subinterfaces.
Chapter 6
The CAP File Format
89
classes[]
The classes item represents a table of variable-length class_info structures.
Each class defined in this package is represented in the array. The entries are
ordered based on hierarchy such that a superclass has a lower index than any
of its subclasses.
6.8.1
type_descriptor
The type_descriptor structure represents the type of a field or the signature of a
method.
type_descriptor {
u1 nibble_count;
u1 type[(nibble_count+1) / 2];
}
The type_descriptor structure contains the following elements:
nibble_count
The nibble_count value represents the number of nibbles required to
describe the type encoded in the type array.
type[]
The type array contains an encoded description of the type, composed of individual nibbles. If the nibble_count item is an odd number, the last nibble in
the type array must be 0x0. The values of the type descriptor nibbles are
defined in the following table.
Type
Value
void
0x1
boolean
0x2
byte
0x3
short
0x4
int
0x5
reference
0x6
array of boolean
0xA
array of byte
0xB
array of short
0xC
array of int
0xD
array of reference
0xE
TABLE 6-6
Type descriptor values
Class reference types are described using the reference nibble 0x6, fol-
90
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
lowed by a 2-byte (4-nibble) class_ref structure. The class_ref structure is
defined as part of the CONSTANT_Classref_info structure (§6.7.1). For example, a field of type reference to p1.c1 in a CAP file defining package p0 is
described as:
Nibble
Value
Description
0
0x6
reference
1
<p1>
package token
(high bit on)
<c1>
class token
0x0
padding
2
3
4
5
TABLE 6-7
Encoded reference type p1.c1
The following are examples of the array types:
Nibble
Value
Description
0
0xB
array of byte
1
0x0
padding
TABLE 6-8
Encoded byte array type
Nibble
Value
Description
0
0xE
array of reference
1
<p1>
package token
(high bit on)
<c1>
class token
0x0
padding
2
3
4
5
TABLE 6-9
Encoded reference array type p1.c1
Method signatures are encoded in the same way, with the return type of the
method encoded at the end of the sequence of nibbles. The return type is
encoded in as many nibbles as required to represent it. For example:
Nibble
Value
Description
0
0x1
void
1
0x0
padding
TABLE 6-10
Encoded method signature ()V
Chapter 6
The CAP File Format
91
Nibble
Value
Description
0
0x6
reference
1
<p1>
package token
(high bit on)
<c1>
class token
0x4
short
2
3
4
5
TABLE 6-11
6.8.2
Encoded method signature (Lp1.ci;)S
interface_info and class_info
The interface_info and class_info structures represent interfaces and classes,
respectively. The two are differentiated by the value of the high bit in the structures.
They are defined as follows:
interface_info {
u1 bitfield {
bit[4] flags
bit[4] interface_count
}
class_ref superinterfaces[interface_count]
interface_name_info interface_name1
}
class_info {
u1 bitfield {
bit[4] flags
bit[4] interface_count
}
class_ref super_class_ref
u1 declared_instance_size
u1 first_reference_token
u1 reference_count
u1 public_method_table_base
u1 public_method_table_count
u1 package_method_table_base
u1 package_method_table_count
u2 public_virtual_method_table[public_method_table_count]
u2 package_virtual_method_table[package_method_table_count]
1. The interface_name[] item is required if the value of ACC_REMOTE is one. This item
must be omitted otherwise. See the description of this field for more information.
92
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
implemented_interface_info interfaces[interface_count]
remote_interface_info remote_interfaces 1
}
6.8.2.1
interface_info and class_info shared Items
flags
The flags item is a mask of modifiers used to describe this interface or class.
Valid values are shown in the following table:
Name
Value
ACC_INTERFACE
0x8
ACC_SHAREABLE
0x4
ACC_REMOTE
0x2
TABLE 6-12
CAP file interface and class flags
The ACC_INTERFACE flag indicates whether this interface_info or
class_info structure represents an interface or a class. The value must be one
if it represents an interface_info structure and zero if a class_info structure.
The ACC_SHAREABLE flag in an interface_info structure indicates whether
this interface is shareable. The value of this flag must be one if and only if the
interface is javacard.framework.Shareable interface or extends that interface directly or indirectly.
The ACC_SHAREABLE flag in a class_info structure indicates whether this
class is shareable.2 The value of this flag must be one if and only if this class or
any of its superclasses implements an interface that is shareable.
The ACC_REMOTE flag indicates whether this class or interface is remote. The
value of this flag must be one if and only if the class or interface satisfies the
requirements defined in §2.2.6.1.
All other flag values are reserved. Their values must be zero.
1. The remote_interfaces item is required if the value of ACC_REMOTE is one. This item
must be omitted otherwise. See the description of this field for more information.
2. A Java Card virtual machine uses the ACC_SHAREABLE flag to implement the firewall restrictions defined by
the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 6
The CAP File Format
93
interface_count
The interface_count item of the interface_info structure indicates the
number of entries in the superinterfaces[] table item. The value represents
the number of direct and indirect superinterfaces of this interface. Indirect
superinterfaces are the set of superinterfaces of the direct superinterfaces. Valid
values are between 0 and 14, inclusive.
The interface_count item of the class_info structure indicates the number
of entries in the interfaces table item. The value represents the number of
interfaces implemented by this class, including superinterfaces of those interfaces and potentially interfaces implemented by superclasses of this class.
Valid values are between 0 and 15, inclusive.
6.8.2.2
interface_info Items
superinterfaces[]
The superinterfaces[] item of the interface_info structure is an array of
class_ref structures representing the superinterfaces of this interface. The
class_ref structure is defined as part of the CONSTANT_Classref_info structure (§6.7.1). This array is empty if this interface has no superinterfaces. Both
direct and indirect superinterfaces are represented in the array. Class Object is
not included.
interface_name[]
The interface_name[] item represents interface name information required
if the interface is remote. The interface_name[] item is defined by a
interface_name_info structure. If the value of the ACC_REMOTE flag is zero,
the structure is defined as:
interface_name_info {
}
If the value of the ACC_REMOTE flag is one, the structure is defined as:
interface_name_info {
u1 interface_name_length
u1 interface_name[interface_name_length]
}
The values in the interface_name_info structure are defined as follows:
interface_name_length
The interface_name_length item is the number of bytes in
interface_name[] item.
interface_name
The interface_name[] item is a variable length representation of the
94
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
name of this interface in UTF-8 format.
6.8.2.3
class_info Items
super_class_ref
The super_class_ref item of the class_info structure is a class_ref structure representing the superclass of this class. The class_ref structure is
defined as part of the CONSTANT_Classref_info structure (§6.7.1).
The super_class_ref item has the value of 0xFFFF only if this class does not
have a superclass. Otherwise the value of the super_class_ref item is limited
only by the constraints of the class_ref structure.
declared_instance_size
The declared_instance_size item of the class_info structure represents
the number of 16-bit cells required to represent the instance fields declared by
this class. It does not include instance fields declared by superclasses of this
class.
Instance fields of type int are represented in two 16-bit cells, while all other
field types are represented in one 16-bit cell.
first_reference_token
The first_reference_token item of the class_info structure represents the
instance field token (§4.3.7.5) value of the first reference type instance field
defined by this class. It does not include instance fields defined by superclasses
of this class.
If this class does not define any reference type instance fields, the value of
the first_reference_token is 0xFF. Otherwise the value of the
first_reference_token item must be within the range of the set of instance
field tokens of this class.
reference_count
The reference_count item of the class_info structure represents the number of reference type instance field defined by this class. It does not include
reference type instance fields defined by superclasses of this class.
Valid values of the reference_count item are between 0 and the maximum
number of instance fields defined by this class.
public_method_table_base
The public_method_table_base item of the class_info structure is equal
to the virtual method token value (§4.3.7.6) of the first method in the
public_virtual_method_table[] array. If the
public_virtual_method_table[] array is empty, the value of the
Chapter 6
The CAP File Format
95
public_method_table_base item is equal to the
public_method_table_base item of the class_info structure of this class’
superclass plus the public_method_table_count item of the class_info
structure of this class’ superclass. If this class has no superclass and the
public_virtual_method_table[] array is empty, the value of the
public_method_table_base item is zero.
public_method_table_count
The public_method_table_count item of the class_info structure indicates the number of entries in the public_virtual_method_table[] array.
If this class does not define any public or protected override methods, the
minimum valid value of public_method_table_count item is the number of
public and protected virtual methods declared by this class. If this class
defines one or more public or protected override methods, the minimum
valid value of public_method_table_count item is the value of the largest
public or protected virtual method token, minus the value of the smallest
public or protected virtual override method token, plus one.
The maximum valid value of the public_method_table_count item is the
value of the largest public or protected virtual method token, plus one.
Any value for the public_method_table_count item between the minimum
and maximum specified here is valid. However, the value must correspond to
the number of entries in the public_virtual_method_table[] array.
package_method_table_base
The package_method_table_base item of the class_info structure is equal
to the virtual method token value (§4.3.7.6) of the first entry in the
package_virtual_method_table[] array. If the
package_virtual_method_table[] array is empty, the value of the
package_method_table_base item is equal to the
package_method_table_base item of the class_info structure of this class’
superclass plus the package_method_table_count item of the class_info
structure of this class’ superclass. If this class has no superclass or inherits from
a class defined in another package and the
package_virtual_method_table[] array is empty, the value of the
package_method_table_base item is zero.
package_method_table_count
The package_method_table_count item of the class_info structure indicates the number of entries in the package_virtual_method_table[] array.
If this class does not define any override methods, the minimum valid value of
package_method_table_count item is the number of package visible virtual
methods declared by this class. If this class defines one or more package visible
override methods, the minimum valid value of
96
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
package_method_table_count item is the value of the largest package visible
virtual method token, minus the value of the smallest package visible virtual
override method token, plus one.
The maximum valid value of the package_method_table_count item is the
value of the largest package visible method token, plus one.
Any value for the package_method_table_count item between the minimum
and maximum specified here are valid. However, the value must correspond to
the number of entries in the package_virtual_method_table[].
public_virtual_method_table[]
The public_virtual_method_table[] item of the class_info structure
represents an array of public and protected virtual methods. These methods
can be invoked on an instance of this class. The
public_virtual_method_table[] array includes methods declared or
defined by this class. It may also include methods declared or defined by any
or all of its superclasses. The value of an index into this table must be equal to
the value of the virtual method token of the indicated method, minus the value
of the public_method_table_base item.
Entries in the public_virtual_method_table[] array that represent methods defined or declared in this package contain offsets into the info item of the
Method Component (§6.9) to the method_info structure representing the
method. Entries that represent methods defined or declared in an imported
package contain the value 0xFFFF.
Entries for methods that are declared abstract, not including those defined by
interfaces, are represented in the public_virtual_method_table[] array in
the same way as non-abstract methods.
package_virtual_method_table[]
The package_virtual_method_table[] item of the class_info structure
represents an array of package-visible virtual methods. These methods can be
invoked on an instance of this class. The package_virtual_method_table[]
array includes methods declared or defined by this class. It may also include
methods declared or defined by any or all of its superclasses that are defined in
this package. The value of an index into this table must be equal to the value of
the virtual method token of the indicated method & 0x7F, minus the value of
the package_method_table_base item.
All entries in the package_virtual_method_table[] array represent methods defined or declared in this package. They contain offsets into the info item
of the Method Component (§6.9) to the method_info structure representing
the method.
Entries for methods that are declared abstract, not including those defined by
interfaces, are represented in the package_virtual_method_table[] array in
Chapter 6
The CAP File Format
97
the same way as non-abstract methods.
interfaces[]
The interfaces item of the class_info structure represents a table of variable-length implemented_interface_info structures. The table must contain
an entry for each of the implemented interfaces indicated in the declaration of
this class and each of the interfaces in the hierarchies of those interfaces. Interfaces that occur more than once are represented by a single entry. Interfaces
implemented by superclasses of this class may optionally be represented.
Given the declarations below, the number of entries for class c0 is 1 and the
entry in the interfaces array is i0. The minimum number of entries for class
c1 is 3 and the entries in the interfaces array are i1, i2, and i3. The entries for
class c1 may also include interface i0, which is implemented by the superclass
of c1.
interface i0 {}
interface i1 {}
interface i2 extends i1 {}
interface i3 {}
class c0 implements i0 {}
class c1 extends c0 implements i2, i3 {}
remote_interfaces
The remote_interfaces item represents information required if this class or
any of its super classes implements a remote interface. This item must be omitted if the ACC_REMOTE flag has a value of zero. The remote_interfaces item
is defined by a remote_interface_info structure.
6.8.2.4
implemented_interface_info
The implemented_interface_info structure is defined as follows:
implemented_interface_info {
class_ref interface
u1 count
u1 index[count]
}
The items in the implemented_interface_info structure are defined as follows:
interface
The interface item has the form of a class_ref structure. The class_ref
structure is defined as part of the CONSTANT_Classref_info structure (§6.7.1).
The interface_info structure referenced by the interface item represents
an interface implemented by this class.
count
The count item indicates the number of entries in the index[] array.
98
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
index[]
The index[] item is an array that maps declarations of interface methods to
implementations of those methods in this class. It is a representation of the set
of methods declared by the interface and its superinterfaces.
Entries in the index array must be ordered such that the interface method
token value (§4.3.7.7) of the interface method is equal to the index into the
array. The interface method token value is assigned to the method within the
scope of the interface definition, not within the scope of this class.
The values in the index[] array represent the virtual method tokens (§4.3.7.6)
of the implementations of the interface methods. The virtual method token values are defined within the scope of the hierarchy of this class.
6.8.2.5
remote_interface_info
If the value of the ACC_REMOTE flag is zero, this structure is defined as:
remote_interface_info {
}
If the value of the ACC_REMOTE flag is one, this structure is defined as:
remote_interface_info {
u1 remote_methods_count
remote_method_info remote_methods[remote_methods_count]
u1 hash_modifier_length
u1 hash_modifier[hash_modifier_length]
u1 class_name_length
u1 class_name[class_name_length]
u1 remote_interfaces_count
class_ref remote_interfaces[remote_interfaces_count]
}
The remote_interface_info structure is defined as:
remote_methods_count
The remote_methods_count item indicates the number of entries in the
remote_methods array.
remote_methods[]
The remote_methods item of the class_info structure is an array of
remote_method_info structures that maps each remote method available in
the class to its hash code and its type definition in the signature_pool[]. The
methods are listed in numerically ascending order of hash values.
The remote_method_info structure is defined as follows:
remote_method_info {
Chapter 6
The CAP File Format
99
u2 remote_method_hash
u2 signature_offset
u1 virtual_method_token
}
The items in the remote_method_info structure are defined as follows:
remote_method_hash
The remote_method_hash item contains a two-byte hash value for the
method. The hash value is computed from the simple (not fully qualified) name of the method concatenated with its method descriptor.
The representation of the method descriptor is the same as in a Java
class file. See the specification described in JavaÔ Virtual Machine Specification (§4.3.3).
The hash value uniquely identifies the method within the class.
The hash code is defined as the first two bytes of the SHA-1 message
digest function performed on the hash_modifier[] item described
below followed by the name of the method followed by the method
descriptor representation in UTF-8 format. Rare hash collisions are
averted automatically during package conversion by adjusting the
anti-collision string.
signature_offset
The signature_offset item contains an offset into the info item of
the Class Component to the variable-length type descriptor structure
inside the signature_pool[] item. This structure represents the signature of the remote method.
virtual_method_token
The virtual_method_token item is the virtual method token of the
remote method in this class.
hash_modifier_length
The hash_modifier_length item is the number of bytes in the following
hash_modifier item. The value of this item must be zero if an anti-collision
string is not required.
hash_modifier[]
The hash_modifier[] item is a variable length representation of the anti-collision string in UTF-8 format.
class_name_length
The class_name_length item is the number of bytes used in the
class_name[] item.
100
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
class_name[]
The class_name[] item is a variable length representation of the name of this
class in UTF-8 format.
remote_interfaces_count
The remote_interfaces_count item is the number of interfaces listed in the
following remote_interfaces[] item.
remote_interfaces[]
The remote_interfaces[] item is a variable length array of class_ref
items. It represents the remote interfaces implemented by this class. The
remote interfaces listed in this array, together with their superinterfaces must
be the complete set of remote interfaces implemented by this class and all its
superclasses.
Each entry has the form of a class_ref structure. Each class_ref structure
must reference an interface_info structure representing a remote interface
implemented by this class.
The entries in the remote_interfaces[] array must be ordered such that all
remote interfaces from the same package are listed consecutively.
6.9
Method Component
The Method Component describes each of the methods declared in this package,
excluding <clinit> methods and interface method declarations. Abstract methods
defined by classes (not interfaces) are included. The exception handlers associated
with each method are also described.
The Method Component does not contain complete access information and
descriptive details for each method. Instead, the information is optimized for size
and therefore limited to that required to execute each method without performing
verification. Complete details regarding the methods defined in this package are
included in the Descriptor Component (§6.13). Among other information, the
Descriptor Component contains the location and number of bytecodes for each
method in the Method Component. This information can be used to parse the
methods in the Method Component.
Instructions and exception handler catch types in the Method Component reference
entries in the Constant Pool Component (§6.7). No other CAP file components,
including the Method Component, are referenced by the elements in the Method
Component.
Chapter 6
The CAP File Format
101
The Applet Component (§6.5), Constant Pool Component (§6.7), Class Component
(§6.8), Export Component (§6.12), Descriptor Component (§6.13), and Debug
Component (§6.14) reference methods defined in the Method Component. The
Reference Location Component (§6.11) references all constant pool indices contained
in the Method Component. No other CAP file components reference the Method
Component.
The Method Component is represented by the following structure:
method_component {
u1 tag
u2 size
u1 handler_count
exception_handler_info exception_handlers[handler_count]
method_info methods[]
}
The items in the method_component structure are as follows:
tag
The tag item has the value COMPONENT_Method (7).
size
The size item indicates the number of bytes in the method_component structure, excluding the tag and size items. The value of the size item must be
greater than zero.
handler_count
The handler_count item represents the number of entries in the
exception_handlers array. Valid values are between 0 and 255, inclusive.
exception_handlers[]
The exception_handlers item represents an array of 8-byte
exception_handler_info structures. Each exception_handler_info structure represents a catch or finally block defined in a method of this package.
Entries in the exception_handlers array are sorted in ascending order by the
the offset to the handler of the exception handler. Smaller offset values occur
first in the array. This ordering constraint ensures that the first match found
when searching for an exception handler is the correct match.
There are two consequences of this ordering constraint. First, a handler that is
nested with the active range (try block) of another handler occurs first in the
array. Second, when multiple handlers are associated with the same active
range, they are ordered as they occur in a method. This is consistent with the
ordering constraints defined for Java class files. An example is shown below.
try {
...
try {
102
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
...
} catch (NullPointerException e) {
...
}
...
} catch (Exception e) {
...
} finally {
...
}
...
try {
...
} catch (SecurityException e) {
...
}
CODE EXAMPLE 6-1
// first
// second
// third
// fourth
Exception handler example
methods[]
The methods item represents a table of variable-length method_info structures. Each entry represents a method declared in a class of this package.
<clinit> methods and interface method declaration are not included; all
other methods, including non-interface abstract methods, are.
6.9.1
exception_handler_info
The exception_handler_info structure is defined as follows:
exception_handler_info {
u2 start_offset
u2 bitfield {
bit[1] stop_bit
bit[15] active_length
}
u2 handler_offset
u2 catch_type_index
}
The items in the exception_handler_info structure are as follows:
start_offset, active_length
The start_offset and active_length pair indicate the active range (try
block) an exception handler. The start_offset item indicates the beginning
of the active range while the active_length item indicates the number of
bytes contained in the active range.
end_offset is defined as start_offset plus active_length.
The start_offset item and end_offset are byte offsets into the info item
of the Method Component. The value of the start_offset must be a valid offset into a bytecodes array of a method_info structure to an opcode of an
Chapter 6
The CAP File Format
103
instruction. The value of the end_offset either must be a valid offset into a
bytecodes array of the same method_info structure to an opcode of an
instruction, or must be equal to the method’s bytecode count, the length of the
bytecodes array of the method_info structure. The value of the
start_offset must be less than the value of the end_offset.
The start_offset is inclusive and the end_offset is exclusive; that is, the
exception handler must be active while the execution address is within the
interval [start_offset, end_offset).
stop_bit
The stop_bit item indicates whether the active range (try block) of this
exception handler is contained within or is equal to the active range of any succeeding exception_handler_info structures in this exception_handlers
array. At the Java source level, this indicates whether an active range is nested
within another, or has at least one succeeding exception handler associated
with the same range. The latter occurs when there is at least one succeeding
catch block or a finally block.
The stop_bit item is equal to 1 if the active range does not intersect with a
succeeding exception handler’s active range, and this exception handler is the
last handler applicable to the active range. It is equal to 0 if the active range is
contained within the active range of another exception handler, or there is at
least one succeeding handler applicable to the same active range.
The stop_bit provides an optimization to be used during the interpretation of
the athrow bytecode. As the interpreter searches for an appropriate exception
handler, it may terminate the search of the exception handlers in this Method
Component under the following conditions:
1. the location of the current program counter is less than the end_offset of
this exception handler, and
2. the stop_bit of this exception handler is equal to 1.
When these conditions are satisfied it is guaranteed that none of the succeeding exception handlers in this Method Component will contain an active range
appropriate for the current exception.
In CODE EXAMPLE 6-1 on page 103, the stop_bit item is set for both the
third and fourth handlers.
handler_offset
The handler_offset item represents a byte offset into the info item of the
Method Component. It indicates the start of the exception handler. At the Java
source level, this is equivalent to the beginning of a catch or finally block.
The value of the item must be a valid offset into a bytecodes array of a
method_info structure to an opcode of an instruction, and must be less than
104
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
the value of the method’s bytecode count.
catch_type_index
If the value of the catch_type_index item is non-zero, it must be a valid index
into the constant_pool[] array of the Constant Pool Component (§6.7). The
constant_pool[] entry at that index must be a CONSTANT_Classref_info
structure, representing the class of the exception caught by this
exception_handlers array entry.
If the exception_handlers table entry represents a finally block, the value of
the catch_type_index item is zero. In this case the exception handler is called
for all exceptions that are thrown within the start_offset and end_offset
range.
The order of constants in the constant pool is constrained such that all entries
referenced by catch_type_index items that represent catch block (not
finally blocks) are located at non-zero entries.
6.9.2
method_info
The method_info structure is defined as follows:
method_info {
method_header_info method_header
u1 bytecodes[]
}
The items in the method_info structure are as follows:
method_header
The method_header item represents either a method_header_info or an
extended_method_header_info structure:
method_header_info {
u1 bitfield {
bit[4] flags
bit[4] max_stack
}
u1 bitfield {
bit[4] nargs
bit[4] max_locals
}
}
extended_method_header_info {
u1 bitfield {
Chapter 6
The CAP File Format
105
bit[4] flags
bit[4] padding
}
u1 max_stack
u1 nargs
u1 max_locals
}
The items of the method_header_info and extended_method_header_info structures
are as follows:
flags
The flags item is a mask of modifiers defined for this method. Valid flag values
are shown in the following table.
Flags
Values
ACC_EXTENDED
0x8
ACC_ABSTRACT
0x4
TABLE 6-13
CAP file method flags
The value of the ACC_EXTENDED flag must be one if the method_header is represented by an extended_method_header_info structure. Otherwise the
value must be zero.
The value of the ACC_ABSTRACT flag must be one if this method is defined as
abstract. In this case the bytecodes array must be empty. If this method is not
abstract the value of the ACC_ABSTRACT flag must be zero.
All other flag values are reserved. Their values must be zero.
padding
The padding item has the value of zero. This item is only defined for the
extended_method_header_info structure.
max_stack
The max_stack item indicates the maximum number of 16-bit cells required on
the operand stack during execution of this method.
Stack entries of type int are represented in two 16-bit cells, while all others are
represented in one 16-bit cell.
nargs
The nargs item indicates the number of 16-bit cells required to represent the
parameters passed to this method, including the this pointer if this method is
a virtual method.
106
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Parameters of type int are represented in two 16-bit cells, while all others are
represented in one 16-bit cell.
max_locals
The max_locals item indicates the number of 16-bit cells required to represent
the local variables declared by this method, not including the parameters
passed to this method on invocation.1
Local variables of type int are represented in two 16-bit cells, while all others
are represented in one 16-bit cell. If an entry in the local variables array of the
stack frame is reused to store more than one local variable (e.g. local variables
from separate scopes), the number of cells required for storage is two if one or
more of the local variables is of type int.
bytecodes[]
The bytecodes item represents an array of Java Card bytecodes that implement this method. Valid instructions are defined in Chapter 7, “Java Card Virtual Machine Instruction Set.” The impdep1 and impdep2 bytecodes can not be
present in the bytecodes array item.
If this method is abstract the bytecodes item must contain zero elements.
6.10
Static Field Component
The Static Field Component contains all of the information required to create and
initialize an image of all of the static fields defined in this package, referred to as the
static field image. Offsets to particular static fields are offsets into the static field
image, not the Static Field Component.
Final static fields of primitive types are not represented in the static field image.
Instead these compile-time constants must be placed in line in Java Card
instructions.
The Static Field Component includes all information required to initialize classes. In
the Java virtual machine a class is initialized by executing its <clinit> method. In
the Java Card virtual machine the functionality of <clinit> methods is represented
in the Static Field Component as array initialization data and non-default values of
primitive types data. §2.2.4.6 contains a description of the subset of <clinit>
functionality supported in the Java Card virtual machine.
1. Unlike in Java Card CAP files, in Java class files the max_locals item includes both the local variables
declared by the method and the parameters passed to the method.
Chapter 6
The CAP File Format
107
The Static Field Component does not reference any other component in this CAP file.
The Constant Pool Component (§6.7), Export Component (§6.12), Descriptor
Component (§6.13), and Debug Component (§6.14) reference fields in the static field
image defined by the Static Field Component.
The ordering constraints, or segments, associated with a static field image are shown
in TABLE 6-14. Reference types occur first in the image. Arrays initialized through
Java <clinit> methods occur first within the set of reference types. Primitive
types occur last in the image, and primitive types initialized to non-default values
occur last within the set of primitive types.
category
segment
content
reference
1
arrays of primitive types initialized by <clinit>
methods
2
reference types initialized to null, including
types
arrays
primitive
types
TABLE 6-14
3
primitive types initialized to default values
4
primitive types initialized to non-default values
Segments of a static field image
The number of bytes used to represent each field type in the static field image is
shown in the following table.
Type
Bytes
boolean
1
byte
1
short
2
int
4
reference, including arrays
2
TABLE 6-15
Static field sizes
The static_field_component structure is defined as:
static_field_component {
u1 tag
u2 size
u2 image_size
u2 reference_count
u2 array_init_count
array_init_info array_init[array_init_count]
u2 default_value_count
u2 non_default_value_count
u1 non_default_values[non_default_values_count]
}
The items in the static_field_component structure are as follows:
108
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
tag
The tag item has the value COMPONENT_StaticField (8).
size
The size item indicates the number of bytes in the static_field_component
structure, excluding the tag and size items. The value of the size item must
be greater than zero.
image_size
The image_size item indicates the number of bytes required to represent the
static fields defined in this package, excluding final static fields of primitive
types. This value is the number of bytes in the static field image. The number of
bytes required to represent each field type is shown in TABLE 6-15.
The value of the image_size item does not include the number of bytes
require to represent the initial values of array instances enumerated in the
Static Field Component.
The value of the image_size is defined as:
image_size =
reference_count * 2 +
default_value_count +
non_default_value_count.
reference_count
The reference_count item indicates the number of reference type static
fields defined in this package. This is the number of fields represented in segments 1 and 2 of the static field image as described in TABLE 6-14.
The value of the reference_count item may be 0 if no reference type fields
are defined in this package. Otherwise it must be equal to the number of
reference type fields defined.
array_init_count
The array_init_count item indicates the number of elements in the
array_init array. This is the number of fields represented in segment 1 of the
static field image as described in TABLE 6-14. It represents the number of
arrays initialized in all of the <clinit> methods in this package.
If this CAP file defines a library package the value of array_init_count must
be zero.
array_init[]
The array_init item represents an array of array_init_info structures that
specify the initial array values of static fields of arrays of primitive types.
These initial values are indicated in Java <clinit> methods. The
Chapter 6
The CAP File Format
109
array_init_info structure is defined as:
array_init_info {
u1 type
u2 count
u1 values[count]
}
The items in the array_init_info structure are defined as follows:
type
The type item indicates the type of the primitive array. Valid values
are shown in the following table.
Type
Value
boolean
2
byte
3
short
4
int
5
TABLE 6-16
Array types
count
The count item indicates the number of bytes in the values array. It
does not represent the number of elements in the static field array
(referred to as length in Java), since the values array is an array of
bytes and the static field array may be a non-byte type. The Java
length of the static field array is equal to the count item divided by
the number of bytes required to represent the static field type
(TABLE 6-15) indicated by the type item.
values
The values item represents a byte array containing the initial values
of the static field array. The number of entries in the values array is
equal to the size in bytes of the type indicated by the type item. The
size in bytes of each type is shown in TABLE 6-15.
default_value_count
The default_value_count item indicates the number of bytes required to initialize the set of static fields represented in segment 3 of the static field image
as described in TABLE 6-14. These static fields are primitive types initialized to
default values. The number of bytes required to initialize each static field type
is equal to the size in bytes of the type as shown in TABLE 6-15.
non_default_value_count
The non_default_value_count item represents the number bytes in the
110
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
non_default_values array. This value is equal to the number of bytes in seg-
ment 4 of the static field image as described in TABLE 6-14. These static fields
are primitive types initialized to non-default values.
non_default_values[]
The non_default_values item represents an array of bytes of non-default initial values. This is the exact image of segment 4 of the static field image as
described in TABLE 6-14. The number of entries in the non_default_values
array for each static field type is equal to the size in bytes of the type as shown
in TABLE 6-15.
The value of a boolean type is 1 to represent true and 0 to represent false.
6.11
Reference Location Component
The Reference Location Component represents lists of offsets into the info item of
the Method Component (§6.9) to items that contain indices into the
constant_pool[] array of the Constant Pool Component (§6.7). This includes all
constant pool index operands of instructions, and all non-zero catch_type_index
items of the exception_handlers array. The catch_type_index items that have the
value of 0 are not included since they represent finally blocks instead of particular
exception classes.
Some of the constant pool indices are represented in one-byte values while others are
represented in two-byte values. Operands of getfield_T and putfield_T instructions are
one-byte constant pool indices. All other indices in a Method Component are twobyte values.
The Reference Location Component is not referenced by any other component in this
CAP file.
The Reference Location Component structure is defined as:
reference_location_component {
u1 tag
u2 size
u2 byte_index_count
u1 offsets_to_byte_indices[byte_index_count]
u2 byte2_index_count
u1 offsets_to_byte2_indices[byte2_index_count]
}
The items of the reference_location_component structure are as follows:
Chapter 6
The CAP File Format
111
tag
The tag item has the value COMPONENT_ReferenceLocation (9).
size
The size item indicates the number of bytes in the
reference_location_component structure, excluding the tag and size
items. The value of the size item must be greater than zero.
byte_index_count
The byte_index_count item represents the number of elements in the
offsets_to_byte_indices array.
offsets_to_byte_indices[]
The offsets_to_byte_indices item represents an array of 1-byte jump offsets into the info item of the Method Component to each 1-byte
constant_pool[] array index. Each entry represents the number of bytes (or
distance) between the current index to the next. If the distance is greater than or
equal to 255 then there are n entries equal to 255 in the array, where n is equal
to the distance divided by 255. The nth entry of 255 is followed by an entry
containing the value of the distance modulo 255.
An example of the jump offsets in an offsets_to_byte_indices array is
shown in the following table.
Instruction
Offset to
Operand
Jump Offset
getfield_a 0
10
10
putfield_b 2
65
55
255
255
getfield_s 1
580
5
255
putfield_a 0
835
0
getfield_i 3
843
8
TABLE 6-17
One-byte reference location example
All 1-byte constant_pool[] array indices in the Method Component must be
represented in offsets_to_byte_indices array.
byte2_index_count
The byte2_index_count item represents the number of elements in the
offsets_to_byte2_indices array.
offsets_to_byte2_indices[]
The offsets_to_byte2_indices item represents an array of 1-byte jump off112
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sets into the info item of the Method Component to each 2-byte
constant_pool[] array index. Each entry represents the number of bytes (or
distance) between the current index to the next. If the distance is greater than or
equal to 255 then there are n entries equal to 255 in the array, where n is equal
to the distance divided by 255. The nth entry of 255 is followed by an entry containing the value of the distance modulo 255.
An example of the jump offsets in an offsets_to_byte_indices array is
shown in TABLE 6-17. The same example applies to the
offsets_to_byte2_indices array if the instructions are changed to those
with 2-byte constant_pool[] array indices.
All 2-byte constant_pool[] array indices in the Method Component must be
represented in offsets_to_byte2_indices array, including those represented in catch_type_index items of the exception_handler_info array.
Chapter 6
The CAP File Format
113
6.12
Export Component
The Export Component lists all static elements in this package that may be imported
by classes in other packages. Instance fields and virtual methods are not represented
in the Export Component.
If this CAP file does not include an Applet Component (§6.5) (called a library
package), the Export Component contains an entry for each public class and public
interface defined in this package. Furthermore, for each public class there is an
entry for each public or protected static field defined in that class, for each
public or protected static method defined in that class, and for each public or
protected constructor defined in that class. Final static fields of primitive types
(compile-time constants) are not included.
If this CAP file includes an Applet Component (§6.5) (called an applet package) the
Export Component includes entries only for all public interfaces that are shareable.1
An interface is shareable if and only if it is the javacard.framework.Shareable
interface or implements (directly or indirectly) that interface.
Elements in the Export Component reference elements in the Class Component
(§6.8), Method Component (§6.9), and Static Field Component (§6.10). No other
component in this CAP file references the Export Component.
The Export Component is represented by the following structure:
export_component {
u1 tag
u2 size
u1 class_count
class_export_info {
u2 class_offset
u1 static_field_count
u1 static_method_count
u2 static_field_offsets[static_field_count]
u2 static_method_offsets[static_method_count]
} class_exports[class_count]
}
The items of the export_component structure are as follows:
tag
The tag item has the value COMPONENT_Export (10).
1. The restriction on shareable functionality is imposed by the firewall as defined in the Java CardÔ 2.2 Runtime
Environment (JCRE) Specification.
114
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
size
The size item indicates the number of bytes in the export_component structure, excluding the tag and size items. The value of the size item must be
greater than zero.
class_count
The class_count item represents the number of entries in the class_exports
table. The value of the class_count item must be greater than zero.
class_exports[]
The class_exports item represents a variable-length table of
class_export_info structures. If this package is a library package, the table
contains an entry for each of the public classes and public interfaces defined
in this package. If this package is an applet package, the table contains an entry
for each of the public shareable interfaces defined in this package.
An index into the table to a particular class or interface is equal to the token
value of that class or interface (§4.3.7.2). The token value is published in the
Export file (§5.7) of this package.
The items in the class_export_info structure are:
class_offset
The class_offset item represents a byte offset into the info item of
the Class Component (§6.8). If this package defines a library package,
the item at that offset must be either an interface_info or a
class_info structure. The interface_info or class_info structure at that offset must represent the exported class or interface.
If this package defines an applet package, the item at the
class_offset in the info item of the Class Component must be an
interface_info structure. The interface_info structure at that
offset must represent the exported, shareable interface. In particular,
the ACC_SHAREABLE flag of the interface_info structure must be
equal to 1.
static_field_count
The static_field_count item represents the number of elements in
the static_field_offsets array. This value indicates the number
of public and protected static fields defined in this class, excluding final static fields of primitive types.
If the class_offset item represents an offset to an interface_info
structure, the value of the static_field_count item must be zero.
static_method_count
The static_method_count item represents the number of elements
Chapter 6
The CAP File Format
115
in the static_method_offsets array. This value indicates the number of public and protected static methods and constructors
defined in this class.
If the class_offset item represents an offset to an interface_info
structure, the value of the static_method_count item must be zero.
static_field_offsets[]
The static_field_offsets item represents an array of 2-byte offsets
into the static field image defined by the Static Field Component
(§6.10). Each offset must be to the beginning of the representation of
the exported static field.
An index into the static_field_offsets array must be equal to the
token value of the field represented by that entry. The token value is
published in the Export file (§5.9) of this package.
static_method_offsets[]
The static_method_offsets item represents a table of 2-byte offsets
into the info item of the Method Component (§6.9). Each offset must
be to the beginning of a method_info structure. The method_info
structure must represent the exported static method or constructor.
An index into the static_method_offsets array must be equal to
the token value of the method represented by that entry.
116
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
6.13
Descriptor Component
The Descriptor Component provides sufficient information to parse and verify all
elements of the CAP file. It references, and therefore describes, elements in the
Constant Pool Component (§6.7), Class Component (§6.8), Method Component
(§6.9), and Static Field Component (§6.10). No components in the CAP file reference
the Descriptor Component.
The Descriptor Component is represented by the following structure:
descriptor_component {
u1 tag
u2 size
u1 class_count
class_descriptor_info classes[class_count]
type_descriptor_info types
}
The items of the descriptor_component structure are as follows:
tag
The tag item has the value COMPONENT_Descriptor (11).
size
The size item indicates the number of bytes in the descriptor_component
structure, excluding the tag and size items. The value of the size item must
be greater than zero.
class_count
The class_count item represents the number of entries in the classes table.
classes[]
The classes item represents a table of variable-length
class_descriptor_info structures. Each class and interface defined in this
package is represented in the table.
types
The types item represents a type_descriptor_info structure. This structure
lists the set of field types and method signatures of the fields and methods
defined or referenced in this package. Those referenced are enumerated in the
Constant Pool Component.
Chapter 6
The CAP File Format
117
6.13.1
class_descriptor_info
The class_descriptor_info structure is used to describe a class or interface
defined in this package:
class_descriptor_info {
u1 token
u1 access_flags
class_ref this_class_ref
u1 interface_count
u2 field_count
u2 method_count
class_ref interfaces [interface_count]
field_descriptor_info fields[field_count]
method_descriptor_info methods[method_count]
}
The items of the class_descriptor_info structure are as follows:
token
The token item represents the class token (§4.3.7.2) of this class or interface. If
this class or interface is package-visible it does not have a token assigned. In
this case the value of the token item must be 0xFF.
access_flags
The access_flags item is a mask of modifiers used to describe the access permission to and properties of this class or interface. The access_flags modifiers for classes and interfaces are shown in the following table.
Name
Value
ACC_PUBLIC
0x01
ACC_FINAL
0x10
ACC_INTERFACE
0x40
ACC_ABSTRACT
0x80
TABLE 6-18
CAP file class descriptor flags
The class access and modifier flags defined in the table above are a subset of
those defined for classes and interfaces in a Java class file. They have the
same meaning, and are set under the same conditions, as the corresponding
flags in a Java class file.
All other flag values are reserved. Their values must be zero.
this_class_ref
The this_class_ref item is a class_ref structure indicating the location of
the class_info structure in the Class Component (§6.8). The class_ref
118
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
structure is defined as part of the CONSTANT_Classref_info structure (§6.7.1).
interface_count
The interface_count item represents the number of entries in the
interfaces array. For an interface, interface_count is always set to zero.
field_count
The field_count item represents the number of entries in the fields array. If
this class_descriptor_info structure represents an interface, the value of
the field_count item is equal to zero.
Static final fields of primitive types are not represented as fields in a CAP
file, but instead these compile-time constants are placed inline in bytecode
sequences. The field_count item does not include static final field of primitive types defined by this class.
method_count
The method_count item represents the number of entries in the methods array.
interfaces[]
The interfaces item represents an array of interfaces implemented by this
class. The elements in the array are class_ref structures indicating the location of the interface_info structure in the Class Component (§6.8). The
class_ref structure is defined as part of the CONSTANT_Classref_info structure (§6.7.1).
fields[]
The fields item represents an array of field_descriptor_info structures.
Each field declared by this class is represented in the array, except static
final fields of primitive types. Inherited fields are not included in the array.
methods[]
The methods item represents an array of method_descriptor_info structures. Each method declared or defined by this class or interface is represented
in the array. For a class, inherited methods are not included in the array. For
an interface, inherited methods are included in the array.
6.13.2
field_descriptor_info
The field_descriptor_info structure is used to describe a field defined in this
package:
field_descriptor_info {
u1 token
u1 access_flags
union {
Chapter 6
The CAP File Format
119
static_field_ref static_field
{
class_ref class
u1 token
} instance_field
} field_ref
union {
u2 primitive_type
u2 reference_type
} type
}
The items of the field_descriptor_info structure are as follows:
token
The token item represents the token of this field. If this field is private or package-visible static field it does not have a token assigned. In this case the value
of the token item must be 0xFF.
access_flags
The access_flags item is a mask of modifiers used to describe the access permission to and properties of this field. The access_flags modifiers for fields
are shown in the following table.
Name
Value
ACC_PUBLIC
0x01
ACC_PRIVATE
0x02
ACC_PROTECTED
0x04
ACC_STATIC
0x08
ACC_FINAL
0x10
TABLE 6-19
CAP file field descriptor flags
The field access and modifier flags defined in the table above are a subset of
those defined for fields in a Java class file. They have the same meaning, and
are set under the same conditions, as the corresponding flags in a Java class
file.
All other flag values are reserved. Their values must be zero.
field_ref
The field_ref item represents a reference to this field. If the ACC_STATIC flag
is equal to 1, this item represents a static_field_ref as defined in the
CONSTANT_StaticFieldref structure (§6.7.3).
If the ACC_STATIC flag is equal to 0, this item represents a reference to an
instance field. It contains a class_ref item and an instance field token item.
120
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
These items are defined in the same manner as in the
CONSTANT_InstanceFieldref structure (§6.7.2).
type
The type item indicates the type of this field. directly or indirectly. If this field
is a primitive type (boolean, byte, short, or int) the high bit of this item is
equal to 1, otherwise the high bit of this item is equal to 0.
primitive_type
The primitive_type item represents the type of this field using the
values in the table below. As noted above, the high bit of the
primitive_type item is equal to 1.
Data Type
Value
boolean
0x0002
byte
0x0003
short
0x0004
int
0x0005
TABLE 6-20
Primitive type descriptor values
reference_type
The reference_type item represents a 15-bit offset into the
type_descriptor_info structure. The item at the offset must represent the reference type of this field. As noted above, the high bit of
the reference_type item is equal to 0.
6.13.3
method_descriptor_info
The method_descriptor_info structure is used to describe a method defined in this
package. This structure contains sufficient information to locate and parse the
methods in the Method Component, while the Method Component does not.
method_descriptor_info {
u1 token
u1 access_flags
u2 method_offset
u2 type_offset
u2 bytecode_count
u2 exception_handler_count
u2 exception_handler_index
}
The items of the method_descriptor_info structure are as follows:
Chapter 6
The CAP File Format
121
token
The token item represents the static method token (§4.3.7.4) or virtual method
token (§4.3.7.6) or interface method token (§4.3.7.7) of this method. If this
method is a private or package-visible static method, a private or package-visible constructor, or a private virtual method it does not have a token assigned.
In this case the value of the token item must be 0xFF.
access_flags
The access_flags item is a mask of modifiers used to describe the access permission to and properties of this method. The access_flags modifiers for
methods are shown in the following table.
Name
Value
ACC_PUBLIC
0x01
ACC_PRIVATE
0x02
ACC_PROTECTED
0x04
ACC_STATIC
0x08
ACC_FINAL
0x10
ACC_ABSTRACT
0x40
ACC_INIT
0x80
TABLE 6-21
CAP file method descriptor flags
The method access and modifier flags defined in the table above, except the
ACC_INIT flag, are a subset of those defined for methods in a Java class file.
They have the same meaning, and are set under the same conditions, as the
corresponding flags in a Java class file.
The ACC_INIT flag is set if the method descriptor identifies a constructor methods. In Java a constructor method is recognized by its name, <init>, but in
Java Card the name is replaced by a token. As in the Java verifier, these methods require special checks by the Java Card verifier.
All other flag values are reserved. Their values must be zero.
method_offset
If the class_descriptor_info structure that contains this
method_descriptor_info structure represents a class, the method_offset
item represents a byte offset into the info item of the Method Component
(§6.9). The element at that offset must be the beginning of a method_info
structure. The method_info structure must represent this method.
If the class_descriptor_info structure that contains this
method_descriptor_info structure represents an interface, the value of the
method_offset item must be zero.
122
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
type_offset
The type_offset item must be a valid offset into the
type_descriptor_info structure. The type described at that offset represents
the signature of this method.
bytecode_count
The bytecode_count item represents the number of bytecodes in this method.
The value is equal to the length of the bytecodes array item in the
method_info structure in the method component (§6.9) of this method.
exception_handler_count
The exception_handler_count item represents the number of exception handlers implemented by this method.
exception_handler_index
The exception_handler_index item represents the index to the first
exception_handlers table entry in the method component (§6.9) implemented by this method. Succeeding exception_handlers table entries, up to
the value of the exception_handler_count item, are also exception handlers
implemented by this method.
The value of the exception_handler_index item is 0 if the value of the
exception_handler_count item is 0.
6.13.4
type_descriptor_info
The type_descriptor_info structure represents the types of fields and signatures
of methods defined in this package:
type_descriptor_info {
u2 constant_pool_count
u2 constant_pool_types[constant_pool_count]
type_descriptor type_desc[]
}
The type_descriptor_info structure contains the following elements:
constant_pool_count
The constant_pool_count item represents the number of entries in the
constant_pool_types array. This value is equal to the number of entries in
the constant_pool array of the Constant Pool Component (§6.7).
constant_pool_types[]
The constant_pool_types item is an array that describes the types of the
Chapter 6
The CAP File Format
123
fields and methods referenced in the Constant Pool Component. This item has
the same number of entries as the constant_pool[] array of the Constant
Pool Component, and each entry describes the type of the corresponding entry
in the constant_pool[] array.
If the corresponding constant_pool[] array entry represents a class or interface reference, it does not have an associated type. In this case the value of the
entry in the constant_pool_types array item is 0xFFFF.
If the corresponding constant_pool[] array entry represents a field or
method, the value of the entry in the constant_pool_types array is an offset
into the type_descriptor_info structure. The element at that offset must
describe the type of the field or the signature of the method.
type_desc[]
The type_desc item represents a table of variable-length type_descriptor
structures. These descriptors represent the types of fields and signatures of
methods. For a description of the type_descriptor structure, see section
§6.8.1.
124
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
6.14
Debug Component
This section specifies the format for the Debug Component. The Debug Component
contains all the metadata necessary for debugging a package on a suitably
instrumented Java Card virtual machine. It is not required for executing Java Card
software in a non-debug environment.
The Debug Component references the Class Component (§6.8), Method Component
(§6.9), and Static Field Component (§6.10). No components reference the Debug
Component.
The Debug Component is represented by the following structure:
debug_component {
u1 tag
u2 size
u2 string_count
utf8_info strings_table[string_count]
u2 package_name_index
u2 class_count
class_debug_info classes[class_count]
}
The items in the debug_component structure are defined as follows:
tag
The tag item has the value COMPONENT_Debug (12).
size
The number of bytes in the component, excluding the tag and size items.
The value of size must be greater than zero.
string_count
The number of strings in the strings_table[] table.
strings_table[]
A table of all the strings used in this component. Various items that occur
through this component represent unsigned two-byte indices into this table.
Each entry in the table is a utf8_info structure. A utf8_info structure is represented by the following structure:
Chapter 6
The CAP File Format
125
utf8_info {
u2 length
u1 bytes[length]
}
The items in the utf8_info structure are defined as follows:
length
The number of bytes in the string.
bytes
The bytes of the string in UTF-8 format.
package_name_index
Contains an index into the strings_table[] item. The strings_table[]
item entry referenced by this index must contain the fully-qualified name of
the package in this CAP file.
class_count
The number of classes in the classes table.
classes[]
Contains a single class_debug_info[] structure for each class in this package.
6.14.1
The class_debug_info Structure
The class_debug_info structure contains all of the debugging information for a
class or interface. It also contains tables of debugging information for all its classes’
fields and methods.
class_debug_info {
u2 name_index
u2 access_flags
u2 location
u2 superclass_name_index
u2 source_file_index
u1 interface_count
u2 field_count
u2 method_count
u2 interface_names_indexes[interface_count]
field_debug_info fields[field_count]
method_debug_info methods[method_count]
}
The items in the class_debug_info structure are defined as follows:
126
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
name_index
Contains an index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
fully-qualified name of this class.
access_flags
A two-byte mask of modifiers that apply to this class. The modifiers are:
Modifier
Value
ACC_PUBLIC
0x0001
ACC_FINAL
0x0010
ACC_REMOTE
0x0020
ACC_INTERFACE
0x0200
ACC_ABSTRACT
0x0400
ACC_SHAREABLE
0x0800
TABLE 6-22
Class access and modifier flags
The ACC_SHAREABLE flag indicates whether this class or interface is shareable.1
A class is shareable if it implements (directly or indirectly) the
javacard.framework.Shareable interface. An interface is shareable if it is or
extends (directly or indirectly) the javacard.framework.Shareable interface.
The ACC_REMOTE flag indicates whether this class or interface is remote. The
value of this flag must be one if and only if the class or interface satisfies the
requirements defined in §2.2.6.1.
All other class access and modifier flags are defined in the same way and with
the same restrictions as described in The JavaÔ Virtual Machine Specification.
location
The byte offset of the class_info or interface_info record for this class or
interface into the info item of the Class Component (§6.8).
superclass_name_index
Contains an index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
fully-qualified name of the superclass of this class or the string “null” if the
class has no superclass.
1. The ACC_SHAREABLE flag is defined to enable Java Card virtual machines to implement the firewall
restrictions defined by the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 6
The CAP File Format
127
source_file_index
Contains the index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
name of the source file in which this class is defined.
interface_count
The number of indexes in the interface_names_indexes[] table.
field_count
The number of field_debug_info structures in the fields[] table.
method_count
The number of method_debug_info structures in the methods[] table.
interface_names_indexes[]
Contains the indexes into the strings_table[] item of the debug_component
structure. The strings_table[] entry at each indexed location must be the
name of an interface implemented by this class. There must be an index value
present for every interface implemented by this class, including interfaces
implemented by superclasses of this class and superinterfaces of the implemented interfaces.
If ACC_INTERFACE is set, the strings_table[] entry at each indexed location
must be the name of a super interface directly or indirectly extended by this
interface. There must be an index value present for every super interface
directly or indirectly extended by this interface.
fields[]
Contains field_debug_info structures for all the fields declared by this class,
including static final fields of primitive types. Inherited fields are not
included in this array.
methods[]
Contains method_debug_info structures for all the methods declared or
defined in this class. Inherited methods are not included in this array.
6.14.1.1
The field_debug_info Structure
The field_debug_info structure describes a field in a class. It can describe either an
instance field, a static field, or a constant (primitive final static) field. The contents
union will have the form of a token_var if the field is an instance field, a
location_var if it is a static field, or a const_value if it is a constant.
The field_debug_info structure is defined as follows:
128
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
field_debug_info {
u2 name_index
u2 descriptor_index
u2 access_flags
union {
{
u1 pad1
u1 pad2
u1 pad3
u1 token
} token_var
{
u2 pad
u2 location
} location_var
u4 const_value
} contents
}
The items in the field_debug_info structure are defined as follows:
name_index
Contains an index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
simple (i.e. not fully-qualified) name of the field (for example, “applets”).
descriptor_index
Contains an index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
type of the field. Class types are fully-qualified (for example, “[Ljavacard/
framework/Applet;”).
access_flags
A two-byte mask of modifiers that apply to this field.
TABLE 6-23
Modifier
Value
ACC_PUBLIC
0x0001
ACC_PRIVATE
0x0002
ACC_PROTECTED
0x0004
ACC_STATIC
0x0008
ACC_FINAL
0x0010
Field access and modifier flags
The above field access and modifier flags are defined in the same way and with
the same restrictions as described in The JavaÔ Virtual Machine Specification.
Chapter 6
The CAP File Format
129
contents
A field_debug_info structure can describe an instance field, a static field, or
a static final field (a constant). Constants can be either primitive data or arrays
of primitive data. Depending on the kind of field described, the contents item
is interpreted in different ways. The kind and type of the field can be determined by examining the field’s descriptor and access flags.
token_var
If the field is an instance field, this value is the instance field token of
the field. The pad1, pad2, and pad3 items are padding only; their values should be ignored.
location_var
If the field is a non-final static field or a final static field with an array
type (a constant array), this value is the byte offset of the location for
this field in the static field image defined by the Static Field Component (§6.10). The pad item is padding only; its value should be
ignored.
const_value
If the field is a final static field of type byte, boolean, short, or int,
this value is interpreted as a signed 32-bit constant.
6.14.1.2
The method_debug_info Structure
The method_debug_info structure describes a method of a class. It can describe
methods that are either virtual or non-virtual (static or initialization methods). The
structure is defined as follows:
method_debug_info {
u2 name_index
u2 descriptor_index
u2 access_flags
u2 location
u1 header_size
u2 body_size
u2 variable_count
u2 line_count
variable_info variable_table[variable_count]
line_info line_table[line_count]
}
The items in the method_debug_info structure are defined as follows:
130
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
name_index
Contains an index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
simple (i.e. not fully-qualified) name of the method (e.g. “lookupAID”).
descriptor_index
Contains an index into the strings_table[] item of the debug_component
structure. The strings_table[] entry at the indexed location must be the
argument and return types of the method (i.e. the signature without the
method name). Class types are fully-qualified (for example,
“([BSB)Ljavacard/framework/AID;”)
access_flags
A two-byte mask of modifiers that apply to this method.
Modifier
Value
ACC_PUBLIC
0x0001
ACC_PRIVATE
0x0002
ACC_PROTECTED
0x0004
ACC_STATIC
0x0008
ACC_FINAL
0x0010
ACC_NATIVE
0x0100
ACC_ABSTRACT
0x0400
TABLE 6-24
Method modifier flags
The ACC_NATIVE flag is only valid for methods of a package located in the card
mask. It cannot be used for methods contained in a CAP file.
All other method access and modifier flags are defined in the same way and
with the same restrictions as described in The JavaÔ Virtual Machine Specification.
location
A byte offset of the method_info structure for this method into the info item
of the Method Component (§6.9). Abstract methods have a location of zero.
header_size
The size in bytes of the header of the method. Abstract methods have a
header_size of zero.
body_size
The size in bytes of the body of the method, not including the method header.
Abstract methods have a body_size of zero.
Chapter 6
The CAP File Format
131
variable_count
The number of variable_info entries in the variable_table[] item.
Abstract methods have a variable_count of zero.
line_count
The number of line_info entries in the line_table[] item.Abstract methods
have a line_count of zero.
variable_table[]
Contains the variable_info structures for all variables in this method.
The variable_info structure describes a single local variable of a method. It
indicates the index into the local variables of the current frame at which the
local variable can be found, as well as the name and type of the variable. It also
indicates the range of bytecodes within which the variable has a value.
variable_info {
u1 index
u2 name_index
u2 descriptor_index
u2 start_pc
u2 length
}
The items in the variable_info structure are defined as follows:
index
The index of the variable in the local stack frame, as used in load and
store bytecodes. If the variable at index is of type int, it occupies both
index and index + 1.
name_index
Contains an index into the strings_table[] item of the
debug_component structure. The strings_table[] entry at the
indexed location must be the name of the local variable. (e.g.
“applets”).
descriptor_index
Contains an index into the strings_table[] item of the
debug_component structure. The strings_table[] entry at the
indexed location must be the type of the local variable. Class types are
fully-qualified (e.g. “[Ljavacard/framework/Applet;”).
start_pc
The index of the first bytecode in which the variable is in-scope and
valid.
132
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
length
Number of bytecodes in which the variable is in-scope and valid. The
value of start_pc + length will be either the index of the next bytecode after the valid range, or the first index beyond the end of the
bytecode array.
line_table[]
Contains the line_info structures that map bytecode instructions of this
method to lines in the class’s source file.
Each line_info item represents a mapping of a range of bytecode instructions
to a particular line in the source file that contains the method. The range of
instructions is from start_pc to end_pc, inclusive. start_pc and end_pc
represent a zero-based byte offset within the method. The source_line is the
one-based line number in the source file. The structure is defined as follows:
line_info {
u2 start_pc
u2 end_pc
u2 source_line
}
The items in the line_info structure are defined as follows:
start_pc
The byte offset of the first bytecode in the range of instructions.
end_pc
The byte offset of the last operand of the last bytecode in the range of
instructions.
source_line
Line number in the source file.
Chapter 6
The CAP File Format
133
134
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
7
Java Card Virtual Machine
Instruction Set
A Java Card virtual machine instruction consists of an opcode specifying the
operation to be performed, followed by zero or more operands embodying values to
be operated upon. This chapter gives details about the format of each Java Card
virtual machine instruction and the operation it performs.
7.1
Assumptions: The Meaning of “Must”
The description of each instruction is always given in the context of Java Card
virtual machine code that satisfies the static and structural constraints of Chapter 6,
“The CAP File Format.”
In the description of individual Java Card virtual machine instructions, we
frequently state that some situation “must” or “must not” be the case: “The value2
must be of type int.” The constraints of Chapter 6, “The CAP File Format”
guarantee that all such expectations will in fact be met. If some constraint (a “must”
or “must not”) in an instruction description is not satisfied at run time, the behavior
of the Java Card virtual machine is undefined.
135
7.2
Reserved Opcodes
In addition to the opcodes of the instructions specified later this chapter, which are
used in Java Card CAP files (see Chapter 6, “The CAP File Format”), two opcodes are
reserved for internal use by a Java Card virtual machine implementation. If Sun
extends the instruction set of the Java Card virtual machine in the future, these
reserved opcodes are guaranteed not to be used.
The two reserved opcodes, numbers 254 (0xfe) and 255 (0xff), have the mnemonics
impdep1 and impdep2, respectively. These instructions are intended to provide “back
doors” or traps to implementation-specific functionality implemented in software
and hardware, respectively.
Although these opcodes have been reserved, they may only be used inside a Java
Card virtual machine implementation. They cannot appear in valid CAP files.
7.3
Virtual Machine Errors
A Java Card virtual machine may encounter internal errors or resource limitations
that prevent it from executing correctly written Java programs. While the Java Virtual
Machine Specification allows reporting and handling of virtual machine errors, it also
states that they cannot ordinarily be handled by application code. This Java Card
Virtual Machine Specification is more restrictive in that it does not allow for any
reporting or handling of unrecoverable virtual machine errors at the application
code level. A virtual machine error is considered unrecoverable if further execution
could compromise the security or correct operation of the virtual machine or
underlying system software. When an unrecoverable error occurs, the virtual
machine will halt bytecode execution. Responses beyond halting the virtual machine
are implementation-specific policies and are not mandated in this specification.
In the case where the virtual machine encounters a recoverable error, such as
insufficient memory to allocate a new object, it will throw a SystemException with
an error code describing the error condition. The Java Card Virtual Machine
Specification cannot predict where resource limitations or internal errors may be
encountered and does not mandate precisely when they can be reported. Thus, a
SystemException may be thrown at any time during the operation of the Java Card
virtual machine.
136
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
7.4
Security Exceptions
Instructions of the Java Card virtual machine throw an instance of the class
SecurityException when a security violation has been detected. The Java Card
virtual machine does not mandate the complete set of security violations that can or
will result in an exception being thrown. However, there is a minimum set that must
be supported.
In the general case, any instruction that de-references an object reference must throw
a SecurityException if the context (§3.4) in which the instruction is executing is
different than the owning context (§3.4) of the referenced object. The list of
instructions includes the instance field get and put instructions, the array load and
store instructions, as well as the arraylength, invokeinterface, invokespecial, invokevirtual,
checkcast, instanceof and athrow instructions.
There are several exceptions to this general rule that allow cross-context use of
objects or arrays. These exceptions are detailed in Chapter 6 of the Java CardÔ 2.2
Runtime Environment (JCRE) Specification. An important detail to note is that any
cross-context method invocation will result in a context switch (§3.4).
The Java Card virtual machine may also throw a SecurityException if an
instruction violates any of the static constraints of Chapter 6, “The CAP File
Format.” The Java CardÔ 2.2 Virtual Machine Specification does not mandate which
instructions must implement these additional security checks, or to what level.
Therefore, a SecurityException may be thrown at any time during the operation of
the Java Card virtual machine.
7.5
The Java Card Virtual Machine
Instruction Set
Java Virtual Machine instructions are represented in this chapter by entries of the
form shown in the figure below, an example instruction page, in alphabetical order
and each beginning on a new page.
Chapter 7
Java Card Virtual Machine Instruction Set
137
mnemonic
mnemonic
Short description of the instruction
Format
mnemonic
operand1
operand2
…
Forms
mnemonic = opcode
Stack
…, value1, value2 Þ
…, value3
Description
A longer description detailing constraints on operand stack
contents or constant pool entries, the operation performed, the
type of the results, etc.
Runtime Exceptions
If any runtime exceptions can be thrown by the execution of an
instruction they are set off one to a line, in the order in which
they must be thrown.
Other than the runtime exceptions, if any, listed for an
instruction, that instruction must not throw any runtime
exceptions except for instances of SystemException.
Notes
Comments not strictly part of the specification of an instruction
are set aside as notes at the end of the description.
FIGURE 7-1
An example instruction page
Each cell in the instruction format diagram represents a single 8-bit byte. The
instruction’s mnemonic is its name. Its opcode is its numeric representation and is
given in both decimal and hexadecimal forms. Only the numeric representation is
actually present in the Java Card virtual machine code in a CAP file.
Keep in mind that there are “operands” generated at compile time and embedded
within Java Card virtual machine instructions, as well as “operands” calculated at
run time and supplied on the operand stack. Although they are supplied from
several different areas, all these operands represent the same thing: values to be
138
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
operated upon by the Java Card virtual machine instruction being executed. By
implicitly taking many of its operands from its operand stack, rather than
representing them explicitly in its compiled code as additional operand bytes,
register numbers, etc., the Java Card virtual machine’s code stays compact.
Some instructions are presented as members of a family of related instructions
sharing a single description, format, and operand stack diagram. As such, a family
of instructions includes several opcodes and opcode mnemonics; only the family
mnemonic appears in the instruction format diagram, and a separate forms line lists
all member mnemonics and opcodes. For example, the forms line for the sconst_<s>
family of instructions, giving mnemonic and opcode information for the two
instructions in that family (sconst_0 and sconst_1), is
Forms sconst_0 = 3 (0x3),
sconst_1 = 4 (0x4)
In the description of the Java Card virtual machine instructions, the effect of an
instruction’s execution on the operand stack (§3.5) of the current frame (§3.5) is
represented textually, with the stack growing from left to right and each word
represented separately. Thus,
Stack…, value1, value2 Þ
…, result
shows an operation that begins by having a one-word value2 on top of the operand
stack with a one-word value1 just beneath it. As a result of the execution of the
instruction, value1 and value2 are popped from the operand stack and replaced by a
one-word result, which has been calculated by the instruction. The remainder of the
operand stack, represented by an ellipsis (…), is unaffected by the instruction’s
execution.
The type int takes two words on the operand stack. In the operand stack
representation, each word is represented separately using a dot notation:
Stack…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
The Java Card Virtual Machine Specification does not mandate how the two words are
used to represent the 32-bit int value; it only requires that a particular
implementation be internally consistent.
Chapter 7
Java Card Virtual Machine Instruction Set
139
aaload
aaload
Load reference from array
Format
aaload
Forms
aaload = 36 (0x24)
Stack
…, arrayref, index Þ
…, value
Description
The arrayref must be of type reference and must refer to an array whose
components are of type reference. The index must be of type short. Both arrayref
and index are popped from the operand stack. The reference value in the component
of the array at index is retrieved and pushed onto the top of the operand stack.
Runtime Exceptions
If arrayref is null, aaload throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
aaload instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the aaload instruction may throw a SecurityException if the
current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
140
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
aastore
aastore
Store into reference array
Format
aastore
Forms
aastore = 55 (0x37)
Stack
…, arrayref, index, value Þ
…
Description
The arrayref must be of type reference and must refer to an array whose
components are of type reference. The index must be of type short and the value
must be of type reference. The arrayref, index and value are popped from the
operand stack. The reference value is stored as the component of the array at index.
At runtime the type of value must be confirmed to be assignment compatible with
the type of the components of the array referenced by arrayref. Assignment of a value
of reference type S (source) to a variable of reference type T (target) is allowed only
when the type S supports all of the operations defined on type T. The detailed rules
follow:
■
If S is a class type, then:
■
■
■
If T is a class type, then S must be the same class as T, or S must be a subclass
of T;
If T is an interface type, then S must implement interface T.
If S is an interface type1, then:
■
■
If T is a class type, then T must be Object (§2.2.2.4);
If T is an interface type, T must be the same interface as S or a superinterface of
S.
1. When both S and T are arrays of reference types, this algorithm is applied recursively using the types of the
arrays, namely SC and TC. In the recursive call, S, which was SC in the original call, may be an interface type.
This rule can only be reached in this manner. Similarly, in the recursive call,T, which was TC in the original call,
may be an interface type.
Chapter 7
Java Card Virtual Machine Instruction Set
141
aastore (cont.)
■
aastore (cont.)
If S is an array type, namely the type SC[], that is, an array of components of type
SC, then:
■
■
If T is a class type, then T must be Object.
If T is an array type, namely the type TC[], an array of components of type TC,
then one of the following must be true:
■
TC and SC are the same primitive type (§3.1).
■
TC and SC are reference types1 (§3.1) with type SC assignable to TC, by these
rules.
■
If T is an interface type, T must be one of the interfaces implemented by arrays.
Runtime Exceptions
If arrayref is null, aastore throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
aastore instruction throws an ArrayIndexOutOfBoundsException.
Otherwise, if arrayref is not null and the actual type of value is not assignment
compatible with the actual type of the component of the array, aastore throws an
ArrayStoreException.
Notes
In some circumstances, the aastore instruction may throw a SecurityException if
the current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
1. This version of the Java Card Virtual Machine Specification does not support multi-dimensional arrays.
Therefore, neither SC or TC can be an array type.
142
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
aconst_null
aconst_null
Push null
Format
aconst_null
Forms
aconst_null = 1 (0x1)
Stack
…Þ
…, null
Description
Push the null object reference onto the operand stack.
Chapter 7
Java Card Virtual Machine Instruction Set
143
aload
aload
Load reference from local variable
Format
aload
index
Forms
aload = 21 (0x15)
Stack
…Þ
…, objectref
Description
The index is an unsigned byte that must be a valid index into the local variables of
the current frame (§3.5). The local variable at index must contain a reference. The
objectref in the local variable at index is pushed onto the operand stack.
Notes
The aload instruction cannot be used to load a value of type returnAddress from a
local variable onto the operand stack. This asymmetry with the astore instruction is
intentional.
144
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
aload_<n>
aload_<n>
Load reference from local variable
Format
aload_<n>
Forms
aload_0
aload_1
aload_2
aload_3
=
=
=
=
24
25
26
27
(0x18)
(0x19)
(0x1a)
(0x1b)
Stack
…Þ
…, objectref
Description
The <n> must be a valid index into the local variables of the current frame (§3.5).
The local variable at <n> must contain a reference. The objectref in the local variable
at <n> is pushed onto the operand stack.
Notes
An aload_<n> instruction cannot be used to load a value of type returnAddress
from a local variable onto the operand stack. This asymmetry with the
corresponding astore_<n> instruction is intentional.
Each of the aload_<n> instructions is the same as aload with an index of <n>, except
that the operand <n> is implicit.
Chapter 7
Java Card Virtual Machine Instruction Set
145
anewarray
anewarray
Create new array of reference
Format
anewarray
indexbyte1
indexbyte2
Forms
anewarray = 145 (0x91)
Stack
…, count Þ
…, arrayref
Description
The count must be of type short. It is popped off the operand stack. The count
represents the number of components of the array to be created. The unsigned
indexbyte1 and indexbyte2 are used to construct an index into the constant pool of the
current package (§3.5), where the value of the index is (indexbyte1 << 8) | indexbyte2.
The item at that index in the constant pool must be of type CONSTANT_Classref
(§6.7.1), a reference to a class or interface type. The reference is resolved. A new
array with components of that type, of length count, is allocated from the heap, and
a reference arrayref to this new array object is pushed onto the operand stack. All
components of the new array are initialized to null, the default value for reference
types.
Runtime Exception
If count is less than zero, the anewarray instruction throws a
NegativeArraySizeException.
146
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
areturn
areturn
Return reference from method
Format
areturn
Forms
areturn = 119 (0x77)
Stack
…, objectref Þ
[empty]
Description
The objectref must be of type reference. The objectref is popped from the operand
stack of the current frame (§3.5) and pushed onto the operand stack of the frame of
the invoker. Any other values on the operand stack of the current method are
discarded.
The virtual machine then reinstates the frame of the invoker and returns control to
the invoker.
Chapter 7
Java Card Virtual Machine Instruction Set
147
arraylength
arraylength
Get length of array
Format
arraylength
Forms
arraylength = 146 (0x92)
Stack
…, arrayref Þ
…, length
Description
The arrayref must be of type reference and must refer to an array. It is popped from
the operand stack. The length of the array it references is determined. That length is
pushed onto the top of the operand stack as a short.
Runtime Exception
If arrayref is null, the arraylength instruction throws a NullPointerException.
Notes
In some circumstances, the arraylength instruction may throw a SecurityException
if the current context (§3.4) is not the owning context (§3.4) of the array referenced
by arrayref. The exact circumstances when the exception will be thrown are specified
in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
148
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
astore
astore
Store reference into local variable
Format
astore
index
Forms
astore = 40 (0x28)
Stack
…, objectref Þ
…
Description
The index is an unsigned byte that must be a valid index into the local variables of
the current frame (§3.5). The objectref on the top of the operand stack must be of type
returnAddress or of type reference. The objectref is popped from the operand
stack, and the value of the local variable at index is set to objectref.
Notes
The astore instruction is used with an objectref of type returnAddress when
implementing Java’s finally keyword. The aload instruction cannot be used to load
a value of type returnAddress from a local variable onto the operand stack. This
asymmetry with the astore instruction is intentional.
Chapter 7
Java Card Virtual Machine Instruction Set
149
astore_<n>
astore_<n>
Store reference into local variable
Format
astore_<n>
Forms
astore_0
astore_1
astore_2
astore_3
=
=
=
=
43
44
45
46
(0x2b)
(0x2c)
(0x2d)
(0x2e)
Stack
…, objectref Þ
…
Description
The <n> must be a valid index into the local variables of the current frame (§3.5).
The objectref on the top of the operand stack must be of type returnAddress or of
type reference. It is popped from the operand stack, and the value of the local
variable at <n> is set to objectref.
Notes
An astore_<n> instruction is used with an objectref of type returnAddress when
implementing Java’s finally keyword. An aload_<n> instruction cannot be used to
load a value of type returnAddress from a local variable onto the operand stack.
This asymmetry with the corresponding astore_<n> instruction is intentional.
Each of the aload_<n> instructions is the same as aload with an index of <n>, except
that the operand <n> is implicit.
150
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
athrow
athrow
Throw exception or error
Format
athrow
Forms
athrow = 147 (0x93)
Stack
…, objectref Þ
objectref
Description
The objectref must be of type reference and must refer to an object that is an
instance of class Throwable or of a subclass of Throwable. It is popped from the
operand stack. The objectref is then thrown by searching the current frame (§3.5) for
the most recent catch clause that catches the class of objectref or one of its
superclasses.
If a catch clause is found, it contains the location of the code intended to handle this
exception. The pc register is reset to that location, the operand stack of the current
frame is cleared, objectref is pushed back onto the operand stack, and execution
continues. If no appropriate clause is found in the current frame, that frame is
popped, the frame of its invoker is reinstated, and the objectref is rethrown.
If no catch clause is found that handles this exception, the virtual machine exits.
Runtime Exception
If objectref is null, athrow throws a NullPointerException instead of objectref.
Notes
In some circumstances, the athrow instruction may throw a SecurityException if
the current context (§3.4) is not the owning context (§3.4) of the object referenced by
objectref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 7
Java Card Virtual Machine Instruction Set
151
baload
baload
Load byte or boolean from array
Format
baload
Forms
baload = 37 (0x25)
Stack
…, arrayref, index Þ
…, value
Description
The arrayref must be of type reference and must refer to an array whose
components are of type byte or of type boolean. The index must be of type short.
Both arrayref and index are popped from the operand stack. The byte value in the
component of the array at index is retrieved, sign-extended to a short value, and
pushed onto the top of the operand stack.
Runtime Exceptions
If arrayref is null, baload throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
baload instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the baload instruction may throw a SecurityException if the
current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
152
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
bastore
bastore
Store into byte or boolean array
Format
bastore
Forms
bastore = 56 (0x38)
Stack
…, arrayref, index, value Þ
…
Description
The arrayref must be of type reference and must refer to an array whose
components are of type byte or of type boolean. The index and value must both be of
type short. The arrayref, index and value are popped from the operand stack. The
short value is truncated to a byte and stored as the component of the array indexed
by index.
Runtime Exceptions
If arrayref is null, bastore throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
bastore instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the bastore instruction may throw a SecurityException if
the current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 7
Java Card Virtual Machine Instruction Set
153
bipush
bipush
Push byte
Format
bipush
byte
Forms
bipush = 18 (0x12)
Stack
…Þ
…, value.word1, value.word2
Description
The immediate byte is sign-extended to an int, and the resulting value is pushed onto
the operand stack.
Notes
If a virtual machine does not support the int data type, the bipush instruction will
not be available.
154
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
bspush
bspush
Push byte
Format
bspush
byte
Forms
bspush = 16 (0x10)
Stack
…Þ
…, value
Description
The immediate byte is sign-extended to a short, and the resulting value is pushed
onto the operand stack.
Chapter 7
Java Card Virtual Machine Instruction Set
155
checkcast
checkcast
Check whether object is of given type
Format
checkcast
atype
indexbyte1
indexbyte2
Forms
checkcast = 148 (0x94)
Stack
…, objectref Þ
…, objectref
Description
The unsigned byte atype is a code that indicates if the type against which the object
is being checked is an array type or a class type. It must take one of the following
values or zero:
Array Type
atype
T_BOOLEAN
10
T_BYTE
11
T_SHORT
12
T_INT
13
T_REFERENCE
14
If the value of atype is 10, 11, 12, or 13, the values of the indexbyte1 and indexbyte2
must be zero, and the value of atype indicates the array type against which to check
the object. Otherwise the unsigned indexbyte1 and indexbyte2 are used to construct an
index into the constant pool of the current package (§3.5), where the value of the
index is (indexbyte1 << 8) | indexbyte2. The item at that index in the constant pool
must be of type CONSTANT_Classref (§6.7.1), a reference to a class or interface type.
The reference is resolved. If the value of atype is 14, the object is checked against an
array type that is an array of object references of the type of the resolved class. If the
value of atype is zero, the object is checked against a class or interface type that is the
resolved class.
The objectref must be of type reference. If objectref is null or can be cast to the
specified array type or the resolved class or interface type, the operand stack is
unchanged; otherwise the checkcast instruction throws a ClassCastException.
The following rules are used to determine whether an objectref that is not null can be
cast to the resolved type: if S is the class of the object referred to by objectref and T is
156
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
checkcast (cont.)
checkcast (cont.)
the resolved class, array or interface type, checkcast determines whether objectref can
be cast to type T as follows:
■
If S is a class type, then:
■
■
■
If T is an interface type, then S must implement interface T.
If S is an interface type1, then:
■
■
■
If T is a class type, then S must be the same class as T, or S must be a subclass
of T;
If T is a class type, then T must be Object (§2.2.2.4);
If T is an interface type, T must be the same interface as S or a superinterface of
S.
If S is an array type, namely the type SC[], that is, an array of components of type
SC, then:
■
■
If T is a class type, then T must be Object.
If T is an array type, namely the type TC[], an array of components of type TC,
then one of the following must be true:
■
TC and SC are the same primitive type (§3.1).
■
TC and SC are reference types2 (§3.1) with type SC assignable to TC, by these
rules.
■
If T is an interface type, T must be one of the interfaces implemented by arrays.
Runtime Exception
If objectref cannot be cast to the resolved class, array, or interface type, the checkcast
instruction throws a ClassCastException.
Notes
The checkcast instruction is fundamentally very similar to the instanceof instruction. It
differs in its treatment of null, its behavior when its test fails (checkcast throws an
exception, instanceof pushes a result code), and its effect on the operand stack.
In some circumstances, the checkcast instruction may throw a SecurityException if
the current context (§3.4) is not the owning context (§3.4) of the object referenced by
objectref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
1. When both S and T are arrays of reference types, this algorithm is applied recursively using the types of the
arrays, namely SC and TC. In the recursive call, S, which was SC in the original call, may be an interface type.
This rule can only be reached in this manner. Similarly, in the recursive call,T, which was TC in the original call,
may be an interface type.
2. This version of the Java Card Virtual Machine Specification does not support multi-dimensional arrays.
Therefore, neither SC or TC can be an array type.
Chapter 7
Java Card Virtual Machine Instruction Set
157
checkcast (cont.)
checkcast (cont.)
If a virtual machine does not support the int data type, the value of atype may not
be 13 (array type = T_INT).
158
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
dup
dup
Duplicate top operand stack word
Format
dup
Forms
dup = 61 (0x3d)
Stack
…, word Þ
…, word, word
Description
The top word on the operand stack is duplicated and pushed onto the operand stack.
The dup instruction must not be used unless word contains a 16-bit data type.
Notes
Except for restrictions preserving the integrity of 32-bit data types, the dup
instruction operates on an untyped word, ignoring the type of data it contains.
Chapter 7
Java Card Virtual Machine Instruction Set
159
dup_x
dup_x
Duplicate top operand stack words and insert below
Format
dup_x
mn
Forms
dup_x = 63 (0x3f)
Stack
…, wordN, …, wordM, …, word1 Þ
…, wordM, …, word1, wordN, …, wordM, …, word1
Description
The unsigned byte mn is used to construct two parameter values. The high nibble,
(mn & 0xf0) >> 4, is used as the value m. The low nibble, (mn & 0xf), is used as the
value n. Permissible values for m are 1 through 4. Permissible values for n are 0 and
m through m+4.
For positive values of n, the top m words on the operand stack are duplicated and
the copied words are inserted n words down in the operand stack. When n equals 0,
the top m words are copied and placed on top of the stack.
The dup_x instruction must not be used unless the ranges of words 1 through m and
words m+1 through n each contain either a 16-bit data type, two 16-bit data types, a
32-bit data type, a 16-bit data type and a 32-bit data type (in either order), or two 32bit data types.
Notes
Except for restrictions preserving the integrity of 32-bit data types, the dup_x
instruction operates on untyped words, ignoring the types of data they contain.
If a virtual machine does not support the int data type, the permissible values for m
are 1 or 2, and permissible values for n are 0 and m through m+2.
160
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
dup2
dup2
Duplicate top two operand stack words
Format
dup2
Forms
dup2 = 62 (0x3e)
Stack
…, word2, word1 Þ
…, word2, word1, word2, word1
Description
The top two words on the operand stack are duplicated and pushed onto the
operand stack, in the original order.
The dup2 instruction must not be used unless each of word1 and word2 is a word that
contains a 16-bit data type or both together are the two words of a single 32-bit
datum.
Notes
Except for restrictions preserving the integrity of 32-bit data types, the dup2
instruction operates on untyped words, ignoring the types of data they contain.
Chapter 7
Java Card Virtual Machine Instruction Set
161
getfield_<t>
getfield_<t>
Fetch field from object
Format
getfield_<t>
index
Forms
getfield_a = 131 (0x83)
getfield_b = 132 (0x84)
getfield_s = 133 (0x85)
getfield_i = 134 (0x86)
Stack
…, objectref Þ
…, value
OR
…, objectref Þ
…, value.word1, value.word2
Description
The objectref, which must be of type reference, is popped from the operand stack.
The unsigned index is used as an index into the constant pool of the current package
(§3.5). The constant pool item at the index must be of type
CONSTANT_InstanceFieldref (§6.7.2), a reference to a class and a field token.
The class of objectref must not be an array. If the field is protected, and it is a
member of a superclass of the current class, and the field is not declared in the same
package as the current class, then the class of objectref must be either the current class
or a subclass of the current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
162
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
getfield_<t> (cont.)
getfield_<t> (cont.)
The width of a field in a class instance is determined by the field type specified in
the instruction. The item is resolved, determining the field offset1. The value at that
offset into the class instance referenced by objectref is fetched. If the value is of type
byte or type boolean, it is sign-extended to a short. The value is pushed onto the
operand stack.
Runtime Exception
If objectref is null, the getfield_<t> instruction throws a NullPointerException.
Notes
In some circumstances, the getfield_<t> instruction may throw a SecurityException
if the current context (§3.4) is not the owning context (§3.4) of the object referenced
by objectref. The exact circumstances when the exception will be thrown are specified
in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
If a virtual machine does not support the int data type, the getfield_i instruction will
not be available.
1. The offset may be computed by adding the field token value to the size of an instance of the immediate
superclass. However, this method is not required by this specification. A Java Card virtual machine may
define any mapping from token value to offset into an instance.
Chapter 7
Java Card Virtual Machine Instruction Set
163
getfield_<t>_this
getfield_<t>_this
Fetch field from current object
Format
getfield_<t>_this
index
Forms
getfield_a_this = 173 (0xad)
getfield_b_this = 174 (0xae)
getfield_s_this = 175 (0xaf)
getfield_i_this = 176 (0xb0)
Stack
…Þ
…, value
OR
…Þ
…, value.word1, value.word2
Description
The currently executing method must be an instance method. The local variable at
index 0 must contain a reference objectref to the currently executing method’s this
parameter. The unsigned index is used as an index into the constant pool of the
current package (§3.5). The constant pool item at the index must be of type
CONSTANT_InstanceFieldref (§6.7.2), a reference to a class and a field token.
The class of objectref must not be an array. If the field is protected, and it is a
member of a superclass of the current class, and the field is not declared in the same
package as the current class, then the class of objectref must be either the current class
or a subclass of the current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
164
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
getfield_<t>_this (cont.)
getfield_<t>_this (cont.)
The width of a field in a class instance is determined by the field type specified in
the instruction. The item is resolved, determining the field offset1. The value at that
offset into the class instance referenced by objectref is fetched. If the value is of type
byte or type boolean, it is sign-extended to a short. The value is pushed onto the
operand stack.
Runtime Exception
If objectref is null, the getfield_<t>_this instruction throws a NullPointerException.
Notes
In some circumstances, the getfield_<t>_this instruction may throw a
SecurityException if the current context (§3.4) is not the owning context (§3.4) of
the object referenced by objectref. The exact circumstances when the exception will be
thrown are specified in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification.
If a virtual machine does not support the int data type, the getfield_i_this instruction
will not be available.
1. The offset may be computed by adding the field token value to the size of an instance of the immediate
superclass. However, this method is not required by this specification. A Java Card virtual machine may
define any mapping from token value to offset into an instance.
Chapter 7
Java Card Virtual Machine Instruction Set
165
getfield_<t>_w
getfield_<t>_w
Fetch field from object (wide index)
Format
getfield_<t>_w
indexbyte1
indexbyte2
Forms
getfield_a_w = 169 (0xa9)
getfield_b_w = 170 (0xaa)
getfield_s_w = 171 (0xab)
getfield_i_w = 172 (0xac)
Stack
…, objectref Þ
…, value
OR
…, objectref Þ
…, value.word1, value.word2
Description
The objectref, which must be of type reference, is popped from the operand stack.
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at the index must be of type
CONSTANT_InstanceFieldref (§6.7.2), a reference to a class and a field token. The
item must resolve to a field of type reference.
The class of objectref must not be an array. If the field is protected, and it is a
member of a superclass of the current class, and the field is not declared in the same
package as the current class, then the class of objectref must be either the current class
or a subclass of the current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
166
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
getfield_<t>_w (cont.)
getfield_<t>_w (cont.)
The width of a field in a class instance is determined by the field type specified in
the instruction. The item is resolved, determining the field offset1. The value at that
offset into the class instance referenced by objectref is fetched. If the value is of type
byte or type boolean, it is sign-extended to a short. The value is pushed onto the
operand stack.
Runtime Exception
If objectref is null, the getfield_<t>_w instruction throws a NullPointerException.
Notes
In some circumstances, the getfield_<t>_w instruction may throw a
SecurityException if the current context (§3.4) is not the owning context (§3.4) of
the object referenced by objectref. The exact circumstances when the exception will be
thrown are specified in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification.
If a virtual machine does not support the int data type, the getfield_i_w instruction
will not be available.
1. The offset may be computed by adding the field token value to the size of an instance of the immediate
superclass. However, this method is not required by this specification. A Java Card virtual machine may
define any mapping from token value to offset into an instance.
Chapter 7
Java Card Virtual Machine Instruction Set
167
getstatic_<t>
getstatic_<t>
Get static field from class
Format
getstatic_<t>
indexbyte1
indexbyte2
Forms
getstatic_a = 123 (0x7b)
getstatic_b = 124 (0x7c)
getstatic_s = 125 (0x7d)
getstatic_i = 126 (0x7e)
Stack
…Þ
…, value
OR
…Þ
…, value.word1, value.word2
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at the index must be of type
CONSTANT_StaticFieldref (§6.7.3), a reference to a static field.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
The width of a class field is determined by the field type specified in the instruction.
The item is resolved, determining the field offset. The item is resolved, determining
the class field. The value of the class field is fetched. If the value is of type byte or
boolean, it is sign-extended to a short. The value is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the getstatic_i instruction
will not be available.
168
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
goto
goto
Branch always
Format
goto
branch
Forms
goto = 112 (0x70)
Stack
No change
Description
The value branch is used as a signed 8-bit offset. Execution proceeds at that offset
from the address of the opcode of this goto instruction. The target address must be
that of an opcode of an instruction within the method that contains this goto
instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
169
goto_w
goto_w
Branch always (wide index)
Format
goto_w
branchbyte1
branchbyte2
Forms
goto_w = 168 (0xa8)
Stack
No change
Description
The unsigned bytes branchbyte1 and branchbyte2 are used to construct a signed 16-bit
branchoffset, where branchoffset is (branchbyte1 << 8) | branchbyte2. Execution proceeds
at that offset from the address of the opcode of this goto instruction. The target
address must be that of an opcode of an instruction within the method that contains
this goto instruction.
170
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
i2b
i2b
Convert int to byte
Format
i2b
Forms
i2b = 93 (0x5d)
Stack
…, value.word1, value.word2 Þ
…, result
Description
The value on top of the operand stack must be of type int. It is popped from the
operand stack and converted to a byte result by taking the low-order 16 bits of the
int value, and discarding the high-order 16 bits. The low-order word is truncated to
a byte, then sign-extended to a short result. The result is pushed onto the operand
stack.
Notes
The i2b instruction performs a narrowing primitive conversion. It may lose
information about the overall magnitude of value. The result may also not have the
same sign as value.
If a virtual machine does not support the int data type, the i2b instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
171
i2s
i2s
Convert int to short
Format
i2s
Forms
i2s = 94 (0x5e)
Stack
…, value.word1, value.word2 Þ
…, result
Description
The value on top of the operand stack must be of type int. It is popped from the
operand stack and converted to a short result by taking the low-order 16 bits of the
int value and discarding the high-order 16 bits. The result is pushed onto the
operand stack.
Notes
The i2s instruction performs a narrowing primitive conversion. It may lose
information about the overall magnitude of value. The result may also not have the
same sign as value.
If a virtual machine does not support the int data type, the i2s instruction will not
be available.
172
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
iadd
iadd
Add int
Format
iadd
Forms
iadd = 66 (0x42)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. The int result is value1 + value2. The result is pushed onto the operand stack.
If an iadd instruction overflows, then the result is the low-order bits of the true
mathematical result in a sufficiently wide two’s-complement format. If overflow
occurs, then the sign of the result may not be the same as the sign of the
mathematical sum of the two values.
Notes
If a virtual machine does not support the int data type, the iadd instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
173
iaload
iaload
Load int from array
Format
iaload
Forms
iaload = 39 (0x27)
Stack
…, arrayref, index Þ
…, value.word1, value.word2
Description
The arrayref must be of type reference and must refer to an array whose
components are of type int. The index must be of type short. Both arrayref and index
are popped from the operand stack. The int value in the component of the array at
index is retrieved and pushed onto the top of the operand stack.
Runtime Exceptions
If arrayref is null, iaload throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
iaload instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the iaload instruction may throw a SecurityException if the
current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
If a virtual machine does not support the int data type, the iaload instruction will
not be available.
174
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
iand
iand
Boolean AND int
Format
iand
Forms
iand = 84 (0x54)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. They are popped from the operand stack.
An int result is calculated by taking the bitwise AND (conjunction) of value1 and
value2. The result is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the iand instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
175
iastore
iastore
Store into int array
Format
iastore
Forms
iastore = 58 (0x3a)
Stack
…, arrayref, index, value.word1, value.word2 Þ
…
Description
The arrayref must be of type reference and must refer to an array whose
components are of type int. The index must be of type short and value must be of
type int. The arrayref, index and value are popped from the operand stack. The int
value is stored as the component of the array indexed by index.
Runtime Exception
If arrayref is null, iastore throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
iastore instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the iastore instruction may throw a SecurityException if the
current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
If a virtual machine does not support the int data type, the iastore instruction will
not be available.
176
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
icmp
icmp
Compare int
Format
icmp
Forms
icmp = 95 (0x5f)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result
Description
Both value1 and value2 must be of type int. They are both popped from the operand
stack, and a signed integer comparison is performed. If value1 is greater than value2,
the short value 1 is pushed onto the operand stack. If value1 is equal to value2, the
short value 0 is pushed onto the operand stack. If value1 is less than value2, the
short value –1 is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the icmp instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
177
iconst_<i>
iconst_<i>
Push int constant
Format
iconst_<i>
Forms
iconst_m1 = 10 (0x09)
iconst_0 = 11 (0xa)
iconst_1 = 12 (0xb)
iconst_2 = 13 (0xc)
iconst_3 = 14 (0xd)
iconst_4 = 15 (0xe)
iconst_5 = 16 (0xf)
Stack
…Þ
…, <i>.word1, <i>.word2
Description
Push the int constant <i> (-1, 0, 1, 2, 3, 4, or 5) onto the operand stack.
Notes
If a virtual machine does not support the int data type, the iconst_<i> instruction
will not be available.
178
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
idiv
idiv
Divide int
Format
idiv
Forms
idiv = 72 (0x48)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. The int result is the value of the Java expression value1 / value2. The result is
pushed onto the operand stack.
An int division rounds towards 0; that is, the quotient produced for int values in n/
d is an int value q whose magnitude is as large as possible while satisfying | d · q |
<= | n |. Moreover, q is a positive when | n | >= | d | and n and d have the same
sign, but q is negative when | n | >= | d | and n and d have opposite signs.
There is one special case that does not satisfy this rule: if the dividend is the negative
integer of the largest possible magnitude for the int type, and the divisor is –1, then
overflow occurs, and the result is equal to the dividend. Despite the overflow, no
exception is thrown in this case.
Runtime Exception
If the value of the divisor in an int division is 0, idiv throws an
ArithmeticException.
Notes
If a virtual machine does not support the int data type, the idiv instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
179
if_acmp<cond>
if_acmp<cond>
Branch if reference comparison succeeds
Format
if_acmp<cond>
branch
Forms
if_acmpeq = 104 (0x68)
if_acmpne = 105 (0x69)
Stack
…, value1, value2 Þ
…
Description
Both value1 and value2 must be of type reference. They are both popped from the
operand stack and compared. The results of the comparisons are as follows:
· eq succeeds if and only if value1 = value2
·
ne succeeds if and only if value1 ¹ value2
If the comparison succeeds, branch is used as signed 8-bit offset, and execution
proceeds at that offset from the address of the opcode of this if_acmp<cond>
instruction. The target address must be that of an opcode of an instruction within the
method that contains this if_acmp<cond> instruction.
Otherwise, execution proceeds at the address of the instruction following this
if_acmp<cond> instruction.
180
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
if_acmp<cond>_w
if_acmp<cond>_w
Branch if reference comparison succeeds (wide index)
Format
if_acmp<cond>_w
branchbyte1
branchbyte2
Forms
if_acmpeq_w = 160 (0xa0)
if_acmpne_w = 161 (0xa1)
Stack
…, value1, value2 Þ
…
Description
Both value1 and value2 must be of type reference. They are both popped from the
operand stack and compared. The results of the comparisons are as follows:
· eq succeeds if and only if value1 = value2
·
ne succeeds if and only if value1 ¹ value2
If the comparison succeeds, the unsigned bytes branchbyte1 and branchbyte2 are used
to construct a signed 16-bit branchoffset, where branchoffset is (branchbyte1 << 8) |
branchbyte2. Execution proceeds at that offset from the address of the opcode of this
if_acmp<cond>_w instruction. The target address must be that of an opcode of an
instruction within the method that contains this if_acmp<cond>_w instruction.
Otherwise, execution proceeds at the address of the instruction following this
if_acmp<cond>_w instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
181
if_scmp<cond>
if_scmp<cond>
Branch if short comparison succeeds
Format
if_scmp<cond>
branch
Forms
if_scmpeq = 106 (0x6a)
if_scmpne = 107 (0x6b)
if_scmplt = 108 (0x6c)
if_scmpge = 109 (0x6d)
if_scmpgt = 110 (0x6e)
if_scmple = 111 (0x6f)
Stack
…, value1, value2 Þ
…
Description
Both value1 and value2 must be of type short. They are both popped from the
operand stack and compared. All comparisons are signed. The results of the
comparisons are as follows:
· eq succeeds if and only if value1 = value2
·
ne succeeds if and only if value1 ¹ value2
·
lt succeeds if and only if value1 < value2
·
le succeeds if and only if value1 £ value2
·
gt succeeds if and only if value1 > value2
·
ge succeeds if and only if value1 ³ value2
If the comparison succeeds, branch is used as signed 8-bit offset, and execution
proceeds at that offset from the address of the opcode of this if_scmp<cond>
instruction. The target address must be that of an opcode of an instruction within the
method that contains this if_scmp<cond> instruction.
Otherwise, execution proceeds at the address of the instruction following this
if_scmp<cond> instruction.
182
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
if_scmp<cond>_w
if_scmp<cond>_w
Branch if short comparison succeeds (wide index)
Format
if_scmp<cond>_w
branchbyte1
branchbyte2
Forms
if_scmpeq_w = 162 (0xa2)
if_scmpne_w = 163 (0xa3)
if_scmplt_w = 164 (0xa4)
if_scmpge_w = 165 (0xa5)
if_scmpgt_w = 166 (0xa6)
if_scmple_w = 167 (0xa7)
Stack
…, value1, value2 Þ
…
Description
Both value1 and value2 must be of type short. They are both popped from the
operand stack and compared. All comparisons are signed. The results of the
comparisons are as follows:
· eq succeeds if and only if value1 = value2
·
ne succeeds if and only if value1 ¹ value2
·
lt succeeds if and only if value1 < value2
·
le succeeds if and only if value1 £ value2
·
gt succeeds if and only if value1 > value2
·
ge succeeds if and only if value1 ³ value2
If the comparison succeeds, the unsigned bytes branchbyte1 and branchbyte2 are used
to construct a signed 16-bit branchoffset, where branchoffset is (branchbyte1 << 8) |
branchbyte2. Execution proceeds at that offset from the address of the opcode of this
if_scmp<cond>_w instruction. The target address must be that of an opcode of an
instruction within the method that contains this if_scmp<cond>_w instruction.
Otherwise, execution proceeds at the address of the instruction following this
if_scmp<cond>_w instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
183
if<cond>
if<cond>
Branch if short comparison with zero succeeds
Format
if<cond>
branch
Forms
ifeq = 96 (0x60)
ifne = 97 (0x61)
iflt = 98 (0x62)
ifge = 99 (0x63)
ifgt = 100 (0x64)
ifle = 101 (0x65)
Stack
…, value Þ
…
Description
The value must be of type short. It is popped from the operand stack and compared
against zero. All comparisons are signed. The results of the comparisons are as
follows:
· eq succeeds if and only if value = 0
·
ne succeeds if and only if value ¹ 0
·
lt succeeds if and only if value < 0
·
le succeeds if and only if value £ 0
·
gt succeeds if and only if value > 0
·
ge succeeds if and only if value ³ 0
If the comparison succeeds, branch is used as signed 8-bit offset, and execution
proceeds at that offset from the address of the opcode of this if<cond> instruction.
The target address must be that of an opcode of an instruction within the method
that contains this if<cond> instruction.
Otherwise, execution proceeds at the address of the instruction following this
if<cond> instruction.
184
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
if<cond>_w
if<cond>_w
Branch if short comparison with zero succeeds (wide index)
Format
if<cond>_w
branchbyte1
branchbyte2
Forms
ifeq_w = 152 (0x98)
ifne_w = 153 (0x99)
iflt_w = 154 (0x9a)
ifge_w = 155 (0x9b)
ifgt_w = 156 (0x9c)
ifle_w = 157 (0x9d)
Stack
…, value Þ
…
Description
The value must be of type short. It is popped from the operand stack and compared
against zero. All comparisons are signed. The results of the comparisons are as
follows:
· eq succeeds if and only if value = 0
·
ne succeeds if and only if value ¹ 0
·
lt succeeds if and only if value < 0
·
le succeeds if and only if value £ 0
·
gt succeeds if and only if value > 0
·
ge succeeds if and only if value ³ 0
If the comparison succeeds, the unsigned bytes branchbyte1 and branchbyte2 are used
to construct a signed 16-bit branchoffset, where branchoffset is (branchbyte1 << 8) |
branchbyte2. Execution proceeds at that offset from the address of the opcode of this
if<cond>_w instruction. The target address must be that of an opcode of an
instruction within the method that contains this if<cond>_w instruction.
Otherwise, execution proceeds at the address of the instruction following this
if<cond>_w instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
185
ifnonnull
ifnonnull
Branch if reference not null
Format
ifnonnull
branch
Forms
ifnonnull = 103 (0x67)
Stack
…, value Þ
…
Description
The value must be of type reference. It is popped from the operand stack. If the
value is not null, branch is used as signed 8-bit offset, and execution proceeds at that
offset from the address of the opcode of this ifnonnull instruction. The target address
must be that of an opcode of an instruction within the method that contains this
ifnonnull instruction.
Otherwise, execution proceeds at the address of the instruction following this
ifnonnull instruction.
186
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
ifnonnull_w
ifnonnull_w
Branch if reference not null (wide index)
Format
ifnonnull_w
branchbyte1
branchbyte2
Forms
ifnonnull_w = 159 (0x9f)
Stack
…, value Þ
…
Description
The value must be of type reference. It is popped from the operand stack. If the
value is not null, the unsigned bytes branchbyte1 and branchbyte2 are used to
construct a signed 16-bit branchoffset, where branchoffset is (branchbyte1 << 8) |
branchbyte2. Execution proceeds at that offset from the address of the opcode of this
ifnonnull_w instruction. The target address must be that of an opcode of an
instruction within the method that contains this ifnonnull_w instruction.
Otherwise, execution proceeds at the address of the instruction following this
ifnonnull_w instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
187
ifnull
ifnull
Branch if reference is null
Format
ifnull
branch
Forms
ifnull = 102 (0x66)
Stack
…, value Þ
…
Description
The value must be of type reference. It is popped from the operand stack. If the
value is null, branch is used as signed 8-bit offset, and execution proceeds at that
offset from the address of the opcode of this ifnull instruction. The target address
must be that of an opcode of an instruction within the method that contains this
ifnull instruction.
Otherwise, execution proceeds at the address of the instruction following this ifnull
instruction.
188
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
ifnull_w
ifnull_w
Branch if reference is null (wide index)
Format
ifnull_w
branchbyte1
branchbyte2
Forms
ifnull_w = 158 (0x9e)
Stack
…, value Þ
…
Description
The value must be of type reference. It is popped from the operand stack. If the
value is null, the unsigned bytes branchbyte1 and branchbyte2 are used to construct a
signed 16-bit branchoffset, where branchoffset is (branchbyte1 << 8) | branchbyte2.
Execution proceeds at that offset from the address of the opcode of this ifnull_w
instruction. The target address must be that of an opcode of an instruction within the
method that contains this ifnull_w instruction.
Otherwise, execution proceeds at the address of the instruction following this
ifnull_w instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
189
iinc
iinc
Increment local int variable by constant
Format
iinc
index
const
Forms
iinc = 90 (0x5a)
Stack
No change
Description
The index is an unsigned byte. Both index and index + 1 must be valid indices into the
local variables of the current frame (§3.5). The local variables at index and index + 1
together must contain an int. The const is an immediate signed byte. The value const
is first sign-extended to an int, then the int contained in the local variables at index
and index + 1 is incremented by that amount.
Notes
If a virtual machine does not support the int data type, the iinc instruction will not
be available.
190
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
iinc_w
iinc_w
Increment local int variable by constant
Format
iinc_w
index
byte1
byte2
Forms
iinc_w = 151 (0x97)
Stack
No change
Description
The index is an unsigned byte. Both index and index + 1 must be valid indices into the
local variables of the current frame (§3.5). The local variables at index and index + 1
together must contain an int. The immediate unsigned byte1 and byte2 values are
assembled into an intermediate short where the value of the short is (byte1 << 8) |
byte2. The intermediate value is then sign-extended to an int const. The int
contained in the local variables at index and index + 1 is incremented by const.
Notes
If a virtual machine does not support the int data type, the iinc_w instruction will
not be available.
Chapter 7
Java Card Virtual Machine Instruction Set
191
iipush
iipush
Push int
Format
iipush
byte1
byte2
byte3
byte4
Forms
iipush = 20 (0x14)
Stack
…Þ
…, value1.word1, value1.word2
Description
The immediate unsigned byte1, byte2, byte3, and byte4 values are assembled into a
signed int where the value of the int is (byte1 << 24) | (byte2 << 16) | (byte3 << 8) |
byte4. The resulting value is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the iipush instruction will
not be available.
192
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
iload
iload
Load int from local variable
Format
iload
index
Forms
iload = 23 (0x17)
Stack
…Þ
…, value1.word1, value1.word2
Description
The index is an unsigned byte. Both index and index + 1 must be valid indices into the
local variables of the current frame (§3.5). The local variables at index and index + 1
together must contain an int. The value of the local variables at index and index + 1 is
pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the iload instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
193
iload_<n>
iload_<n>
Load int from local variable
Format
iload_<n>
Forms
iload_0 = 32 (0x20)
iload_1 = 33 (0x21)
iload_2 = 34 (0x22)
iload_3 = 35 (0x23)
Stack
…Þ
…, value1.word1, value1.word2
Description
Both <n> and <n> + 1 must be a valid indices into the local variables of the current
frame (§3.5). The local variables at <n> and <n> + 1 together must contain an int.
The value of the local variables at <n> and <n> + 1 is pushed onto the operand stack.
Notes
Each of the iload_<n> instructions is the same as iload with an index of <n>, except
that the operand <n> is implicit.
If a virtual machine does not support the int data type, the iload_<n> instruction
will not be available.
194
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
ilookupswitch
ilookupswitch
Access jump table by key match and jump
Format
ilookupswitch
defaultbyte1
defaultbyte2
npairs1
npairs2
match-offset pairs…
Pair Format
matchbyte1
matchbyte2
matchbyte3
matchbyte4
offsetbyte1
offsetbyte2
Forms
ilookupswitch = 118 (0x76)
Stack
…, key.word1, key.word2 Þ
…
Description
An ilookupswitch instruction is a variable-length instruction. Immediately after the
ilookupswitch opcode follow a signed 16-bit value default, an unsigned 16-bit value
npairs, and then npairs pairs. Each pair consists of an int match and a signed 16-bit
offset. Each match is constructed from four unsigned bytes as (matchbyte1 << 24) |
(matchbyte2 << 16) | (matchbyte3 << 8) | matchbyte4. Each offset is constructed from
two unsigned bytes as (offsetbyte1 << 8) | offsetbyte2.
The table match-offset pairs of the ilookupswitch instruction must be sorted in
increasing numerical order by match.
The key must be of type int and is popped from the operand stack and compared
against the match values. If it is equal to one of them, then a target address is
calculated by adding the corresponding offset to the address of the opcode of this
ilookupswitch instruction. If the key does not match any of the match values, the target
address is calculated by adding default to the address of the opcode of this
ilookupswitch instruction. Execution then continues at the target address.
Chapter 7
Java Card Virtual Machine Instruction Set
195
ilookupswitch (cont.)
ilookupswitch (cont.)
The target address that can be calculated from the offset of each match-offset pair, as
well as the one calculated from default, must be the address of an opcode of an
instruction within the method that contains this ilookupswitch instruction.
Notes
The match-offset pairs are sorted to support lookup routines that are quicker than
linear search.
If a virtual machine does not support the int data type, the ilookupswitch instruction
will not be available.
196
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
imul
imul
Multiply int
Format
imul
Forms
imul = 70 (0x46)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. The int result is value1 * value2. The result is pushed onto the operand stack.
If an imul instruction overflows, then the result is the low-order bits of the
mathematical product as an int. If overflow occurs, then the sign of the result may
not be the same as the sign of the mathematical product of the two values.
Notes
If a virtual machine does not support the int data type, the imul instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
197
ineg
ineg
Negate int
Format
ineg
Forms
ineg = 76 (0x4c)
Stack
…, value.word1, value.word2 Þ
…, result.word1, result.word2
Description
The value must be of type int. It is popped from the operand stack. The int result is
the arithmetic negation of value, -value. The result is pushed onto the operand stack.
For int values, negation is the same as subtraction from zero. Because the Java Card
virtual machine uses two’s-complement representation for integers and the range of
two’s-complement values is not symmetric, the negation of the maximum negative
int results in that same maximum negative number. Despite the fact that overflow
has occurred, no exception is thrown.
For all int values x, -x equals (~x) + 1.
Notes
If a virtual machine does not support the int data type, the ineg instruction will not
be available.
198
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
instanceof
instanceof
Determine if object is of given type
Format
instanceof
atype
indexbyte1
indexbyte2
Forms
instanceof = 149 (0x95)
Stack
…, objectref Þ
…, result
Description
The unsigned byte atype is a code that indicates if the type against which the object
is being checked is an array type or a class type. It must take one of the following
values or zero:
Array Type
atype
T_BOOLEAN
10
T_BYTE
11
T_SHORT
12
T_INT
13
T_REFERENCE
14
If the value of atype is 10, 11, 12, or 13, the values of the indexbyte1 and indexbyte2
must be zero, and the value of atype indicates the array type against which to check
the object. Otherwise the unsigned indexbyte1 and indexbyte2 are used to construct an
index into the constant pool of the current package (§3.5), where the value of the
index is (indexbyte1 << 8) | indexbyte2. The item at that index in the constant pool
must be of type CONSTANT_Classref (§6.7.1), a reference to a class or interface type.
The reference is resolved. If the value of atype is 14, the object is checked against an
array type that is an array of object references of the type of the resolved class. If the
value of atype is zero, the object is checked against a class or interface type that is the
resolved class.
The objectref must be of type reference. It is popped from the operand stack. If
objectref is not null and is an instance of the resolved class, array or interface, the
instanceof instruction pushes a short result of 1 on the operand stack. Otherwise it
pushes a short result of 0.
Chapter 7
Java Card Virtual Machine Instruction Set
199
instanceof (cont.)
instanceof (cont.)
The following rules are used to determine whether an objectref that is not null is an
instance of the resolved type: if S is the class of the object referred to by objectref and
T is the resolved class, array or interface type, instanceof determines whether objectref
is an instance of T as follows:
■
If S is a class type, then:
■
■
■
If T is an interface type, then S must implement interface T.
If S is an interface type1, then:
■
■
■
If T is a class type, then S must be the same class as T, or S must be a subclass
of T;
If T is a class type, then T must be Object (§2.2.2.4);
If T is an interface type, T must be the same interface as S or a superinterface of
S.
If S is an array type, namely the type SC[], that is, an array of components of type
SC, then:
■
■
If T is a class type, then T must be Object.
If T is an array type, namely the type TC[], an array of components of type TC,
then one of the following must be true:
■
TC and SC are the same primitive type (§3.1).
■
TC and SC are reference types2 (§3.1) with type SC assignable to TC, by these
rules.
■
If T is an interface type, T must be one of the interfaces implemented by arrays.
Notes
The instanceof instruction is fundamentally very similar to the checkcast instruction. It
differs in its treatment of null, its behavior when its test fails (checkcast throws an
exception, instanceof pushes a result code), and its effect on the operand stack.
In some circumstances, the instanceof instruction may throw a SecurityException if
the current context (§3.4) is not the owning context (§3.4) of the object referenced by
objectref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
If a virtual machine does not support the int data type, the value of atype may not
be 13 (array type = T_INT).
1. When both S and T are arrays of reference types, this algorithm is applied recursively using the types of the
arrays, namely SC and TC. In the recursive call, S, which was SC in the original call, may be an interface type.
This rule can only be reached in this manner. Similarly, in the recursive call,T, which was TC in the original call,
may be an interface type.
2. This version of the Java Card Virtual Machine Specification does not support multi-dimensional arrays.
Therefore, neither SC or TC can be an array type.
200
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
invokeinterface
invokeinterface
Invoke interface method
Format
invokeinterface
nargs
indexbyte1
indexbyte2
method
Forms
invokeinterface = 142 (0x8e)
Stack
…, objectref, [arg1, [arg2 …]] Þ
…
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at that index must be of type
CONSTANT_Classref (§6.7.1), a reference to an interface class. The specified interface
is resolved.
The nargs operand is an unsigned byte that must not be zero.
The method operand is an unsigned byte that is the interface method token for the
method to be invoked. The interface method must not be <init> or an instance
initialization method.
The objectref must be of type reference and must be followed on the operand stack
by nargs – 1 words of arguments. The number of words of arguments and the type
and order of the values they represent must be consistent with those of the selected
interface method.
The interface table of the class of the type of objectref is determined. If objectref is an
array type, then the interface table of class Object (§2.2.2.4) is used. The interface
table is searched for the resolved interface. The result of the search is a table that is
used to map the method token to a index.
The index is an unsigned byte that is used as an index into the method table of the
class of the type of objectref. If the objectref is an array type, then the method table of
class Object is used. The table entry at that index includes a direct reference to the
method’s code and modifier information.
Chapter 7
Java Card Virtual Machine Instruction Set
201
The nargs – 1 words of arguments and objectref are popped from the operand stack. A
new stack frame is created for the method being invoked, and objectref and the
arguments are made the values of its first nargs words of local variables, with
objectref in local variable 0, arg1 in local variable 1, and so on. The new stack frame is
then made current, and the Java Card virtual machine pc is set to the opcode of the
first instruction of the method to be invoked. Execution continues with the first
instruction of the method.
Runtime Exception
If objectref is null, the invokeinterface instruction throws a NullPointerException.
Notes
In some circumstances, the invokeinterface instruction may throw a
SecurityException if the current context (§3.4) is not the context (§3.4) of the object
referenced by objectref. The exact circumstances when the exception will be thrown
are specified in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification. If the current context is not the object’s context and the JCRE permits
invocation of the method, the invokeinterface instruction will cause a context switch
(§3.4) to the object’s context before invoking the method, and will cause a return
context switch to the previous context when the invoked method returns.
202
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
invokespecial
invokespecial
Invoke instance method; special handling for superclass, private, and instance
initialization method invocations
Format
invokespecial
indexbyte1
indexbyte2
Forms
invokespecial = 140 (0x8c)
Stack
…, objectref, [arg1, [arg2 …]] Þ
…
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. If the invoked method is a private instance method or
an instance initialization method, the constant pool item at index must be of type
CONSTANT_StaticMethodref (§6.7.3), a reference to a statically linked instance
method. If the invoked method is a superclass method, the constant pool item at
index must be of type CONSTANT_SuperMethodref (§6.7.2), a reference to an instance
method of a specified class. The reference is resolved. The resolved method must not
be <clinit>, a class or interface initialization method. If the method is <init>, an
instance initialization method, then the method must only be invoked once on an
uninitialized object, and before the first backward branch following the execution of
the new instruction that allocated the object. Finally, if the resolved method is
protected, and it is a member of a superclass of the current class, and the method is
not declared in the same package as the current class, then the class of objectref must
be either the current class or a subclass of the current class.
The resolved method includes the code for the method, an unsigned byte nargs that
must not be zero, and the method’s modifier information.
The objectref must be of type reference, and must be followed on the operand stack
by nargs – 1 words of arguments, where the number of words of arguments and the
type and order of the values they represent must be consistent with those of the
selected instance method.
The nargs – 1 words of arguments and objectref are popped from the operand stack. A
new stack frame is created for the method being invoked, and objectref and the
arguments are made the values of its first nargs words of local variables, with
objectref in local variable 0, arg1 in local variable 1, and so on. The new stack frame is
Chapter 7
Java Card Virtual Machine Instruction Set
203
invokespecial (cont.)
invokespecial (cont.)
then made current, and the Java Card virtual machine pc is set to the opcode of the
first instruction of the method to be invoked. Execution continues with the first
instruction of the method.
Runtime Exception
If objectref is null, the invokespecial instruction throws a NullPointerException.
204
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
invokestatic
invokestatic
Invoke a class (static) method
Format
invokestatic
indexbyte1
indexbyte2
Forms
invokestatic = 141 (0x8d)
Stack
…, [arg1, [arg2 …]] Þ
…
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at that index must be of type
CONSTANT_StaticMethodref (§6.7.3), a reference to a static method. The method
must not be <init>, an instance initialization method, or <clinit>, a class or
interface initialization method. It must be static, and therefore cannot be
abstract.
The resolved method includes the code for the method, an unsigned byte nargs that
may be zero, and the method’s modifier information.
The operand stack must contain nargs words of arguments, where the number of
words of arguments and the type and order of the values they represent must be
consistent with those of the resolved method .
The nargs words of arguments are popped from the operand stack. A new stack
frame is created for the method being invoked, and the words of arguments are
made the values of its first nargs words of local variables, with arg1 in local variable
0, arg2 in local variable 1, and so on. The new stack frame is then made current, and
the Java Card virtual machine pc is set to the opcode of the first instruction of the
method to be invoked. Execution continues with the first instruction of the method.
Chapter 7
Java Card Virtual Machine Instruction Set
205
invokevirtual
invokevirtual
Invoke instance method; dispatch based on class
Format
invokevirtual
indexbyte1
indexbyte2
Forms
invokevirtual = 139 (0x8b)
Stack
…, objectref, [arg1, [arg2 …]] Þ
…
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at that index must be of type
CONSTANT_VirtualMethodref (§6.7.2), a reference to a class and a virtual method
token. The specified method is resolved. The method must not be <init>, an
instance initialization method, or <clinit>, a class or interface initialization
method. Finally, if the resolved method is protected, and it is a member of a
superclass of the current class, and the method is not declared in the same package
as the current class, then the class of objectref must be either the current class or a
subclass of the current class.
The resolved method reference includes an unsigned index into the method table of
the resolved class and an unsigned byte nargs that must not be zero.
The objectref must be of type reference. The index is an unsigned byte that is used as
an index into the method table of the class of the type of objectref. If the objectref is an
array type, then the method table of class Object (§2.2.2.4) is used. The table entry at
that index includes a direct reference to the method’s code and modifier information.
The objectref must be followed on the operand stack by nargs – 1 words of arguments,
where the number of words of arguments and the type and order of the values they
represent must be consistent with those of the selected instance method.
The nargs – 1 words of arguments and objectref are popped from the operand stack. A
new stack frame is created for the method being invoked, and objectref and the
arguments are made the values of its first nargs words of local variables, with
objectref in local variable 0, arg1 in local variable 1, and so on. The new stack frame is
then made current, and the Java Card virtual machine pc is set to the opcode of the
first instruction of the method to be invoked. Execution continues with the first
instruction of the method.
206
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Runtime Exception
If objectref is null, the invokevirtual instruction throws a NullPointerException.
In some circumstances, the invokevirtual instruction may throw a
SecurityException if the current context (§3.4) is not the context (§3.4) of the object
referenced by objectref. The exact circumstances when the exception will be thrown
are specified in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification. If the current context is not the object’s context and the JCRE permits
invocation of the method, the invokevirtual instruction will cause a context switch
(§3.4) to the object’s context before invoking the method, and will cause a return
context switch to the previous context when the invoked method returns.
Chapter 7
Java Card Virtual Machine Instruction Set
207
ior
ior
Boolean OR int
Format
ior
Forms
ior = 86 (0x56)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. An int result is calculated by taking the bitwise inclusive OR of value1 and
value2. The result is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the ior instruction will not
be available.
208
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
irem
irem
Remainder int
Format
irem
Forms
irem = 74 (0x4a)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. The int result is the value of the Java expression value1 – (value1 / value2) *
value2. The result is pushed onto the operand stack.
The result of the irem instruction is such that (a/b)*b + (a%b) is equal to a. This
identity holds even in the special case that the dividend is the negative int of largest
possible magnitude for its type and the divisor is –1 (the remainder is 0). It follows
from this rule that the result of the remainder operation can be negative only if the
dividend is negative and can be positive only if the dividend is positive. Moreover,
the magnitude of the result is always less than the magnitude of the divisor.
Runtime Exception
If the value of the divisor for a short remainder operator is 0, irem throws an
ArithmeticException.
Notes
If a virtual machine does not support the int data type, the irem instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
209
ireturn
ireturn
Return int from method
Format
ireturn
Forms
ireturn = 121 (0x79)
Stack
…, value.word1, value.word2 Þ
[empty]
Description
The value must be of type int. It is popped from the operand stack of the current
frame (§3.5) and pushed onto the operand stack of the frame of the invoker. Any
other values on the operand stack of the current method are discarded.
The virtual machine then reinstates the frame of the invoker and returns control to
the invoker.
Notes
If a virtual machine does not support the int data type, the ireturn instruction will
not be available.
210
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
ishl
ishl
Shift left int
Format
ishl
Forms
ishl = 78 (0x4e)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. An int result is calculated by shifting value1 left by s bit positions, where s is
the value of the low five bits of value2. The result is pushed onto the operand stack.
Notes
This is equivalent (even if overflow occurs) to multiplication by 2 to the power s. The
shift distance actually used is always in the range 0 to 31, inclusive, as if value2 were
subjected to a bitwise logical AND with the mask value 0x1f.
If a virtual machine does not support the int data type, the ishl instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
211
ishr
ishr
Arithmetic shift right int
Format
ishr
Forms
ishr = 80 (0x50)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. An int result is calculated by shifting value1 right by s bit positions, with sign
extension, where s is the value of the low five bits of value2. The result is pushed onto
the operand stack.
Notes
The resulting value is ë(value1) / 2sû, where s is value2 & 0x1f. For nonnegative value1,
this is equivalent (even if overflow occurs) to truncating int division by 2 to the
power s. The shift distance actually used is always in the range 0 to 31, inclusive, as
if value2 were subjected to a bitwise logical AND with the mask value 0x1f.
Notes
If a virtual machine does not support the int data type, the ishr instruction will not
be available.
212
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
istore
istore
Store int into local variable
Format
istore
index
Forms
istore = 42 (0x2a)
Stack
…, value.word1, value.word2 Þ
…
Description
The index is an unsigned byte. Both index and index + 1 must be a valid index into the
local variables of the current frame (§3.5). The value on top of the operand stack must
be of type int. It is popped from the operand stack, and the local variables at index
and index + 1 are set to value.
Notes
If a virtual machine does not support the int data type, the istore instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
213
istore_<n>
istore_<n>
Store int into local variable
Format
istore_<n>
Forms
istore_0 = 51
istore_1 = 52
istore_2 = 53
istore_3 = 54
(0x33)
(0x34)
(0x35)
(0x36)
Stack
…, value.word1, value.word2 Þ
…
Description
Both <n> and <n> + 1 must be a valid indices into the local variables of the current
frame (§3.5). The value on top of the operand stack must be of type int. It is popped
from the operand stack, and the local variables at index and index + 1 are set to value.
Notes
If a virtual machine does not support the int data type, the istore_<n> instruction
will not be available.
214
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
isub
isub
Subtract int
Format
isub
Forms
isub = 68 (0x44)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. The int result is value1 - value2. The result is pushed onto the operand stack.
For int subtraction, a – b produces the same result as a + (–b). For int values,
subtraction from zeros is the same as negation.
Despite the fact that overflow or underflow may occur, in which case the result may
have a different sign than the true mathematical result, execution of an isub
instruction never throws a runtime exception.
Notes
If a virtual machine does not support the int data type, the isub instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
215
itableswitch
itableswitch
Access jump table by int index and jump
Format
itableswitch
defaultbyte1
defaultbyte2
lowbyte1
lowbyte2
lowbyte3
lowbyte4
highbyte1
highbyte2
highbyte3
highbyte4
jump offsets…
Offset Format
offsetbyte1
offsetbyte2
Forms
itableswitch = 116 (0x74)
Stack
…, index Þ
…
Description
An itableswitch instruction is a variable-length instruction. Immediately after the
itableswitch opcode follow a signed 16-bit value default, a signed 32-bit value low, a
signed 32-bit value high, and then high – low + 1 further signed 16-bit offsets. The
value low must be less than or equal to high. The high – low + 1 signed 16-bit offsets
are treated as a 0-based jump table. Each of the signed 16-bit values is constructed
from two unsigned bytes as (byte1 << 8) | byte2. Each of the signed 32-bit values is
constructed from four unsigned bytes as (byte1 << 24) | (byte2 << 16) | (byte3 << 8) |
byte4.
The index must be of type int and is popped from the stack. If index is less than low
or index is greater than high, then a target address is calculated by adding default to
the address of the opcode of this itableswitch instruction. Otherwise, the offset at
position index – low of the jump table is extracted. The target address is calculated by
adding that offset to the address of the opcode of this itableswitch instruction.
Execution then continues at the target address.
216
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
itableswitch (cont.)
itableswitch (cont.)
The target addresses that can be calculated from each jump table offset, as well as
the one calculated from default, must be the address of an opcode of an instruction
within the method that contains this itableswitch instruction.
Notes
If a virtual machine does not support the int data type, the itableswitch instruction
will not be available.
Chapter 7
Java Card Virtual Machine Instruction Set
217
iushr
iushr
Logical shift right int
Format
iushr
Forms
iushr = 82 (0x52)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. An int result is calculated by shifting the result right by s bit positions, with
zero extension, where s is the value of the low five bits of value2. The result is pushed
onto the operand stack.
Notes
If value1 is positive and s is value2 & 0x1f, the result is the same as that of value1 >> s;
if value1 is negative, the result is equal to the value of the expression (value1 >> s) +
(2 << ~s). The addition of the (2 << ~s) term cancels out the propagated sign bit. The
shift distance actually used is always in the range 0 to 31, inclusive, as if value2 were
subjected to a bitwise logical AND with the mask value 0x1f.
If a virtual machine does not support the int data type, the iushr instruction will not
be available.
218
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
ixor
ixor
Boolean XOR int
Format
ixor
Forms
ixor = 88 (0x58)
Stack
…, value1.word1, value1.word2, value2.word1, value2.word2 Þ
…, result.word1, result.word2
Description
Both value1 and value2 must be of type int. The values are popped from the operand
stack. An int result is calculated by taking the bitwise exclusive OR of value1 and
value2. The result is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the ixor instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
219
jsr
jsr
Jump subroutine
Format
jsr
branchbyte1
branchbyte2
Forms
jsr = 113 (0x71)
Stack
…Þ
…, address
Description
The address of the opcode of the instruction immediately following this jsr instruction
is pushed onto the operand stack as a value of type returnAddress. The unsigned
branchbyte1 and branchbyte2 are used to construct a signed 16-bit offset, where the
offset is (branchbyte1 << 8) | branchbyte2. Execution proceeds at that offset from the
address of this jsr instruction. The target address must be that of an opcode of an
instruction within the method that contains this jsr instruction.
Notes
The jsr instruction is used with the ret instruction in the implementation of the
finally clause of the Java language. Note that jsr pushes the address onto the stack
and ret gets it out of a local variable. This asymmetry is intentional.
220
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
new
new
Create new object
Format
new
indexbyte1
indexbyte2
Forms
new = 143 (0x8f)
Stack
…Þ
…, objectref
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The item at that index in the constant pool must be of
type CONSTANT_Classref (§6.7.1), a reference to a class or interface type. The
reference is resolved and must result in a class type (it must not result in an interface
type). Memory for a new instance of that class is allocated from the heap, and the
instance variables of the new object are initialized to their default initial values. The
objectref, a reference to the instance, is pushed onto the operand stack.
Notes
The new instruction does not completely create a new instance; instance creation is
not completed until an instance initialization method has been invoked on the
uninitialized instance.
Chapter 7
Java Card Virtual Machine Instruction Set
221
newarray
newarray
Create new array
Format
newarray
atype
Forms
newarray = 144 (0x90)
Stack
…, count Þ
…, arrayref
Description
The count must be of type short. It is popped off the operand stack. The count
represents the number of elements in the array to be created.
The unsigned byte atype is a code that indicates the type of array to create. It must
take one of the following values:
Array Type
atype
T_BOOLEAN
10
T_BYTE
11
T_SHORT
12
T_INT
13
A new array whose components are of type atype, of length count, is allocated from
the heap. A reference arrayref to this new array object is pushed onto the operand
stack. All of the elements of the new array are initialized to the default initial value
for its type.
Runtime Exception
If count is less than zero, the newarray instruction throws a
NegativeArraySizeException.
Notes
If a virtual machine does not support the int data type, the value of atype may not
be 13 (array type = T_INT).
222
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
nop
nop
Do nothing
Format
nop
Forms
nop = 0 (0x0)
Stack
No change
Description
Do nothing.
Chapter 7
Java Card Virtual Machine Instruction Set
223
pop
pop
Pop top operand stack word
Format
pop
Forms
pop = 59 (0x3b)
Stack
…, word Þ
…
Description
The top word is popped from the operand stack. The pop instruction must not be
used unless the word contains a 16-bit data type.
Notes
The pop instruction operates on an untyped word, ignoring the type of data it
contains.
224
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
pop2
pop2
Pop top two operand stack words
Format
pop2
Forms
pop2 = 60 (0x3c)
Stack
…, word2, word1 Þ
…
Description
The top two words are popped from the operand stack.
The pop2 instruction must not be used unless each of word1 and word2 is a word that
contains a 16-bit data type or both together are the two words of a single 32-bit
datum.
Notes
Except for restrictions preserving the integrity of 32-bit data types, the pop2
instruction operates on an untyped word, ignoring the type of data it contains.
Chapter 7
Java Card Virtual Machine Instruction Set
225
putfield_<t>
putfield_<t>
Set field in object
Format
putfield_<t>
index
Forms
putfield_a = 135 (0x87)
putfield_b = 136 (0x88)
putfield_s = 137 (0x89)
putfield_i = 138 (0x8a)
Stack
…, objectref, value Þ
…
OR
…, objectref, value.word1, value.word2 Þ
…
Description
The unsigned index is used as an index into the constant pool of the current package
(§3.5). The constant pool item at the index must be of type
CONSTANT_InstanceFieldref (§6.7.2), a reference to a class and a field token.
The class of objectref must not be an array. If the field is protected, and it is a
member of a superclass of the current class, and the field is not declared in the same
package as the current class, then the class of objectref must be either the current class
or a subclass of the current class. If the field is final, it must be declared in the
current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
value must be of a type that is assignment compatible with the field descriptor (t)
type.
226
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
putfield_<t> (cont.)
putfield_<t> (cont.)
The width of a field in a class instance is determined by the field type specified in
the instruction. The item is resolved, determining the field offset1. The objectref,
which must be of type reference, and the value are popped from the operand stack.
If the field is of type byte or type boolean, the value is truncated to a byte. The field
at the offset from the start of the object referenced by objectref is set to the value.
Runtime Exception
If objectref is null, the putfield_<t> instruction throws a NullPointerException.
Notes
In some circumstances, the putfield_<t> instruction may throw a SecurityException
if the current context (§3.4) is not the owning context (§3.4) of the object referenced
by objectref. The exact circumstances when the exception will be thrown are specified
in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
If a virtual machine does not support the int data type, the putfield_i instruction will
not be available.
1. The offset may be computed by adding the field token value to the size of an instance of the immediate
superclass. However, this method is not required by this specification. A Java Card virtual machine may
define any mapping from token value to offset into an instance.
Chapter 7
Java Card Virtual Machine Instruction Set
227
putfield_<t>_this
putfield_<t>_this
Set field in current object
Format
putfield_<t>_this
index
Forms
putfield_a_this = 181 (0xb5)
putfield_b_this = 182 (0xb6)
putfield_s_this = 183 (0xb7)
putfield_i_this = 184 (0xb8)
Stack
…, value Þ
…
OR
…, value.word1, value.word2 Þ
…
Description
The currently executing method must be an instance method that was invoked using
the invokevirtual, invokeinterface or invokespecial instruction. The local variable at index
0 must contain a reference objectref to the currently executing method’s this
parameter. The unsigned index is used as an index into the constant pool of the
current package (§3.5). The constant pool item at the index must be of type
CONSTANT_InstanceFieldref (§6.7.2), a reference to a class and a field token.
The class of objectref must not be an array. If the field is protected, and it is a
member of a superclass of the current class, and the field is not declared in the same
package as the current class, then the class of objectref must be either the current class
or a subclass of the current class. If the field is final, it must be declared in the
current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
value must be of a type that is assignment compatible with the field descriptor (t)
type.
228
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
putfield_<t>_this (cont.)
putfield_<t>_this (cont.)
The width of a field in a class instance is determined by the field type specified in
the instruction. The item is resolved, determining the field offset1. The value is
popped from the operand stack. If the field is of type byte or type boolean, the value
is truncated to a byte. The field at the offset from the start of the object referenced by
objectref is set to the value.
Runtime Exception
If objectref is null, the putfield_<t>_this instruction throws a NullPointerException.
Notes
In some circumstances, the putfield_<t>_this instruction may throw a
SecurityException if the current context (§3.4) is not the owning context (§3.4) of
the object referenced by objectref. The exact circumstances when the exception will be
thrown are specified in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification.
If a virtual machine does not support the int data type, the putfield_i_this instruction
will not be available.
1. The offset may be computed by adding the field token value to the size of an instance of the immediate
superclass. However, this method is not required by this specification. A Java Card virtual machine may
define any mapping from token value to offset into an instance.
Chapter 7
Java Card Virtual Machine Instruction Set
229
putfield_<t>_w
putfield_<t>_w
Set field in object (wide index)
Format
putfield<t>_w
indexbyte1
indexbyte2
Forms
putfield_a_w = 177 (0xb1)
putfield_b_w = 178 (0xb2)
putfield_s_w = 179 (0xb3)
putfield_i_w = 180 (0xb4)
Stack
…, objectref, value Þ
…
OR
…, objectref, value.word1, value.word2 Þ
…
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at the index must be of type
CONSTANT_InstanceFieldref (§6.7.2), a reference to a class and a field token.
The class of objectref must not be an array. If the field is protected, and it is a
member of a superclass of the current class, and the field is not declared in the same
package as the current class, then the class of objectref must be either the current class
or a subclass of the current class. If the field is final, it must be declared in the
current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
value must be of a type that is assignment compatible with the field descriptor (t)
type.
230
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
putfield_<t>_w (cont.)
putfield_<t>_w (cont.)
The width of a field in a class instance is determined by the field type specified in
the instruction. The item is resolved, determining the field offset1. The objectref,
which must be of type reference, and the value are popped from the operand stack.
If the field is of type byte or type boolean, the value is truncated to a byte. The field
at the offset from the start of the object referenced by objectref is set to the value.
Runtime Exception
If objectref is null, the putfield_<t>_w instruction throws a NullPointerException.
Notes
In some circumstances, the putfield_<t>_w instruction may throw a
SecurityException if the current context (§3.4) is not the owning context (§3.4) of
the object referenced by objectref. The exact circumstances when the exception will be
thrown are specified in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE)
Specification.
If a virtual machine does not support the int data type, the putfield_i_w instruction
will not be available.
1. The offset may be computed by adding the field token value to the size of an instance of the immediate
superclass. However, this method is not required by this specification. A Java Card virtual machine may
define any mapping from token value to offset into an instance.
Chapter 7
Java Card Virtual Machine Instruction Set
231
putstatic_<t>
putstatic_<t>
Set static field in class
Format
putstatic_<t>
indexbyte1
indexbyte2
Forms
putstatic_a = 127 (0x7f)
putstatic_b = 128 (0x80)
putstatic_s = 129 (0x81)
putstatic_i = 130 (0x82)
Stack
…, value Þ
…
OR
…, value.word1, value.word2 Þ
…
Description
The unsigned indexbyte1 and indexbyte2 are used to construct an index into the
constant pool of the current package (§3.5), where the value of the index is
(indexbyte1 << 8) | indexbyte2. The constant pool item at the index must be of type
CONSTANT_StaticFieldref (§6.7.3), a reference to a static field. If the field is final,
it must be declared in the current class.
The item must resolve to a field with a type that matches t, as follows:
· a field must be of type reference
·
b
field must be of type byte or type boolean
·
s
field must be of type short
·
i
field must be of type int
value must be of a type that is assignment compatible with the field descriptor (t)
type.
The width of a class field is determined by the field type specified in the instruction.
The item is resolved, determining the class field. The value is popped from the
operand stack. If the field is of type byte or type boolean, the value is truncated to a
byte. The field is set to the value.
232
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
putstatic_<t> (cont.)
putstatic_<t> (cont.)
Notes
In some circumstances, the putstatic_a instruction may throw a SecurityException
if the current context (§3.4) is not the owning context (§3.4) of the object being stored
in the field. The exact circumstances when the exception will be thrown are specified
in Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
If a virtual machine does not support the int data type, the putstatic_i instruction
will not be available.
Chapter 7
Java Card Virtual Machine Instruction Set
233
ret
ret
Return from subroutine
Format
ret
index
Forms
ret = 114 (0x72)
Stack
No change
Description
The index is an unsigned byte that must be a valid index into the local variables of
the current frame (§3.5). The local variable at index must contain a value of type
returnAddress. The contents of the local variable are written into the Java Card
virtual machine’s pc register, and execution continues there.
Notes
The ret instruction is used with the jsr instruction in the implementation of the
finally keyword of the Java language. Note that jsr pushes the address onto the
stack and ret gets it out of a local variable. This asymmetry is intentional.
The ret instruction should not be confused with the return instruction. A return
instruction returns control from a Java method to its invoker, without passing any
value back to the invoker.
234
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
return
return
Return void from method
Format
return
Forms
return = 122 (0x7a)
Stack
…Þ
[empty]
Description
Any values on the operand stack of the current method are discarded. The virtual
machine then reinstates the frame of the invoker and returns control to the invoker.
Chapter 7
Java Card Virtual Machine Instruction Set
235
s2b
s2b
Convert short to byte
Format
s2b
Forms
s2b = 91 (0x5b)
Stack
…, value Þ
…, result
Description
The value on top of the operand stack must be of type short. It is popped from the
top of the operand stack, truncated to a byte result, then sign-extended to a short
result. The result is pushed onto the operand stack.
Notes
The s2b instruction performs a narrowing primitive conversion. It may lose
information about the overall magnitude of value. The result may also not have the
same sign as value.
236
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
s2i
s2i
Convert short to int
Format
s2i
Forms
s2i = 92 (0x5c)
Stack
…, value Þ
…, result.word1, result.word2
Description
The value on top of the operand stack must be of type short. It is popped from the
operand stack and sign-extended to an int result. The result is pushed onto the
operand stack.
Notes
The s2i instruction performs a widening primitive conversion. Because all values of
type short are exactly representable by type int, the conversion is exact.
If a virtual machine does not support the int data type, the s2i instruction will not
be available.
Chapter 7
Java Card Virtual Machine Instruction Set
237
sadd
sadd
Add short
Format
sadd
Forms
sadd = 65 (0x41)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. The short result is value1 + value2. The result is pushed onto the
operand stack.
If a sadd instruction overflows, then the result is the low-order bits of the true
mathematical result in a sufficiently wide two’s-complement format. If overflow
occurs, then the sign of the result may not be the same as the sign of the
mathematical sum of the two values.
238
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
saload
saload
Load short from array
Format
saload
Forms
saload = 38 (0x46)
Stack
…, arrayref, index Þ
…, value
Description
The arrayref must be of type reference and must refer to an array whose
components are of type short. The index must be of type short. Both arrayref and
index are popped from the operand stack. The short value in the component of the
array at index is retrieved and pushed onto the top of the operand stack.
Runtime Exceptions
If arrayref is null, saload throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
saload instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the saload instruction may throw a SecurityException if the
current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 7
Java Card Virtual Machine Instruction Set
239
sand
sand
Boolean AND short
Format
sand
Forms
sand = 83 (0x53)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 are popped from the operand stack. A short result is
calculated by taking the bitwise AND (conjunction) of value1 and value2. The result is
pushed onto the operand stack.
240
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sastore
sastore
Store into short array
Format
sastore
Forms
sastore = 57 (0x39)
Stack
…, arrayref, index, value Þ
…
Description
The arrayref must be of type reference and must refer to an array whose
components are of type short. The index and value must both be of type short. The
arrayref, index and value are popped from the operand stack. The short value is stored
as the component of the array indexed by index.
Runtime Exception
If arrayref is null, sastore throws a NullPointerException.
Otherwise, if index is not within the bounds of the array referenced by arrayref, the
sastore instruction throws an ArrayIndexOutOfBoundsException.
Notes
In some circumstances, the sastore instruction may throw a SecurityException if
the current context (§3.4) is not the owning context (§3.4) of the array referenced by
arrayref. The exact circumstances when the exception will be thrown are specified in
Chapter 6 of the Java CardÔ 2.2 Runtime Environment (JCRE) Specification.
Chapter 7
Java Card Virtual Machine Instruction Set
241
sconst_<s>
sconst_<s>
Push short constant
Format
sconst_<s>
Forms
sconst_m1 = 2 (0x2)
sconst_0 = 3 (0x3)
sconst_1 = 4 (0x4)
sconst_2 = 5 (0x5)
sconst_3 = 6 (0x6)
sconst_4= 7 (0x7)
sconst_5 = 8 (0x8)
Stack
…Þ
…, <s>
Description
Push the short constant <s> (-1, 0, 1, 2, 3, 4, or 5) onto the operand stack.
242
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sdiv
sdiv
Divide short
Format
sdiv
Forms
sdiv = 71 (0x47)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. The short result is the value of the Java expression value1 / value2.
The result is pushed onto the operand stack.
A short division rounds towards 0; that is, the quotient produced for short values
in n/d is a short value q whose magnitude is as large as possible while satisfying | d
· q | <= | n |. Moreover, q is a positive when | n | >= | d | and n and d have the
same sign, but q is negative when | n | >= | d | and n and d have opposite signs.
There is one special case that does not satisfy this rule: if the dividend is the negative
integer of the largest possible magnitude for the short type, and the divisor is –1,
then overflow occurs, and the result is equal to the dividend. Despite the overflow,
no exception is thrown in this case.
Runtime Exception
If the value of the divisor in a short division is 0, sdiv throws an
ArithmeticException.
Chapter 7
Java Card Virtual Machine Instruction Set
243
sinc
sinc
Increment local short variable by constant
Format
sinc
index
const
Forms
sinc = 89 (0x59)
Stack
No change
Description
The index is an unsigned byte that must be a valid index into the local variable of the
current frame (§3.5). The const is an immediate signed byte. The local variable at
index must contain a short. The value const is first sign-extended to a short, then
the local variable at index is incremented by that amount.
244
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sinc_w
sinc_w
Increment local short variable by constant
Format
sinc_w
index
byte1
byte2
Forms
sinc_w = 150 (0x96)
Stack
No change
Description
The index is an unsigned byte that must be a valid index into the local variable of the
current frame (§3.5). The immediate unsigned byte1 and byte2 values are assembled
into a short const where the value of const is (byte1 << 8) | byte2. The local variable
at index, which must contain a short, is incremented by const.
Chapter 7
Java Card Virtual Machine Instruction Set
245
sipush
sipush
Push short
Format
sipush
byte1
byte2
Forms
sipush = 19 (0x13)
Stack
…Þ
…, value1.word1, value1.word2
Description
The immediate unsigned byte1 and byte2 values are assembled into a signed short
where the value of the short is (byte1 << 8) | byte2. The intermediate value is then
sign-extended to an int, and the resulting value is pushed onto the operand stack.
Notes
If a virtual machine does not support the int data type, the sipush instruction will
not be available.
246
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sload
sload
Load short from local variable
Format
sload
index
Forms
sload = 22 (0x16)
Stack
…Þ
…, value
Description
The index is an unsigned byte that must be a valid index into the local variables of
the current frame (§3.5). The local variable at index must contain a short. The value
in the local variable at index is pushed onto the operand stack.
Chapter 7
Java Card Virtual Machine Instruction Set
247
sload_<n>
sload_<n>
Load short from local variable
Format
sload_<n>
Forms
sload_0
sload_1
sload_2
sload_3
=
=
=
=
28
29
30
31
(0x1c)
(0x1d)
(0x1e)
(0x1f)
Stack
…Þ
…, value
Description
The <n> must be a valid index into the local variables of the current frame (§3.5).
The local variable at <n> must contain a short. The value in the local variable at <n>
is pushed onto the operand stack.
Notes
Each of the sload_<n> instructions is the same as sload with an index of <n>, except
that the operand <n> is implicit.
248
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
slookupswitch
slookupswitch
Access jump table by key match and jump
Format
slookupswitch
defaultbyte1
defaultbyte2
npairs1
npairs2
match-offset pairs…
Pair Format
matchbyte1
matchbyte2
offsetbyte1
offsetbyte2
Forms
slookupswitch = 117 (0x75)
Stack
…, key Þ
…
Description
A slookupswitch instruction is a variable-length instruction. Immediately after the
slookupswitch opcode follow a signed 16-bit value default, an unsigned 16-bit value
npairs, and then npairs pairs. Each pair consists of a short match and a signed 16-bit
offset. Each of the signed 16-bit values is constructed from two unsigned bytes as
(byte1 << 8) | byte2.
The table match-offset pairs of the slookupswitch instruction must be sorted in
increasing numerical order by match.
The key must be of type short and is popped from the operand stack and compared
against the match values. If it is equal to one of them, then a target address is
calculated by adding the corresponding offset to the address of the opcode of this
slookupswitch instruction. If the key does not match any of the match values, the target
address is calculated by adding default to the address of the opcode of this
slookupswitch instruction. Execution then continues at the target address.
The target address that can be calculated from the offset of each match-offset pair, as
well as the one calculated from default, must be the address of an opcode of an
instruction within the method that contains this slookupswitch instruction.
Chapter 7
Java Card Virtual Machine Instruction Set
249
slookupswitch (cont.)
slookupswitch (cont.)
Notes
The match-offset pairs are sorted to support lookup routines that are quicker than
linear search.
250
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
smul
smul
Multiply short
Format
smul
Forms
smul = 69 (0x45)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. The short result is value1 * value2. The result is pushed onto the
operand stack.
If a smul instruction overflows, then the result is the low-order bits of the
mathematical product as a short. If overflow occurs, then the sign of the result may
not be the same as the sign of the mathematical product of the two values.
Chapter 7
Java Card Virtual Machine Instruction Set
251
sneg
sneg
Negate short
Format
sneg
Forms
sneg = 72 (0x4b)
Stack
…, value Þ
…, result
Description
The value must be of type short. It is popped from the operand stack. The short
result is the arithmetic negation of value, -value. The result is pushed onto the operand
stack.
For short values, negation is the same as subtraction from zero. Because the Java
Card virtual machine uses two’s-complement representation for integers and the
range of two’s-complement values is not symmetric, the negation of the maximum
negative short results in that same maximum negative number. Despite the fact that
overflow has occurred, no exception is thrown.
For all short values x, -x equals (~x) + 1.
252
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sor
sor
Boolean OR short
Format
sor
Forms
sor = 85 (0x55)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. A short result is calculated by taking the bitwise inclusive OR of
value1 and value2. The result is pushed onto the operand stack.
Chapter 7
Java Card Virtual Machine Instruction Set
253
srem
srem
Remainder short
Format
srem
Forms
srem = 73 (0x49)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. The short result is the value of the Java expression value1 – (value1 /
value2) * value2. The result is pushed onto the operand stack.
The result of the irem instruction is such that (a/b)*b + (a%b) is equal to a. This
identity holds even in the special case that the dividend is the negative short of
largest possible magnitude for its type and the divisor is –1 (the remainder is 0). It
follows from this rule that the result of the remainder operation can be negative only
if the dividend is negative and can be positive only if the dividend is positive.
Moreover, the magnitude of the result is always less than the magnitude of the
divisor.
Runtime Exception
If the value of the divisor for a short remainder operator is 0, srem throws an
ArithmeticException.
254
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sreturn
sreturn
Return short from method
Format
sreturn
Forms
sreturn = 120 (0x78)
Stack
…, value Þ
[empty]
Description
The value must be of type short. It is popped from the operand stack of the current
frame (§3.5) and pushed onto the operand stack of the frame of the invoker. Any
other values on the operand stack of the current method are discarded.
The virtual machine then reinstates the frame of the invoker and returns control to
the invoker.
Chapter 7
Java Card Virtual Machine Instruction Set
255
sshl
sshl
Shift left short
Format
sshl
Forms
sshl = 77 (0x4d)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. A short result is calculated by shifting value1 left by s bit positions,
where s is the value of the low five bits of value2. The result is pushed onto the
operand stack.
Notes
This is equivalent (even if overflow occurs) to multiplication by 2 to the power s. The
shift distance actually used is always in the range 0 to 31, inclusive, as if value2 were
subjected to a bitwise logical AND with the mask value 0x1f.
The mask value of 0x1f allows shifting beyond the range of a 16-bit short value. It is
used by this instruction, however, to ensure results equal to those generated by the
Java instruction ishl.
256
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sshr
sshr
Arithmetic shift right short
Format
sshr
Forms
sshr = 79 (0x4f)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. A short result is calculated by shifting value1 right by s bit positions,
with sign extension, where s is the value of the low five bits of value2. The result is
pushed onto the operand stack.
Notes
The resulting value is ë(value1) / 2sû, where s is value2 & 0x1f. For nonnegative value1,
this is equivalent (even if overflow occurs) to truncating short division by 2 to the
power s. The shift distance actually used is always in the range 0 to 31, inclusive, as
if value2 were subjected to a bitwise logical AND with the mask value 0x1f.
The mask value of 0x1f allows shifting beyond the range of a 16-bit short value. It is
used by this instruction, however, to ensure results equal to those generated by the
Java instruction ishr.
Chapter 7
Java Card Virtual Machine Instruction Set
257
sspush
sspush
Push short
Format
sspush
byte1
byte2
Forms
sspush = 17 (0x11)
Stack
…Þ
…, value
Description
The immediate unsigned byte1 and byte2 values are assembled into a signed short
where the value of the short is (byte1 << 8) | byte2. The resulting value is pushed onto
the operand stack.
258
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sstore
sstore
Store short into local variable
Format
sstore
index
Forms
sstore = 41 (0x29)
Stack
…, value Þ
…
Description
The index is an unsigned byte that must be a valid index into the local variables of
the current frame (§3.5). The value on top of the operand stack must be of type
short. It is popped from the operand stack, and the value of the local variable at
index is set to value.
Chapter 7
Java Card Virtual Machine Instruction Set
259
sstore_<n>
sstore_<n>
Store short into local variable
Format
sstore_<n>
Forms
sstore_0
sstore_1
sstore_2
sstore_3
=
=
=
=
47
48
49
50
(0x2f)
(0x30)
(0x31)
(0x32)
Stack
…, value Þ
…
Description
The <n> must be a valid index into the local variables of the current frame (§3.5).
The value on top of the operand stack must be of type short. It is popped from the
operand stack, and the value of the local variable at <n> is set to value.
260
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
ssub
ssub
Subtract short
Format
ssub
Forms
ssub = 67 (0x43)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. The short result is value1 - value2. The result is pushed onto the
operand stack.
For short subtraction, a – b produces the same result as a + (–b). For short values,
subtraction from zeros is the same as negation.
Despite the fact that overflow or underflow may occur, in which case the result may
have a different sign than the true mathematical result, execution of a ssub
instruction never throws a runtime exception.
Chapter 7
Java Card Virtual Machine Instruction Set
261
stableswitch
stableswitch
Access jump table by short index and jump
Format
stableswitch
defaultbyte1
defaultbyte2
lowbyte1
lowbyte2
highbyte1
highbyte2
jump offsets…
Offset Format
offsetbyte1
offsetbyte2
Forms
stableswitch = 115 (0x73)
Stack
…, index Þ
…
Description
A stableswitch instruction is a variable-length instruction. Immediately after the
stableswitch opcode follow a signed 16-bit value default, a signed 16-bit value low, a
signed 16-bit value high, and then high – low + 1 further signed 16-bit offsets. The
value low must be less than or equal to high. The high – low + 1 signed 16-bit offsets
are treated as a 0-based jump table. Each of the signed 16-bit values is constructed
from two unsigned bytes as (byte1 << 8) | byte2.
The index must be of type short and is popped from the stack. If index is less than
low or index is greater than high, than a target address is calculated by adding default
to the address of the opcode of this stableswitch instruction. Otherwise, the offset at
position index – low of the jump table is extracted. The target address is calculated by
adding that offset to the address of the opcode of this stableswitch instruction.
Execution then continues at the target address.
The target addresses that can be calculated from each jump table offset, as well as
the one calculated from default, must be the address of an opcode of an instruction
within the method that contains this stableswitch instruction.
262
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sushr
sushr
Logical shift right short
Format
sushr
Forms
sushr = 81 (0x51)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. A short result is calculated by sign-extending value1 to 32 bits1 and
shifting the result right by s bit positions, with zero extension, where s is the value of
the low five bits of value2. The resulting value is then truncated to a 16-bit result. The
result is pushed onto the operand stack.
Notes
If value1 is positive and s is value2 & 0x1f, the result is the same as that of value1 >> s;
if value1 is negative, the result is equal to the value of the expression (value1 >> s) +
(2 << ~s). The addition of the (2 << ~s) term cancels out the propagated sign bit. The
shift distance actually used is always in the range 0 to 31, inclusive, as if value2 were
subjected to a bitwise logical AND with the mask value 0x1f.
The mask value of 0x1f allows shifting beyond the range of a 16-bit short value. It is
used by this instruction, however, to ensure results equal to those generated by the
Java instruction iushr.
1. Sign extension to 32 bits ensures that the result computed by this instruction will be exactly equal to that
computed by the Java iushr instruction, regardless of the input values. In a Java Card virtual machine the
expression “0xffff >>> 0x01” yields 0xffff, where “>>>” is performed by the sushr instruction. The same
result is rendered by a Java virtual machine.
Chapter 7
Java Card Virtual Machine Instruction Set
263
swap_x
swap_x
Swap top two operand stack words
Format
swap_x
mn
Forms
swap_x = 64 (0x40)
Stack
…, wordM+N, …, wordM+1, wordM, …, word1 Þ
…, wordM, …, word1, wordM+N, …, wordM+1
Description
The unsigned byte mn is used to construct two parameter values. The high nibble,
(mn & 0xf0) >> 4, is used as the value m. The low nibble, (mn & 0xf), is used as the
value n. Permissible values for both m and n are 1 and 2.
The top m words on the operand stack are swapped with the n words immediately
below.
The swap_x instruction must not be used unless the ranges of words 1 through m and
words m+1 through n each contain either a 16-bit data type, two 16-bit data types, a
32-bit data type, a 16-bit data type and a 32-bit data type (in either order), or two 32bit data types.
Notes
Except for restrictions preserving the integrity of 32-bit data types, the swap_x
instruction operates on untyped words, ignoring the types of data they contain.
If a virtual machine does not support the int data type, the only permissible value
for both m and n is 1.
264
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
sxor
sxor
Boolean XOR short
Format
sxor
Forms
sxor = 87 (0x57)
Stack
…, value1, value2 Þ
…, result
Description
Both value1 and value2 must be of type short. The values are popped from the
operand stack. A short result is calculated by taking the bitwise exclusive OR of
value1 and value2. The result is pushed onto the operand stack.
Chapter 7
Java Card Virtual Machine Instruction Set
265
266
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
CHAPTER
8
Tables of Instructions
The following pages contain lists of the APDU instructions recognized by Java Card
organized by opcode value (TABLE 8-1 on page 268) and by opcode mnemonic
(TABLE 8-2 on page 270).
267
TABLE 8-1
268
Instructions by Opcode Value
dec
hex
mnemonic
dec
hex
mnemonic
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
00
01
02
03
04
05
06
07
08
09
0A
0B
0C
0D
0E
0F
10
11
12
13
14
15
16
17
18
19
1A
1B
1C
1D
1E
1F
20
21
22
23
24
25
26
27
28
29
2A
2B
2C
2D
2E
nop
aconst_null
sconst_m1
sconst_0
sconst_1
sconst_2
sconst_3
sconst_4
sconst_5
iconst_m1
iconst_0
iconst_1
iconst_2
iconst_3
iconst_4
iconst_5
bspush
sspush
bipush
sipush
iipush
aload
sload
iload
aload_0
aload_1
aload_2
aload_3
sload_0
sload_1
sload_2
sload_3
iload_0
iload_1
iload_2
iload_3
aaload
baload
saload
iaload
astore
sstore
istore
astore_0
astore_1
astore_2
astore_3
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
2F
30
31
32
33
34
35
36
37
38
39
3A
3B
3C
3D
3E
3F
40
41
42
43
44
45
46
47
48
49
4A
4B
4C
4D
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
5D
sstore_0
sstore_1
sstore_2
sstore_3
istore_0
istore_1
istore_2
istore_3
aastore
bastore
sastore
iastore
pop
pop2
dup
dup2
dup_x
swap_x
sadd
iadd
ssub
isub
smul
imul
sdiv
idiv
srem
irem
sneg
ineg
sshl
ishl
sshr
ishr
sushr
iushr
sand
iand
sor
ior
sxor
ixor
sinc
iinc
s2b
s2i
i2b
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Instructions by Opcode Value (continued)
dec
hex
mnemonic
dec
hex
mnemonic
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
5E
5F
60
61
62
63
64
65
66
67
68
69
6A
6B
6C
6D
6E
6F
70
71
72
73
74
75
76
77
78
79
7A
7B
7C
7D
7E
7F
80
81
82
83
84
85
86
87
88
89
8A
8B
8C
i2s
icmp
ifeq
ifne
iflt
ifge
ifgt
ifle
ifnull
ifnonnull
if_acmpeq
if_acmpne
if_scmpeq
if_scmpne
if_scmplt
if_scmpge
if_scmpgt
if_scmple
goto
jsr
ret
stableswitch
itableswitch
slookupswitch
ilookupswitch
areturn
sreturn
ireturn
return
getstatic_a
getstatic_b
getstatic_s
getstatic_i
putstatic_a
putstatic_b
putstatic_s
putstatic_i
getfield_a
getfield_b
getfield_s
getfield_i
putfield_a
putfield_b
putfield_s
putfield_i
invokevirtual
invokespecial
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
8D
8E
8F
90
91
92
93
94
95
96
97
98
99
9A
9B
9C
9D
9E
9F
A0
A1
A2
A3
A4
A5
A6
A7
A8
A9
AA
AB
AC
AD
AE
AF
B0
B1
B2
B3
B4
B5
B6
B7
B8
invokestatic
invokeinterface
new
newarray
anewarray
arraylength
athrow
checkcast
instanceof
sinc_w
iinc_w
ifeq_w
ifne_w
iflt_w
ifge_w
ifgt_w
ifle_w
ifnull_w
ifnonnull_w
if_acmpeq_w
if_acmpne_w
if_scmpeq_w
if_scmpne_w
if_scmplt_w
if_scmpge_w
if_scmpgt_w
if_scmple_w
goto_w
getfield_a_w
getfield_b_w
getfield_s_w
getfield_i_w
getfield_a_this
getfield_b_this
getfield_s_this
getfield_i_this
putfield_a_w
putfield_b_w
putfield_s_w
putfield_i_w
putfield_a_this
putfield_b_this
putfield_s_this
putfield_i_this
…
impdep1
impdep2
254 FE
255 FF
Chapter 8
Tables of Instructions
269
TABLE 8-2
270
Instructions by Opcode Mnemonic
mnemonic
dec
hex
mnemonic
dec
hex
aaload
aastore
aconst_null
aload
aload_0
aload_1
aload_2
aload_3
anewarray
areturn
arraylength
astore
astore_0
astore_1
astore_2
astore_3
athrow
baload
bastore
bipush
bspush
checkcast
dup
dup_x
dup2
getfield_a
getfield_a_this
getfield_a_w
getfield_b
getfield_b_this
getfield_b_w
getfield_i
getfield_i_this
getfield_i_w
getfield_s
getfield_s_this
getfield_s_w
getstatic_a
getstatic_b
getstatic_i
getstatic_s
goto
goto_w
i2b
i2s
iadd
iaload
36
55
1
21
24
25
26
27
145
119
146
40
43
44
45
46
147
37
56
18
16
148
61
63
62
131
173
169
132
174
170
134
176
172
133
175
171
123
124
126
125
112
168
93
94
66
39
24
37
01
15
18
19
1A
1B
91
77
92
28
2B
2C
2D
2E
93
25
38
12
10
94
3D
3F
3E
83
AD
A9
84
AE
AA
86
B0
AC
85
AF
AB
7B
7C
7E
7D
70
A8
5D
5E
42
27
iand
iastore
icmp
iconst_0
iconst_1
iconst_2
iconst_3
iconst_4
iconst_5
iconst_m1
idiv
if_acmpeq
if_acmpeq_w
if_acmpne
if_acmpne_w
if_scmpeq
if_scmpeq_w
if_scmpge
if_scmpge_w
if_scmpgt
if_scmpgt_w
if_scmple
if_scmple_w
if_scmplt
if_scmplt_w
if_scmpne
if_scmpne_w
ifeq
ifeq_w
ifge
ifge_w
ifgt
ifgt_w
ifle
ifle_w
iflt
iflt_w
ifne
ifne_w
ifnonnull
ifnonnull_w
ifnull
ifnull_w
iinc
iinc_w
iipush
iload
84
58
95
10
11
12
13
14
15
9
72
104
160
105
161
106
162
109
165
110
166
111
167
108
164
107
163
96
152
99
155
100
156
101
157
98
154
97
153
103
159
102
158
90
151
20
23
54
3A
5F
0A
0B
0C
0D
0E
0F
09
48
68
A0
69
A1
6A
A2
6D
A5
6E
A6
6F
A7
6C
A4
6B
A3
60
98
63
9B
64
9C
65
9D
62
9A
61
99
67
9F
66
9E
5A
97
14
17
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Instructions by Opcode Mnemonic (continued)
mnemonic
dec
hex
mnemonic
dec
hex
iload_0
iload_1
iload_2
iload_3
ilookupswitch
imul
ineg
instanceof
invokeinterface
invokespecial
invokestatic
invokevirtual
ior
irem
ireturn
ishl
ishr
istore
istore_0
istore_1
istore_2
istore_3
isub
itableswitch
iushr
ixor
jsr
new
newarray
nop
pop
pop2
putfield_a
putfield_a_this
putfield_a_w
putfield_b
putfield_b_this
putfield_b_w
putfield_i
putfield_i_this
putfield_i_w
putfield_s
putfield_s_this
putfield_s_w
putstatic_a
putstatic_b
putstatic_i
32
33
34
35
118
70
76
149
142
140
141
139
86
74
121
78
80
42
51
52
53
54
68
116
82
88
113
143
144
0
59
60
135
181
177
136
182
178
138
184
180
137
183
179
127
128
130
20
21
22
23
76
46
4C
95
8E
8C
8D
8B
56
4A
79
4E
50
2A
33
34
35
36
44
74
52
58
71
8F
90
00
3B
3C
87
B5
B1
88
B6
B2
8A
B8
B4
89
B7
B3
7F
80
82
putstatic_s
ret
return
s2b
s2i
sadd
saload
sand
sastore
sconst_0
sconst_1
sconst_2
sconst_3
sconst_4
sconst_5
sconst_m1
sdiv
sinc
sinc_w
sipush
sload
sload_0
sload_1
sload_2
sload_3
slookupswitch
smul
sneg
sor
srem
sreturn
sshl
sshr
sspush
sstore
sstore_0
sstore_1
sstore_2
sstore_3
ssub
stableswitch
sushr
swap_x
sxor
129
114
122
91
92
65
38
83
57
3
4
5
6
7
8
2
71
89
150
19
22
28
29
30
31
117
69
75
85
73
120
77
79
17
41
47
48
49
50
67
115
81
64
87
81
72
7A
5B
5C
41
26
53
39
03
04
05
06
07
08
02
47
59
96
13
16
1C
1D
1E
1F
75
45
4B
55
49
78
4D
4F
11
29
2F
30
31
32
43
73
51
40
57
Chapter 8
Tables of Instructions
271
272
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Glossary
active applet instance—an applet instance that is selected on at least one of the
logical channels.
AID (application identifier)—defined by ISO 7816, a string used to uniquely identify
card applications and certain types of files in card file systems. An AID consists of
two distinct pieces: a 5-byte RID (resource identifier) and a 0 to 11-byte PIX
(proprietary identifier extension). The RID is a resource identifier assigned to
companies by ISO. The PIX identifiers are assigned by companies.
There is a unique AID for each package and a unique AID for each applet in the
package. The package AID and the default AID for each applet defined in the
package are specified in the CAP file. They are supplied to the converter when the
CAP file is generated.
APDU—an acronym for Application Protocol Data Unit as defined in ISO 7816-4.
API—an acronym for Application Programming Interface. The API defines calling
conventions by which an application program accesses the operating system and
other services.
applet—within the context of this document means a Java Card Applet, which is the
basic unit of selection, context, functionality, and security in Java Card technology.
applet developer—refers to a person creating an applet using Java Card technology.
applet execution context—context of a package that contains currently active applet.
applet firewall—the mechanism that prevents unauthorized accesses to objects in
contexts other than currently active context.
applet package—see library package.
assigned logical channel—the logical channel on which the applet instance is either
the active applet instance or will become the active applet instance.
273
atomic operation—an operation that either completes in its entirety or no part of the
operation completes at all.
atomicity—refers to whether a particular operation is atomic. Atomicity of data
update guarantee that data are not corrupted in case of power loss or card removal.
ATR—an acronym for Answer to Reset. An ATR is a string of bytes sent by the Java
Card after a reset condition.
basic logical channel—logical channel 0, the only channel that is active at card reset.
This channel is permanent and can never be closed.
big-endian—a technique of storing multibyte data where the high-order bytes come
first. For example, given an 8-bit data item stored in big-endian order, the first bit
read is considered the high bit.
binary compatibility—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.
bytecode—machine-independent code generated by the Java compiler and executed
by the Java interpreter.
CAD—an acronym for Card Acceptance Device. The CAD is the device in which the
card is inserted.
CAP file—the CAP file is produced by the Converter and is the standard file format
for the binary compatibility of the Java Card platform. A CAP file contains an
executable binary representation of the classes of a Java package. The CAP file also
contains the CAP file components (see also CAP file component). The CAP files
produced by the converter are contained in JAR files.
CAP file component—a Java Card CAP file consists of a set of components which
represent a Java package. Each component describes a set of elements in the Java
package, or an aspect of the CAP file. A complete CAP file must contain all of the
required components: Header, Directory, Import, Constant Pool, Method, Static
Field, and Reference Location
These components are optional: the Applet, Export, and Debug. The Applet
component is included only if one or more Applets are defined in the package. The
Export component is included only if classes in other packages may import elements
in the package defined. The Debug component is optional. It contains all of the data
necessary for debugging a package.
card session—a card session begins with the insertion of the card into the CAD. The
card is powered up, and exchanges streams of APDUs with the CAD. The card
session ends when the card is removed from the CAD.
cast—the explicit conversion from one data type to another.
274
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
constant pool—the constant pool contains variable-length structures representing
various string constants, class names, field names and other constants referred to
within the CAP file and the ExportFile structure. Each of the constant pool entries,
including entry zero, is a variable-length structure whose format is indicated by its
first tag byte. There are no ordering constraints on entries in the constant pool
entries. One constant pool is associated with each package.
There are differences between the Java language constant pool and the Java Card
constant pool. For example, in the Java constant pool there is one constant type for
method references, while in the Java Card constant pool there are three constant
types for method references. The additional information provided by a constant type
in Java Card technologies simplifies resolution of references.
context—protected object space associated with each applet package and JCRE. All
objects owned by an applet belong to context of the applet's package.
context switch—a change from one currently active context to another. For example,
a context switch is caused by an attempt to access an object that belongs to an applet
instance that resides in a different package. The result of a context switch is a new
currently active context.
Converter—a piece of software that preprocesses all of the Java class files that make
up a package, and converts the package to a CAP file. The Converter also produces
an export file.
currently active context—when an object instance method is invoked, an owning
context of this object becomes currently active context.
currently selected applet—the JCRE keeps track of the currently selected Java Card
applet. Upon receiving a SELECT FILE command with this applet’s AID, the JCRE
makes this applet the currently selected applet. The JCRE sends all APDU
commands to the currently selected applet.
custom CAP file component—a new component added to the CAP file. The new
component must must conform to the general component format. Otherwise, it will
be silently ignored by the JCVM. The identifiers associated with the new component
are recorded in the custom_component item of the CAP file's Directory component.
default applet—an applet that is selected by default on a logical channel when it is
opened. If an applet is designated the default applet on a particular logical channel
on the Java Card, it will become the active applet by default when that logical
channel is opened via the basic channel.
EEPROM—an acronym for Electrically Erasable, Programmable Read Only Memory.
Export file—the Export file is produced by the Converter and represents the fields
and methods of a package which can be imported by classes in other packages.
Glossary
275
externally visible—in Java Card, “externally visible from a package” refers to any
classes, interfaces, their constructors, methods and fields that can be accessed from
another package according to the Java Language semantics, as defined by the JavaÔ
Language Specification, and Java Card package access control restrictions (see the
JavaÔ Language Specification, section 2.2.1.1).
Externally visible items may be represented in an export file. For a library package,
all externally visible items are represented in an export file. For an applet package,
only those externally visible items which are part of a shareable interface are
represented in an export file.
finalization—the process by which a Java VM allows an unreferenced object
instance to release non-memory resources (e.g. close/open files) prior to reclaiming
the object's memory. Finalization is only performed on an object when that object is
ready to be garbage collected (i.e. there are no references to the object).
Finalization is not supported by the Java Card virtual machine. finalize() will
not be called automatically by the Java Card virtual machine.
firewall—see applet firewall.
flash memory—a type of persistent mutable memory. It is more efficient in space
and power that EPROM. Flash memory can be read bit-by-bit but can be updated
only as a block. Thus, flash memory is typically used for storing additional
programs or large chunks of data that are updated as a whole.
framework—the set of classes that implement the API. This includes core and
extension packages. Responsibilities include applet selection, sending APDU bytes,
and managing atomicity.
garbage collection—the process by which dynamically allocated storage is
automatically reclaimed during the execution of a program.
heap—a common pool of free memory usable by a program. A part of the
computer's memory used for dynamic memory allocation, in which blocks of
memory are used in an arbitrary order. The Java Card virtual machine's heap is not
required to be garbage collected. Objects allocated from the heap will not necessarily
be reclaimed.
installer—the on-card mechanism to download and install CAP files. The installer
receives executable binary from the off-card installation program, writes the binary
into the smart card memory, links it with the other classes on the card, and creates and
initializes any data structures used internally by the Java Card Runtime Environment.
installation program—the off-card mechanism that employs a card acceptance device
(CAD) to transmit the executable binary in a CAP file to the installer running on the
card.
instance variables—are also known as non-static fields.
276
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
instantiation—in object-oriented programming, means to produce a particular object
from its class template. This involves allocation of a data structure with the types
specified by the template, and initialization of instance variables with either default
values or those provided by the class’s constructor function.
instruction—a statement that indicates an operation for the computer to perform
and any data to be used in performing the operation. An instruction can be in
machine language or a programming language.
internally visible—items which are not externally visible. These items are not
described in a package’s export file, but some such items use private tokens to
represent internal references. See also externally visible.
JAR file—a file format used for aggregating many files into one.
Java Card Remote Method Invocation (JCRMI)—a subset of the Java Remote
Method Invocation (RMI) system. It provides a mechanism for a client application
running on the CAD platform to invoke a method on a remote object on the card.
Java Card Runtime Environment (JCRE)—consists of the Java Card Virtual
Machine, the framework, and the associated native methods.
Java Card Virtual Machine (JCVM)—a subset of the Java Virtual Machine which is
designed to be run on smart cards and other resource-constrained devices. The
JCVM acts an engine that loads Java class files and executes them with a particular set
of semantics.
JCRE entry point objects—objects owned by the JCRE context that contain entry
point methods. These methods can be invoked from any context and allow nonprivileged users (applets) to request privileged JCRE system services. JCRE entry
point objects can be either temporary or permanent:
■
■
temporary—references to temporary JCRE entry point objects cannot be stored in
class variables, instance variables or array components. The JCRE detects and
restricts attempts to store references to these objects as part of the firewall
functionality to prevent unauthorized re-use. Examples of these objects are APDU
objects and all JCRE-owned exception objects.
permanent—references to permanent JCRE entry point objects can be stored and
freely re-used. Examples of these objects are JCRE-owned AID instances.
JDK—is an acronym for Java Development Kit. The JDK is a Sun Microsystems, Inc.
product that provides the environment required for software development in the
Java programming language. The JDK is available for a variety of platforms, for
example Sun Solaris and Microsoft Windows.
library package—a library package is a Java package that does not contain any nonabstract classes which extend the class javacard.framework.Applet. An applet
package contains one or more non-abstract classes which extend the
javacard.framework.Applet class.
Glossary
277
local variable—a data item known within a block, but inaccessible to code outside
the block. For example, any variable defined within a method is a local variable and
can't be used outside the method.
logical channel—a logical channel, as seen at the card edge, works as a logical link
to an application on the card. A logical channel establishes a communications
session between a card applet and the terminal. Commands issued on a specific
logical channel are forwarded to the active applet on that logical channel. For more
information, see the ISO 7816 Specification, Part 4. (http://www.iso.org).
MAC—an acronym for Message Authentication Code. MAC is an encryption of data
for security purposes.
mask production (masking)—refers to embedding the Java Card virtual machine,
runtime environment, and applets in the read-only memory of a smart card during
manufacture.
method—the name given to a procedure or routine, associated with one or more
classes, in object-oriented languages.
multiselectable applets—implements the
javacard.framework.MultiSelectable interface. Multiselectable applets can
be selected on multiple logical channels at the same time. They can also accept other
applets belonging to the same package being selected simultaneously.
multiselected applet—an applet instance that is selected (that is, the active applet
instance) on more than one logical channel simultaneously.
namespace—a set of names in which all names are unique.
native method—a method which is not implemented in the Java programming
language, but rather, in another language. The CAP file format does not support
native methods.
object-oriented—a programming methodology based on the concept of an object,
which is a data structure encapsulated with a set of routines, called methods, which
operate on the data.
object owner—the applet instance within the currently active context when the
object is instantiated. An object can be owned by an applet instance, or by the JCRE.
objects—in object-oriented programming, are unique instances of a data structure
defined according to the template provided by its class. Each object has its own
values for the variables belonging to its class and can respond to the messages
(methods) defined by its class.
origin logical channel—the logical channel on which an APDU command is issued.
owning context—the context in which an object is instantiated or created.
278
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
package—a namespace within the Java programming language and can have classes
and interfaces.
persistent object—persistent objects and their values persist from one CAD session
to the next, indefinitely. Objects are persistent by default. Persistent object values are
updated atomically using transactions. The term persistent does not mean there is an
object-oriented database on the card or that objects are serialized/deserialized, just
that the objects are not lost when the card loses power.
PIX—see AID.
RAM (random access memory)—used as temporary working space for storing and
modifying data. RAM is non persistent memory; that is, the information content is
not preserved when power is removed from the memory cell. RAM can be accessed
an unlimited number of times and none of the restrictions of EEPROM apply.
reference implementation—a fully functional and compatible implementation of a
given technology. It enables developers to build prototypes of applications based on
the technology.
remote interface—an interface which extends, directly or indirectly, the interface
java.rmi.Remote.
Each method declaration in the remote interface or its super-interfaces includes the
exception java.rmi.RemoteException (or one of its superclasses) in its throws
clause.
In a remote method declaration, if a remote object is declared as a return type, it is
declared as the remote interface, not the implementation class of that interface.
In addition, JCRMI imposes additional constraints on the definition of remote
methods. These constraints are as a result of the Java Card language subset and other
feature limitations.
remote methods—the methods of a remote interface.
remote object—an object whose remote methods can be invoked remotely from the
CAD client. A remote object is described by one or more remote interfaces.
RFU—acronym for “Reserved for Future Use”.
RID—see AID.
RMI—an acronym for Remote Method Invocation. RMI is a mechanism for invoking
instance methods on objects located on remote virtual machines (i.e. a virtual
machine other than that of the invoker).
Glossary
279
ROM (read-only memory)—used for storing the fixed program of the card. No
power is needed to hold data in this kind of memory. It cannot be written to after the
card is manufactured. A smart card's ROM contains operating system routines as
well as permanent data and user applications. Writing a binary image to the ROM is
called masking. It occurs during the chip manufacturing process.
runtime environment—see JCRE.
shareable interface—defines a set of shared interface methods. These interface
methods can be invoked from an applet in one context when the object
implementing them is owned by an applet in another context.
shareable interface object (SIO)—an object that implements the shareable interface.
smart card—a card which stores and processes information through the electronic
circuits embedded in silicon in the substrate of its body. Unlike magnetic stripe
cards, smart cards carry both processing power and information. They do not
require access to remote databases at the time of a transaction.
terminal—a Card Acceptance Device that is typically a computer in its own right
and can integrate a card reader as one of its components. In addition to being a
smart card reader, a terminal can process data exchanged between itself and the
smart card.
thread—the basic unit of program execution. A process can have several threads
running concurrently each performing a different job, such as waiting for events or
performing a time consuming job that the program doesn't need to complete before
going on. When a thread has finished its job, the thread is suspended or destroyed.
The Java Card virtual machine can support only a single thread of execution. Java
Card programs cannot use class Thread or any of the thread-related keywords in
the Java programming language.
transaction—an atomic operation in which the developer defines the extent of the
operation by indicating in the program code the beginning and end of the
transaction.
transient object—the state of transient objects do not persist from one CAD session
to the next, and are reset to a default state at specified intervals. Updates to the
values of transient objects are not atomic and are not affected by transactions.
verification—a process performed on a CAP file which ensures that the binary
representation of the package is structurally correct.
word—an abstract storage unit. A word is large enough to hold a value of type byte,
short, reference or returnAddress. Two words are large enough to hold a value of
integer type.
280
Java CardÔ 2.2 Virtual Machine Specification • June, 2002
Index
athrow 151
attribute 65
attributes 19, 65
A
aaload 140
aastore 141
abstract 11
AbstractMethodError 25
access control 9
remote interfaces 16
aconst_null 143
AID 37
AID-based naming 37
aload 144
aload_ 145
anewarray 146
applet 3
mulitselectable 16
applet component 77
applet firewall 5
application identifier
See AID
areturn 147
ArithmeticException 24
ArrayIndexOutOfBoundsException 24
arraylength 148
arrays 11, 14, 49, 67
ArrayStoreException 24
astore 149
astore_<n> 150
B
baload 152
bastore 153
big-endian 30
binary compatibility 45
binary file formats 30
binary representation 35
bipush 154
bitfield structures 67
boolean 11, 27
break 11
bspush 155
byte 11, 27
bytecode 20
C
CAP 3
CAP file 35
CAP file format 67
case 11
catch 11
char 9
checkcast 156
281
class 12, 57
in a package 13
initialization 15
initialization methods 30
instances 14
object 12
remote 16
throwable 12
unsupported 10
class 11
class component 86, 88
class file 17, 35
class_debug_info 126
class_descriptor_info 118
class_info 92
ClassCastException 24
ClassCirculatoryError 25
ClassFile 18
ClassFormatError 25
ClassNotFoundException 23
classsystem 10
CloneNotSupportedException 23
cloning 9
compatibility 45
components 68
applet 77
class 86, 88
constant pool 81
debug 125
defining 70
descriptor 117
directory 75
export 114
header 72
import 80
installation 70
method 101
reference location 111
static field 107
constant pool 18, 19
constant pool component 81
CONSTANT_Classref 55, 83
CONSTANT_InstanceFieldref 84
CONSTANT_Integer 56
CONSTANT_Package 54
constant_pool 53
282
Java Card 2.2 Virtual Machine Specification • June, 2002
CONSTANT_StaticFieldref 86
CONSTANT_StaticMethodref 86
CONSTANT_SuperMethodref 84
CONSTANT_Utf8 structure 56
CONSTANT_VirtualMethodref 84
context 28
current 29
owning 29
context switch 29
continue 11
converted applet
See CAP
current context 29
D
data type 27
integer 12
debug component 125
default 11
deletion 12
descriptor component 117
directory component 75
do 11
double 9
dup 159
dup_x 160
dup2 161
dynamic class loading 8
dynamic object creation 10
E
else 11
errors 25, 136
exception_handler_info 103
ExceptionInInitializerError 25
exceptions 11, 22, 30, 137
checked 23
uncatchable 23
uncaught 23
export component 114
export file 3, 35
conversion 40
export file format 36, 49
name 50
ownership 50
structure 51
extends 11
externally visible items 39
F
field_debug_info 128
field_descriptor_info 119
fields 18, 19, 61
descriptors 17, 18
static 14
file formats
Java Card 35
final 11
finalization 8
finally 11
float 9
for 11
frames 29
G
garbage collection 28
getfield_<t> 162
getfield_<t>_this 164
getfield_<t>_w 166
getstatic_<t> 168
goto 11, 169
goto_w 170
H
header component 72
heap 28
high bit 67
I
i2b 171
i2s 172
iadd 173
iaload 174
iand 175
iastore 176
icmp 177
iconst_<i> 178
idiv 179
if 11, 184
if<cond>_w 185
if_acmp 180
if_acmp<cond>_w 181
if_scmp 182
if_scmp<cond>_w 183
ifnonnull 186
ifnonnull_w 187
ifnull 188
ifnull_w 189
iinc 190
iinc_w 191
iipush 192
IllegalAccessError 25
IllegalAccessException 23
IllegalArgumentException 24
IllegalMonitorStateException 24
IllegalStateException 24
IllegalThreadStateException 24
iload 193
iload_<n> 194
ilookupswitch 195
implements 11
import 11
import component 80
imul 197
IncompatibleClassChangeError 25
IndexOutOfBoundsException 24
ineg 198
initialization 29
class 15
installation 41, 70
instance initialization methods 29
Index
283
instanceof 11, 199
instances 14
InstantiationError 25
InstantiationException 23
instruction set 30, 135
sample 138
instructions
by opcode mnemonic 270
by opcode value 268
int 11, 27
integer data type 12
interface 11
interface initialization methods 30
interface_info 92
interfaces 11, 14, 57
remote 16
InternalError 25
InterruptedException 23
invokeinterface 201
invokespecial 203
invokestatic 205
invokevirtual 206
ior 208
irem 209
ireturn 210
ishl 211
ishr 212
istore 213
istore_<n> 214
isub 215
itableswitch 216
items 49, 67
iushr 218
ixor 219
J
JAR files 36, 50, 69
Java Card applet
See applet
Java Card Converter 3
Java Card file formats 35
Java Card Remote Method Invocation
284
Java Card 2.2 Virtual Machine Specification • June, 2002
See JCRMI
Java Card system 2
Java Card Virtual Machine 2, 31
limitations 13
Java Card Virtual Machine errors 136
Java Card Virtual Machine instruction set 135
Java programming language 7
unsupported features 8
Java Virtual Machine 7, 17
JCRE context 29
JCRMI 16
parameters 17
return values 17
jsr 220
K
keywords 9, 11
L
ldc 21
ldc_w 21
library package 3
LinkageError 25
linking 39, 41, 47
long 9
lookupswitch 22
M
method component 101
method descriptors 18
method_debug_info 130
method_descriptor_info 121
method_info 105
methods 14, 15, 18, 19, 63
static 14
virtual 11, 43
mnemonic 138
multiselectable applets 16
must 135
N
naming 37
native 9
NegativeArraySizeException 24
new 11, 221
newarray 222
NoClassDefFoundError 25
nop 223
NoSuchFieldError 25
NoSuchFieldException 23
NoSuchMethodError 25
NoSuchMethodException 23
NullPointerException 24
NumberFormatException 24
numeric types 27
O
object 12
objects 11, 14
deletion mechanism 12
dynamic creation 10
representation of 29
opcode mnemonic 270
opcode value 268
opcodes 30
reserved 136
operands 30
OutOfMemoryError 25
owning context 29
P
package 10
applet 3
classes 13
library 3
name 13
references 13
versions 47
package 11
parameters 17
PIX 38
pop 224
pop2 225
primitive types 27
primitive values
values
primitive 27
private 11
proprietary identifier extension
See PIX
protected 11
public 11
putfield_<t> 226
putfield_<t>_this 228
putfield_<t>_w 230
putstatic_<t> 232
R
reference location component 111
reference types 27
reference types 27
reference values 27
references
external 40
internal 40
remote classes 16
remote interfaces 16
access control 16
reserved opcodes 136
resident image 47
resource identifier
See RID
ret 234
return 11, 235
return values 17
RID 38
RMI
See JCRMI
runtime data areas 28
runtime exceptions
exceptions
runtime 24
Index
285
S
s2b 236
s2i 237
sadd 238
saload 239
sand 240
sastore 241
sconst_<s> 242
sdiv 243
security 4
exceptions 137
manager 8
SecurityException 24
short 11, 27
sinc 244
sinc_w 245
sipush 246
sload 247
sload_<n> 248
slookupswitch 249
smul 251
sneg 252
sor 253
srem 254
sreturn 255
sshl 256
sshr 257
sspush 258
sstore 259
sstore_<n> 260
ssub 261
stableswitch 262
StackOverflowError 25
static 11
static field component 107
static field image 107
static fields 14
static methods 14
strictfp 9
StringIndexOutOfBoundsException 24
super 11
sushr 263
swap_x 264
286
Java Card 2.2 Virtual Machine Specification • June, 2002
switch 11
switch statements 15
sxor 265
synchronized 9
system 10
T
tables 49, 67
tableswitch 22
this 11
ThreadDeath 25
threads 8, 28
throw 11
throwable 12
throws 11
token-based linking 39
tokens
assignment 41
class 42
details 41
instance field 43
interface methods 44
package 42
private 39
public 39
static field 42
static method 42
virtual method 44
transient 9
try 11
type_descriptor 90
type_descriptor_info 123
types 11, 31
boolean 27
numeric 27
primitive 27
reference 27
reference 27
unsupported 9
U
union notation 67
UnknownError 25
UnsatisfiedLinkError 25
V
values
reference 27
VerifyError 25
virtual methods 11, 43
VirtualMachineError 25
void 11
volatile 9
W
while 11
wide 22
words 28
Index
287
288
Java Card 2.2 Virtual Machine Specification • June, 2002
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement