Jigsaw module-file format DRAFT

Mark Reinhold
2010/1/20 09:33 -0800 [4]

Copyright 2010 Sun Microsystems, Inc. · All Rights Reserved

Goals

• Optimized for streamed reading, from beginning to end. Random access should not be required when reading a module file, though it can be required when writing.

• Content-specific compression: Pack200+gzip/lzma for classes, bzip2 for native code, etc.

• Independent of any specific installed-module format or target-filesystem capability.

Layout

A module file has the following sections, in the order listed.

The first two sections are required:

• Header – Magic number, format version, sizes, overall hash
• module-info.class (never compressed, so as to be easily readable by tools)

The remaining sections are optional:

• Classes (excluding module-info.class)
• Resources
• Native libraries
• Native launchers
• Configuration (i.e., properties) files

Module file header

ModuleFileHeader {
  u4 magic;                 // FileConstants.MAGIC
  u2 type;                  // FileConstants.Type.MODULE_FILE
  u2 major;                 // FileConstants.ModuleFile.MAJOR_VERSION
  u2 minor;                 // FileConstants.ModuleFile.MINOR_VERSION
  u8 csize;                 // Size of entire file, compressed
  u8 usize;                 // Space required for uncompressed contents
                            //   (upper bound; need not be exact)
  u2 sections;              // Number of following sections
  u2 hashType;              // One of FileConstants.ModuleFile.HashType
                            //   (applies to all hashes in this file)
  u2 hashLength;            // Length of following hash
  b* hash;                  // Hash of entire file (except this hash)
}

All integers are in network byte order.

Sections

Each section (except the initial file header) has a header, which is then followed by the section’s content:

SectionHeader {
  u2 type;                  // One of FileConstants.ModuleFile.SectionType
  u2 compressor;            // One of FileConstants.ModuleFile.Compressor
  u4 csize;                 // Size of section content, compressed
  u2 subsections;           // Number of following subsections
  u2 hashLength;            // Length of following hash
  b* hash;                  // Hash of section content
}

Compression is only relevant to section content; it never applies to the headers defined here.

The subsection count is zero for sections that contain only one entity, i.e., module-info, classes, and hash sections. The subsection count is non-zero for sections that contain multiple entities, i.e., resources, native code, and config sections.

Subsections

If a section has subsections then each subsection has its own header. At the moment only file subsections are defined:

SubSectionFileHeader {
  u2 type;                  // FileConstants.ModuleFile.SubSectionType.FILE
  u4 csize;                 // Size of file, compressed
  u2 pathLength;            // Length of path name, in bytes
  b* path;                  // Path name, in Java-modified UTF-8
}

The ‘/’ character separates nested directories in path names. The module installer must transpose this to a different character, if needed, to suit the host system.

Path names are relative to an unspecified installation directory. Absolute path names, i.e., those starting with a separator, are not permitted. The path names of native-code files must not include more than one element.

There is no mode field on files within a section. The module installer must set the local mode as appropriate; it must, e.g., make native-code files executable as required by the host system.

Layout grammar

ModuleFileHeader
SectionHeader(MODULE_INFO) [module-info data]
(SectionHeader(CLASSES) [class data])?
(SectionHeader(RESOURCES) (SubSectionFileHeader [file data])+)?
(SectionHeader(NATIVE_LIBS) (SubSectionFileHeader [file data])+)?
(SectionHeader(NATIVE_CMDS) (SubSectionFileHeader [file data])+)?
(SectionHeader(CONFIG) (SubSectionFileHeader+ [file data])+)?

Open issues

• Signing: Should module files carry their own digital-signature information, as jar files do today, or should such information be provided elsewhere?

Changes

Version 4:

• Moved hash type and overall file hash to the file header

• Added per-section hashes

• Removed per-section uncompressed sizes

• Added subsection count to section headers

• Added layout grammar

SEARCH:

Related searches:
module section native header required

gipoco.com is neither affiliated with the authors of this page or responsible
for its contents. This is a safe-cache copy of the original web site.

gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.