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 platform 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.

5.1 Export File Name

As described in Section 4.1.1 "Export File Format”, 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 Section 4.1.3 "JAR File Container”, 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.

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

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 magic item contains the magic number identifying the ExportFile format; it has the value 0x00FACADE.

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 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.

The constant_pool_count item is a non-zero, positive value that indicates the number of constants in the 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 variable-length structure whose format is indicated by its first “tag” byte.

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 (Section 5.6.1 "CONSTANT_Package”) structure representing the package defined by this ExportFile.

The value of the export_class_count item gives the number of elements in the classes table.

Each value of the classes table is a variable-length class_info structure (Section 5.7 "Classes and Interfaces”) 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 (Section 5.6.1 "CONSTANT_Package”) 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

5.6 Constant Pool

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 14. 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.

TABLE 14 – Export file constant pool tags
Constant Type	Value
`CONSTANT_Package`	`13`
`CONSTANT_Classref`	`7`
`CONSTANT_Integer`	`3`
`CONSTANT_Utf8`	`1`

5.6.1 CONSTANT_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 flags item is a mask of modifiers that apply to this package. The flags modifiers are shown in the following table.

TABLE 15 – Export file package flags
Flags	Value
`ACC_LIBRARY`	`0x01`

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.2 A shareable interface is either the javacard.framework.Shareable interface or an interface that extends the javacard.framework.Shareable interface.

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.

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 Section 4.5 "Package Versions” for a description of assigning and using package version numbers.

The value of the aid_length item gives the number of bytes in the aid array. Valid values are between 5 and 16, inclusive.

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 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 (Section 5.6.4 "CONSTANT_Utf8”) 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 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 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.

5.6.4 CONSTANT_Utf8

The CONSTANT_Utf8_info structure is used to represent constant string values. UTF-8 strings are encoded in the same way as described in The Java‘ Virtual Machine Specification (§ 4.4.7).

CONSTANT_Utf8_info { 
     u1 tag 
     u2 length 
     u1 bytes[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.

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]

     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 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 following table.

TABLE 16 – Export file class access and modifier flags
Name	Value	Meaning	Used By
`ACC_PUBLIC`	`0x0001`	Is public; may be accessed from outside its package	Class, interface
`ACC_FINAL`	`0x0010`	Is final; no subclasses allowed.	Class
`ACC_INTERFACE`	`0x0200`	Is an interface	Interface
`ACC_ABSTRACT`	`0x0400`	Is abstract; may not be instantiated	Class, interface
`ACC_SHAREABLE`	`0x0800`	Is shareable; may be shared between Java Card applets.	Class, interface
`ACC_REMOTE`	`0x1000`	Is remote; may be accessed by Java Card RMI	Class, interface

The ACC_SHAREABLE flag indicates whether this class or interface is shareable.3 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 Section 2.2.6.1 "Remote Classes and Remote Interfaces”.

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.

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 (Section 5.6.2 "CONSTANT_Classref”) structure representing a valid, fully qualified Java class or interface name.

The value of the export_supers_count item indicates the number of entries in the supers array.

The supers array contains an entry for each public superclass of this class or interface. It does not include package visible superclasses.

For a class, 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 structure (Section 5.6.2 "CONSTANT_Classref”) representing a valid, fully-qualified Java class name. Entries in the supers array can occur in any order.

For an interface, the supers array contains a single value representing a valid index into the constant_pool table. The constant_pool entry must be a CONSTANT_Classref_info structure (Section 5.6.2 "CONSTANT_Classref”) representing the fully-qualified name of the java.lang.Object class.

The value of the export_interfaces_count item indicates the number of entries in the interfaces array.

If this class_info structure describes a class, the interfaces array contains an entry for each public interface implemented by this class. It does not include package-visible interfaces. It does include all public superinterfaces in the hierarchies of public interfaces implemented by this class.

If this class_info structure describes an interface, the interfaces array contains an entry for each public interface extended by this interface. It does not include package visible interfaces. It does include all public superinterfaces in the hierarchies of public interfaces extended by this 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 structure (Section 5.6.2 "CONSTANT_Classref”) representing a valid, fully-qualified Java interface name. Entries in the interfaces array can occur in any order.

The value of the export_fields_count item gives the number of entries in the fields table.

Each value in the fields table is a variable-length field_info (Section 5.8 "Fields”) 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.

The value of the export_methods_count item gives the number of entries in the methods table.

Each value in the methods table is a method_info (Section 5.9 "Methods”) structure. The 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.

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 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.4

If this field is static, but is not a compile-time constant, the token item represents a static field token (Section 4.3.7.3 "Static Fields”).

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.

TABLE 17 – Export file field access and modifier flags
Name	Value	Meaning	Used By
`ACC_PUBLIC`	`0x0001`	Is public; may be accessed from outside its package.	Any field
`ACC_PROTECTED`	`0x0004`	Is protected; may be accessed within subclasses.	Class field Instance field
`ACC_STATIC`	`0x0008`	Is static.	Class field Interface field
`ACC_FINAL`	`0x0010`	Is final; no further overriding or assignment after initialization.	Any field

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.

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 (Section 5.6.4 "CONSTANT_Utf8”) structure representing a valid Java field name stored as a simple (not fully qualified) name, that is, as a Java identifier.

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 (Section 5.6.4 "CONSTANT_Utf8”) 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).

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 (Section 5.10.1 "ConstantValue Attribute”). 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.

The only attribute defined for the attributes table of a field_info structure by this specification is the ConstantValue attribute (Section 5.10.1 "ConstantValue Attribute”). 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 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 (Section 4.3.7.4 "Static Methods and Constructors”). If this method is a virtual method, the token item represents a virtual method token (Section 4.3.7.6 "Virtual Methods”). If this method is an interface method, the token item represents an interface method token (Section 4.3.7.7 "Interface Methods”).

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.

TABLE 18 – Export file method access and modifier flags
Name	Value	Meaning	Used By
`ACC_PUBLIC`	`0x0001`	Is public; may be accessed from outside its package.	Any method
`ACC_PROTECTED`	`0x0004`	Is protected; may be accessed within subclasses.	Class/instance method
`ACC_STATIC`	`0x0008`	Is static.	Class/instance method
`ACC_FINAL`	`0x0010`	Is final; no further overriding or assignment after initialization.	Class/instance method
`ACC_ABSTRACT`	`0x0400`	Is abstract; no implementation is provided	Any method

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.

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 (Section 5.6.4 "CONSTANT_Utf8”) 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.

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 (Section 5.6.4 "CONSTANT_Utf8”) structure representing a valid Java method descriptor.

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 (Section 4.3.3 "The Export File and Conversion”).

5.10 Attributes

Attributes are used in the field_info (Section 5.8 "Fields”) 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.

ConstantValue_attribute { 
     u2 attribute_name_index 
     u4 attribute_length 
     u2 constantvalue_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 (Section 5.6.4 "CONSTANT_Utf8”) structure representing the string “ConstantValue.”

The value of the attribute_length item of a ConstantValue_attribute structure must be 2.

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.

Chapter 5