Objects are key to understanding object-oriented technology. Look around right now and you’ll find many examples of real-world objects: your dog, your desk, your television set, your bicycle.

Real-world objects share two characteristics: They all have state and behavior. Dogs have state (name, color, breed, hungry) and behavior (barking, fetching, wagging tail). Bicycles also have state (current gear, current pedal cadence, current speed) and behavior (changing gear, changing pedal cadence, applying brakes). Identifying the state and behavior for real-world objects is a great way to begin thinking in terms of object-oriented programming.

Take a minute right now to observe the real-world objects that are in your immediate area. For each object that you see, ask yourself two questions: “What possible states can this object be in?” and “What possible behavior can this object perform?”. Make sure to write down your observations. As you do, you’ll notice that real-world objects vary in complexity; your desktop lamp may have only two possible states (on and off) and two possible behaviors (turn on, turn off), but your desktop radio might have additional states (on, off, current volume, current station) and behavior (turn on, turn off, increase volume, decrease volume, seek, scan, and tune). You may also notice that some objects, in turn, will also contain other objects. These real-world observations all translate into the world of object-oriented programming.

A software object.

Software objects are conceptually similar to real-world objects: they too consist of state and related behavior. An object stores its state in fields (variables in some programming languages) and exposes its behavior through methods (functions in some programming languages). Methods operate on an object’s internal state and serve as the primary mechanism for object-to-object communication. Hiding internal state and requiring all interaction to be performed through an object’s methods is known as data encapsulation — a fundamental principle of object-oriented programming.

Consider a bicycle, for example:

A bicycle modeled as a software object.

By attributing state (current speed, current pedal cadence, and current gear) and providing methods for changing that state, the object remains in control of how the outside world is allowed to use it. For example, if the bicycle only has 6 gears, a method to change gears could reject any value that is less than 1 or greater than 6.

Bundling code into individual software objects provides a number of benefits, including:

1. Modularity: The source code for an object can be written and maintained independently of the source code for other objects. Once created, an object can be easily passed around inside the system.
   



2. Information-hiding: By interacting only with an object’s methods, the details of its internal implementation remain hidden from the outside world.
   



3. Code re-use: If an object already exists (perhaps written by another software developer), you can use that object in your program. This allows specialists to implement/test/debug complex, task-specific objects, which you can then trust to run in your own code.
   



4. Pluggability and debugging ease: If a particular object turns out to be problematic, you can simply remove it from your application and plug in a different object as its replacement. This is analogous to fixing mechanical problems in the real world. If a bolt breaks, you replace it, not the entire machine.

Any set of packages or classes can easily be made to play the role of an extension. The first step in turning a set of classes into an extension is to bundle them in a JAR file. Once that’s done, you can turn the software into an extension in two ways:

• by placing the JAR file in a special location in the directory structure of the Java Runtime Environment, in which case it’s called an installed extension.


• by referencing the JAR file in a specified way from the manifest of the another JAR file, in which case it’s called a download extension.

This lesson shows you how the extension mechanism works by using a simple “toy” extension as an example.

Installed Extensions

In this section, you’ll create a simple installed extension and see how extension software is treated as part of the platform by the runtime environment.

Download Extensions

This section will show you how modify a JAR file’s manifest so that the JAR-bundled software can make use of download extensions.

Understanding Extension Class Loading

This section is a short detour that summarizes the Java platform’s delegation model for loading classes, and shows how it relates to loading classes in extensions.

The extension framework makes use of the class-loading delegation mechanism. When the runtime environment needs to load a new class for an application, it looks for the class in the following locations, in order:

1. Bootstrap classes: the runtime classes in rt.jar, internationalization classes in i18n.jar, and others.


2. Installed extensions: classes in JAR files in the lib/ext directory of the JRE, and in the system-wide, platform-specific extension directory (such as /usr/jdk/packages/lib/ext on the Solaris^TM Operating System, but note that use of this directory applies only to Java^TM 6 and later).


3. The class path: classes, including classes in JAR files, on paths specified by the system property java.class.path. If a JAR file on the class path has a manifest with the Class-Path attribute, JAR files specified by the Class-Path attribute will be searched also. By default, the java.class.path property’s value is ., the current directory. You can change the value by using the -classpath or -cp command-line options, or setting the CLASSPATH environment variable. The command-line options override the setting of the CLASSPATH environment variable.

The precedence list tells you, for example, that the class path is searched only if a class to be loaded hasn’t been found among the classes in rt.jar, i18n.jar or the installed extensions.

Unless your software instantiates its own class loaders for special purposes, you don’t really need to know much more than to keep this precedence list in mind. In particular, you should be aware of any class name conflicts that might be present. For example, if you list a class on the class path, you’ll get unexpected results if the runtime environment instead loads another class of the same name that it found in an installed extension.

The Java Class Loading Mechanism

The Java platform uses a delegation model for loading classes. The basic idea is that every class loader has a “parent” class loader. When loading a class, a class loader first “delegates” the search for the class to its parent class loader before attempting to find the class itself.

Here are some highlights of the class-loading API:

• Constructors in java.lang.ClassLoader and its subclasses allow you to specify a parent when you instantiate a new class loader. If you don’t explicitly specify a parent, the virtual machine’s system class loader will be assigned as the default parent.


• The loadClass method in ClassLoader performs these tasks, in order, when called to load a class:
  
  
  
  1. If a class has already been loaded, it returns it.
  
  
  2. Otherwise, it delegates the search for the new class to the parent class loader.
  
  
  3. If the parent class loader does not find the class, loadClass calls the method findClass to find and load the class.


• The findClass method of ClassLoader searches for the class in the current class loader if the class wasn’t found by the parent class loader. You will probably want to override this method when you instantiate a class loader subclass in your application.


• The class java.net.URLClassLoader serves as the basic class loader for extensions and other JAR files, overriding the findClass method of java.lang.ClassLoader to search one or more specified URLs for classes and resources.

To see a sample application that uses some of the API as it relates to JAR files, see the Using JAR-related APIs lesson in this tutorial.

Class Loading and the java Command

The Java platform’s class-loading mechanism is reflected in the java command.

• In the java tool, the -classpath option is a shorthand way to set the java.class.path property.


• The -cp and -classpath options are equivalent.


• The -jar option runs applications that are packaged in JAR files. For a description and examples of this option, see the Running JAR-Packaged Software lesson in this tutorial.

Installed extensions are JAR files in the lib/ext directory of the Java Runtime Environment (JRE^TM) software. As its name implies, the JRE is the runtime portion of the Java Development Kit containing the platform’s core API but without development tools such as compilers and debuggers. The JRE is available either by itself or as part of the Java Development Kit.

As of the Java 1.2 platform, the JRE is a strict subset of the JDK^TM software. A subset of the JDK software directory tree looks like this:

The JRE consists of those directories within the highlighted box in the diagram. Whether your JRE is stand-alone or part of the JDK software, any JAR file in the lib/ext of the JRE directory is automatically treated by the runtime environment as an extension.

Since installed extensions extend the platform’s core API, use them judiciously. They are rarely appropriate for interfaces used by a single, or small set of applications.

Furthermore, since the symbols defined by installed extensions will be visible in all Java processes, care should be taken to ensure that all visible symbols follow the appropriate “reverse domain name” and “class hierarchy” conventions. For example, com.mycompany.MyClass.

As of Java 6, extension JAR files may also be placed in a location that is independent of any particular JRE, so that extensions can be shared by all JREs that are installed on a system. Prior to Java 6, the value of java.ext.dirs referred to a single directory, but as of Java 6 it is a list of directories (like CLASSPATH) that specifies the locations in which extensions are searched for. The first element of the path is always the lib/ext directory of the JRE. The second element is a directory outside of the JRE. This other location allows extension JAR files to be installed once and used by several JREs installed on that system. The location varies depending on the operating system:

• Solaris^TM Operating System: /usr/jdk/packages/lib/ext


• Linux: /usr/java/packages/lib/ext


• Microsoft Windows: %SystemRoot%\Sun\Java\lib\ext

Note that an installed extension placed in one of the above directories extends the platform of each of the JREs (Java 6 or later) on that system.

A Simple Example

Let’s create a simple installed extension. Our extension consists of one class, RectangleArea, that computes the areas of rectangles:

public final class RectangleArea {

    public static int area(java.awt.Rectangle r) {

        return r.width * r.height;

    }

}

This class has a single method, area, that takes an instance of java.awt.Rectangle and returns the rectangle’s area.

Suppose that you want to test RectangleArea with an application called AreaApp:

import java.awt.*;

public class AreaApp {

    public static void main(String[] args) {

        int width = 10;

        int height = 5;
        Rectangle r = new Rectangle(width, height);

        System.out.println(“The rectangle’s area is ”

                           + RectangleArea.area(r));

    }

}

This application instantiates a 10 x 5 rectangle, and then prints out the rectangle’s area using the RectangleArea.area method.

Running AreaApp Without the Extension Mechanism

Let’s first review how you would run the AreaApp application without using the extension mechanism. We’ll assume that the RectangleArea class is bundled in a JAR file named area.jar.

The RectangleArea class is not part of the Java platform, of course, so you would need to place the area.jar file on the class path in order to run AreaApp without getting a runtime exception. If area.jar was in the directory /home/user, for example, you could use this command:

java -classpath .:/home/user/area.jar AreaApp

The class path specified in this command contains both the current directory, containing AreaApp.class, and the path to the JAR file containing the RectangleArea package. You would get the desired output by running this command:

The rectangle’s area is 50

Running AreaApp by Using the Extension Mechanism

Now let’s look at how you would run AreaApp by using the RectangleArea class as an extension.

To make the RectangleArea class into an extension, you place the file area.jar in the lib/ext directory of the JRE. Doing so automatically gives the RectangleArea the status of being an installed extension.

With area.jar installed as an extension, you can run AreaApp without needing to specify the class path:

java AreaApp

Because you’re using area.jar as an installed extension, the runtime environment will be able to find and to load the RectangleArea class even though you haven’t specified it on the class path. Similarly, any applet or application being run by any user on your system would be able to find and use the RectangleArea class.

If there are multiple JREs (Java 6 or later) installed on a system and want the RectangleArea class to be available as an extension to all of them, instead of installing it in the lib/ext directory of a particular JRE, install it in the system-wide location. For example, on system running Linux, install area.jar in the directory /usr/java/packages/lib/ext. Then AreaApp can run using different JREs that are installed on that system, for example if different browsers are configured to use different JREs.

JAR (Java Archive) is a platform-independent file format that aggregates many files into one. Multiple Java applets and their requisite components (.class files, images and sounds) can be bundled in a JAR file and subsequently downloaded to a browser in a single HTTP transaction, greatly improving the download speed. The JAR format also supports compression, which reduces the file size, further improving the download time. In addition, the applet author can digitally sign individual entries in a JAR file to authenticate their origin. It is fully extensible.

Overview and Specification

• Overview – An overview of JAR Files


• Specification – The JAR File Specification

API Specification

• java.util.jar Package


• java.net.JarURLConnection

Tutorials and Programmer’s Guides

• A tutorial introduction to JAR files.

Enhancements

• Enhancements in JDK^TM 6 – An annotated list of changes between the 5.0 and 6.0 releases to APIs, the jar command, and the jar/zip implementation.

 This page summarizes enhancements to the jar and zip support provided in JDK 6.

API changes

Two new compressed streams have been added:

• java.util.zip.DeflaterInputStream: Data read from this stream is compressed.


• java.util.zip.InflaterOutputStream: Data written to this stream is decompressed.

For example, these can be useful if a client wants to send compressed data over a network. The data can be compressed into packets with DeflaterInputStream, and those packets written over the network connection. The receiving end then reads the compressed packets from the network connection, and decompresses them by writing to an InflaterOutputStream.

Implementation changes

On all platforms, zip files can contain more than 64k entries.

On Windows, some limitations have been removed:

• File names longer than 256 characters are now supported.


• The limitation of just over 2,000 simultaneously open zip files has been removed.

Changes to the jar command

There are two changes to the behavior of the jar command:

• The timestamps of extracted files are those listed in the archive, instead of the time of extraction.


• When creating a jar, it is possible to specify the entry point for stand-alone applications bundled into an executable jar file. The ‘e’ option specifies the application entry point by creating or overriding the Main-Class attribute value in the jar file’s manifest.

Contents

• Introduction
  
• The META-INF directory
  
• Name-Value pairs and Sections
  
• JAR Manifest
  
• 
  
  
  
  • Overview
    
  • Manifest Specification
    
  • Main Attributes
    
  • Per-Entry Attributes
  
  
• Signed JAR file
  
• 
  
  
  
  • Overview
    
  • Signature File
    
  • 
    
    
    
    • Signature validation
      
    • The Magic Attribute
    
    
  • Digital Signatures
  
  
• Notes on Manifest and Signature Files
  
• JAR Index
  
• 
  
  
  
  • Overview
    
  • Index File Specification
    
  • Backward Compatibility
  
  
• Service Provider
  
• 
  
  
  
  • Overview
    
  • Provider Configuration File
    
  • Example
  
  
• API Details
  
• See Also

Introduction

JAR file is a file format based on the popular ZIP file format and is used for aggregating many files into one. A  JAR file is essentially a zip file that contains an optional META-INF directory. A JAR file can be created by the command-line jar tool, or by using the  java.util.jar API in the Java platform. There is no restriction on the name of a JAR file, it can be any legal file name on a particular platform.

In many cases, JAR files are not just simple archives of java classes files and/or resources. They are used as building blocks for applications and extensions. The META-INF directory, if it exists, is used to store package and extension configuration data, including security, versioning, extension and services.

The META-INF directory

The following files/directories in the META-INF directory are recognized and interpreted by the Java 2 Platform to configure applications, extensions, class loaders and services:

• MANIFEST.MF

The manifest file that is used to define extension and package related data.

• INDEX.LIST

This file is generated by the new “-i” option of the jar tool, which contains location information for packages defined in an application or extension.  It is part of the JarIndex implementation and used by class loaders to speed up their class loading process.

• x.SF

The signature file for the JAR file.  `x` stands for the base file name.

• x.DSA

The signature block file associated with the signature file with the same base file name. This file stores the digital signature of the corresponding signature file.

• services/

This directory stores all the service provider configuration files.

Name-Value pairs and Sections

Before we go to the details of the contents of the individual configuration files, some format convention needs to be defined. In most cases, information contained within the manifest file and signature files is represented as so-called “name: value” pairs inspired by the RFC822 standard.  We also call these pairs headers or attributes.

Groups of name-value pairs are known as a “section”. Sections are separated from other sections by empty lines.

Binary data of any form is represented as base64. Continuations are required for binary data which causes line length to exceed 72 bytes. Examples of binary data are digests and signatures.

Implementations shall support header values of up to 65535 bytes.

All the specifications in this document use the same grammar in which terminal symbols are shown in fixed width font and non-terminal symbols are shown in italic type face.

Specification:

  section:                       *header +newline
  nonempty-section:      +header +newline
  newline:                      CR LF | LF | CR (not followed by LF)
  header:                       name : value
  name:                         alphanum *headerchar
  value:                          SPACE *otherchar newline *continuation
  continuation:              SPACE *otherchar newline
  alphanum:                  {A-Z} | {a-z} | {0-9}
  headerchar:                alphanum | – | _
  otherchar:                  any UTF-8 character except NUL, CR and LF

; Also: To prevent mangling of files sent via straight e-mail, no
; header will start with the four letters “From”.
 

Non-terminal symbols defined in the above specification will be referenced in the following specifications.

JAR Manifest

Overview

A JAR file manifest consists of a main section followed by a list of sections for individual JAR file entries, each separated by a newline. Both the main section and individual sections follow the section syntax specified above. They each have their own specific restrictions and rules.

The main section contains security and configuration information about the JAR file itself, as well as the application or extension that this JAR file is a part of. It also defines main attributes that apply to every individual manifest entry.  No attribute in this section can have its name equal to  “Name“. This section is terminated by an empty line.

The individual sections define various attributes for packages or files contained in this JAR file. Not all files in the JAR file need to be listed in the manifest as entries, but all files which are to be signed must be listed. The manifest file itself must not be listed.  Each section must start with an attribute with the name as “Name“, and the value must be a relative path to the file, or an absolute URL referencing data outside the archive.

If there are multiple individual sections for the same file entry, the attributes in these sections are merged. If a certain attribute have different values in different sections, the last one is recognized.

Attributes which are not understood are ignored. Such attributes may include implementation specific information used by applications.

Manifest Specification:

  manifest-file:                    main-section newline *individual-section
  main-section:                    version-info newline *main-attribute
  version-info:                      Manifest-Version : version-number
  version-number :               digit+{.digit+}*
  main-attribute:                 (any legitimate main attribute) newline
  individual-section:             Name : value newline *perentry-attribute
  perentry-attribute:            (any legitimate perentry attribute) newline
  newline :                            CR LF | LF | CR (not followed by LF)
   digit:                                {0-9} 

In the above specification, attributes that can appear in the main section are referred to as main attributes, whereas attributes that can appear in individual sections are referred to as per-entry attributes. Certain attributes can appear both in the main section and the individual sections, in which case the per-entry attribute value overrides the main attribute value for the specified entry. The two types of attributes are defined as follows.
 

Main Attributes

Main attributes are the attributes that are present in the main section of the manifest. They fall into the following different groups:

• general main attributes

• 
  
  
  
  • Manifest-Version:
  
  
  
  
  • Defines the manifest file version. The value is a legitimate version number, as described in the above spec.
     
    
  • Created-By:
    
  • 
    Defines the version and the vendor of the java implementation on top of which this manifest file is generated. This attribute is generated by the jar tool.
     
    
  • Signature-Version:
    
  • 
    Defines the signature version of the jar file. The value should be a valid version-number string.
     
    
  • Class-Path :
    
  • 
    The value of this attribute specifies the relative URLs of the extensions or libraries that this application or extension needs. URLs are separated by one or more spaces. The application or extension class loader uses the value of this attribute to construct its internal search path.
     
  
  
• attribute defined for stand-alone applications
  
• This attribute is used by stand-alone applications that are bundled into executable jar files which can be invoked by the java runtime directly by running “java -jar x.jar“.
  
  
  
  • Main-Class :
    
  • 
    The value of this attribute defines the relative path of the main application class which the launcher will load at startup time. The value must not have the .class extension appended to the class name.

• attributes defined for applets
  
• These attributes is used by an applet which is bundled into JAR files to define requirements, version and location information for the extensions which this applet depends on. (see  Extension Versioning ). 
  
  
  
  • Extension-List:
    
  • 
    This attribute indicates the extensions that are needed by the applet. Each extension listed in this attribute will have a set of additional attributes that the applet uses to specify which version and vendor of the extension it requires.
     
    
  • <extension>-Extension-Name :
    
  • 
    This attribute is the unique name of the extension. The Java Plug-in will compare the value of this attribute with the Extension-Name attribute in the manifests of installed extensions to determine if the extension is installed.
     
    
  • <extension>-Specification-Version
    
  • 
    This attribute specifies the minimum extension specification version that is required by the applet. The Java Plug-in will compare the value of this attribute with the Specification-Version attribute of the installed extension to determine if the extension is up to date.
     
    
  • <extension>-Implementation-Version
    
  • 
    This attritute specifies the minimum extension implementation version number that is required by the applet. The Java Plug-in will compare the value of this attribute with the Implementation-Version attribute of the installed extension to see if a more recent implementation needs to be downloaded.
     
    
  • <extension>-Implementation-Vendor-Id
    
  • 
    This attribute can be used to identify the vendor of an extension implementation if the applet requires an implementation from a specific vendor. The Java Plug-in will compare the value of this attribute with the Implementation-Vendor-Id attribute of the installed extension.
     
    
  • <extension>-Implementation-URL
    
  • 
    This attribute specifies a URL that can be used to obtain the most recent version of the extension if the required version is not already installed.
     
  
  
• attribute defined for extension identification
  
• This attribute is used by extensions to define their unique identity.
  
  
  
  • Extension-Name:
    
  • This attribute specifies a name for the extension contained in the Jar file. The name should be a unique identifier such as the name of the main package comprising the extension.
   
  
• attributes defined for extension and  package versioning  and sealing information
  
• These attributes define features of the extension which the JAR file is a part of. The value of these attributes apply to all the packages in the JAR file, but can be overridden by per-entry attributes. 
  
  
  
  • Implementation-Title :
    
  • The value is a string that defines the title of the extension implementation. 
    
  • Implementation-Version :
    
  • 
    The value is a string that defines the version of the extension implementation.
     
    
  • Implementation-Vendor :
    
  • 
    The value is a string that defines the organization that maintains the extension implementation.
     
    
  • Implementation-Vendor-Id :
    
  • 
    The value is a string id that uniquely defines the organization that maintains the  extension implementation.
     
    
  • Implementation-URL :
    
  • 
    This attribute defines the URL from which the extension implementation can be downloaded from.
     
    
  •  Specification-Title :
    
  • 
    The value is a string that defines the title of the extension specification.
     
    
  • Specification-Version :
    
  • 
    The value is a string that defines the version of the extension specification.
     
    
  • Specification-Vendor :
    
  • 
    The value is a string that defines the organization that maintains the extension specification.

Per-Entry Attributes

Per-entry attributes apply only to the individual JAR file entry to which the manifest entry is associated with.  If the same attribute also appeared in the main section, then the value of the per-entry attribute overwrites the main attribute`s value. For example, if JAR file a.jar has the following manifest content:
It means that all the packages archived in a.jar are sealed, except that package foo.bar is not.

The per-entry attributes fall into the following groups:

• attributes defined for file contents:
  
• 
  
  
  
  • Content-Type :
    
  • 
    This attribute can be used to specify the MIME type and subtype of data for a specific file entry in the JAR file. The value should be a string in the form of type/subtype. For example “image/bmp” is an image type with a subtype of bmp (representing bitmap). This would indicate the file entry as an image with the data stored as a bitmap. RFC 1521 and 1522 discuss and define the MIME types definition.

• attributes defined for package versioning and sealing information:
  
• 
  

  These are the same set of attributes defined above as main attributes that defines the extension package versioning and sealing information. When used as per-entry attributes, these attributes overwrites the main attributes but only apply to the individual file specified by the manifest entry.
   

  
  
• attribute defined for beans objects:
  
• 
  
  
  
  • Java-Bean:
    
  • 
    Defines whether the specific jar file entry is a Java Beans object or not. The value should be either “true” or “false”, case is ignored.
     
  
  
• attributes defined for signing:
  
• 
  These attributes are used for signing and verifying purposes. More details here.
  
  
  
  • x-Digest-y:
    
  • 
    The name of this attribute specifies the name of the digest algorithm used to compute the digest value for the corresponding jar file entry. The value of this attribute stores the actual digest value. The prefix `x` specifies the algorithm name and the optional suffix `y`  indicates to which language the digest value should be verified against.
    
  • Magic:
    
  • 
    This is an optional attribute that can be used by applications to indicate how verifier should compute the digest value contained in the manifest entry.  The value of this attribute is a set of comma separated context specific strings. Detailed description is here.

Signed JAR File

Overview

A JAR file can be signed by using the command line jarsigner tool or directly through the java.security API. Every file entry, including non-signature related files in the META-INF directory, will be signed if the JAR file is signed by the jarsigner tool. The signature related files are:

• META-INF/MANIFEST.MF
  
• META-INF/*.SF
  
• META-INF/*.DSA
  
• META-INF/*.RSA
  
• META-INF/SIG-*

Note that if such files are located in META-INF subdirectories, they are not considered signature-related. Case-insensitive versions of these filenames are reserved and will also not be signed.

Subsets of a JAR file can be signed by using the java.security API. A signed JAR file is exactly the same as the original JAR file, except that its manifest is updated and two additional files are added to the META-INF directory: a signature file and a signature block file. When jarsigner is not used, the signing program has to construct both the signature file and the signature block file.

For every file entry signed in the signed JAR file, an individual manifest entry is created for it as long as it does not already exist in the manifest. Each manifest entry lists one or more digest attribute and an optional Magic attribute.

Signature File

Each signer is represented by a signature file with extension .SF. The major part of the file is similar to the manifest file. It consists of a main section which includes information supplied by the signer but not specific to any particular jar file entry. The main section entry, x-Digest-Manifest-Main-Attributes (where x is a digest algorithm), contains the digest value for the main attributes of the manifest.

The main section is followed by a list of individual entries whose names must also be present in the manifest file. Each individual entry must contain at least the digest of its corresponding entry in the manifest file.

Paths or URLs appearing in the manifest file but not in the signature file are not used in the calculation.

Signature Validation

The signature over the signature file is first verified when the manifest is first parsed. For efficiency, this verification can be remembered. Note that this verification only validates the signature directions themselves, not the actual archive files.

The manifest main attributes are also verified when verification information is available in the signature file. If an x-Digest-Manifest-Main-Attributes entry exists in the signature file, it is compared against a digest calculated against the main attributes in the manifest file. If this calculation fails, then jar validation fails. This decision can be remembered, for efficiency. If an x-Digest-Manifest-Main-Attributes entry does not exist in the signature file, its nonexistence does not affect jar validation and the manifest main attributes are not verified.

To validate a file, a digest value in the signature file is compared against a digest calculated against the corresponding entry in the manifest file. Then, a digest value in the manifest file is compared against a digest calculated against the actual data referenced in the “Name:” attribute, which specifies either a relative file path or URL.

Example manifest file:

Manifest-Version: 1.0Created-By: 1.3 (Sun Microsystems, Inc) Name: common/class1.classMD5-Digest: (base64 representation of MD5 digest) Name: common/class2.classMD5-Digest: (base64 representation of MD5 digest)SHA-Digest: (base64 representation of SHA digest)

The corresponding signature file would be:

Signature-Version: 1.0MD5-Digest-Manifest-Main-Attributes: (base64 representation of MD5 digest) Name: common/class1.classMD5-Digest: (base64 representation of MD5 digest) Name: common/class2.classMD5-Digest: (base64 representation of MD5 digest)

The Magic Attribute

Another requirement to validate the signature on a given manifest entry is that the verifier understand the value or values of the Magic key-pair value in that entry`s manifest entry.

The Magic attribute is optional but it is required that a parser understand the value of an entry`s Magic key if it is verifying that entry`s signature.

The value or values of the Magic attribute are a set of comma-separated context-specific strings. The spaces before and after the commas are ignored. Case is ignored. The exact meaning of the magic attributes is application specific. These values indicate how to compute the hash value contained in the manifest entry, and are therefore crucial to the proper verification of the signature. The keywords may be used for dynamic or embedded content, multiple hashes for multilingual documents, etc.

Here are two examples of the potential use of Magic attribute in the manifest file:

               Name: http://www.scripts.com/index#script1
        SHA-Digest: (base64 representation of SHA hash)
        Magic: JavaScript, Dynamic

        Name: http://www.tourist.com/guide.html
        SHA-Digest: (base64 representation of SHA hash)
        SHA-Digest-French: (base64 representation of SHA hash)
        SHA-Digest-German: (base64 representation of SHA hash)
        Magic: Multilingual

In the first example, these Magic values may indicate that the result of an http query is the script embedded in the document, as opposed to the document itself, and also that the script is generated dynamically. These two pieces of information indicate how to compute the hash value against which to compare the manifest`s digest value, thus comparing a valid signature.

In the second example, the Magic value indicates that the document retrieved may have been content-negotiated for a specific language, and that the digest to verify against is dependent on which language the document retrieved is written in.

Digital Signatures

A digital signature is a signed version of the .SF signature file. These are binary files not intended to be interpreted by humans.

Digital signature files have the same filenames as the .SF files but different extensions. The extension varies depending on the type of digital signature.

.RSA      (PKCS7 signature, MD5 + RSA).DSA      (PKCS7 signature, DSA)

Digital signature files for signature algorithms not listed above must reside in the META-INF directory and have the prefix “SIG-“. The corresonding signature file (.SF file) must also have the same prefix.

For those formats that do not support external signed data, the file shall consist of a signed copy of the .SF file. Thus some data may be duplicated and a verifier should compare the two files.

Formats that support external data either reference the .SF file, or perform calculations on it with implicit reference.

Each .SF file may have multiple digital signatures, but those signatures should be generated by the same legal entity.

File name extensions may be 1 to 3 alphanum characters. Unrecognized extensions are ignored.

Notes on Manifest and Signature Files

Following is a list of additional restrictions and rules that apply to manifest and signature files.

• Before parsing:
  
• 
  If the last character of the file is an EOF character (code 26), the EOF is treated as whitespace. Two newlines are appended (one for editors that don`t put a newline at the end of the last line, and one so that the grammar doesn`t have to special-case the last entry, which may not have a blank line after it).

• Attributes:
  
• 
  In all cases for all sections, attributes which are not understood are ignored.
  

  Attribute names are case insensitive. Programs which generate manifest and signature files should use the cases shown in this specification however.

  
  

  Attribute names cannot be repeated within a section.

• Versions:
  
• 
  Manifest-Version and Signature-Version must be first, and in exactly that case (so that they can be recognized easily as magic strings). Other than that, the order of attributes within a main section is not significant.
   
  
• Ordering:
  
• 
  The order of individual manifest entries is not significant.
  

  The order of individual signature entries is not significant, except that the digests that get signed are in that order.

• Line length:
  
• 
  No line may be longer than 72 bytes (not characters), in its UTF8-encoded form. If a value would make the initial line longer than this, it should be continued on extra lines (each starting with a single SPACE).
   
  
• Errors:
  
• 
  If a file cannot be parsed according to this spec, a warning should be output, and none of the signatures should be trusted.
   
  
• Limitations:
  
• 
  Because header names cannot be continued, the maximum length of a header name is 70 bytes (there must be a colon and a SPACE after the name).
  

  NUL, CR, and LF can`t be embedded in header values, and NUL, CR, LF and “:” can`t be embedded in header names.

  
  

  Implementations should support 65535-byte (not character) header values, and 65535 headers per file. They might run out of memory, but there should not be hard-coded limits below these values.

• Signers:
  
• 
  It is technically possible that different entities may use different signing algorithms to share a single signature file. This violates the standard, and the extra signature may be ignored.

• Algorithms:
  
• 
  No digest algorithm or signature algorithm is mandated by this standard. However, at least one of MD5 and SHA digest algorithm must be supported.

JAR Index

Overview

Since 1.3, JarIndex is introduced to optimize the class searching process of class loaders for network applications, especially applets. Originally, an applet class loader uses a simple linear search algorithm to search each element on its internal search path, which is constructed from the “ARCHIVE” tag or the “Class-Path” main attribute. The class loader downloads and opens each element in its search path, until the class or resource is found. If the class loader tries to find a nonexistent resource, then all the jar files within the application or applet will have to be downloaded. For large network applications and applets this could result in slow startup, sluggish response and wasted network bandwidth. The JarIndex mechanism collects the contents of all the jar files defined in an applet and stores the information in an index file in the first jar file on the applet`s class path. After the first jar file is downloaded, the applet class loader will use the collected content information for efficient downloading of jar files.

The existing jar tool is enhanced to be able to examine a list of jar files and generate directory information as to which classes and resources reside in which jar file. This directory information is stored in a simple text file named INDEX.LIST in the META-INF directory of the root jar file. When the classloader loads the root jar file,  it reads the INDEX.LIST file and uses it to construct a hash table of mappings from file and package names to lists of jar file names. In order to find a class or a resource, the class loader queries the hashtable to find the proper jar file and then downloads it if necessary.

Once the class loader finds a INDEX.LIST file in a particular jar file, it always trusts the information listed in it. If a mapping is found for a particular class, but the class loader fails to find it by following the link, an InvalidJarIndexException is thrown. When this occurs, the application developer should rerun the jar tool on the extension to get the right information into the index file.

To prevent adding too much space overhead to the application and to speed up the construction of the in-memory hash table, the INDEX.LIST file is kept as small as possible. For classes with non-null package names, mappings are recorded at the package level. Normally one package name is mapped to one jar file, but if a particular package spans more than one jar file, then the mapped value of this package will be a list of jar files. For resource files with non-empty directory prefixes, mappings are also recorded at the directory level.  Only for classes with null package name, and resource files which reside in the root directory, will the mapping be recorded at the individual file level.

Index File Specification

The INDEX.LIST file contains one or more sections each separated by a single blank line. Each section defines the content of a particular jar file, with a header defining the jar file path name, followed by a list of package or file names, one per line.  All the jar file paths are relative to the code base of the root jar file. These path names are resolved in the same way as the current extension mechanism does for bundled extensions.

The UTF-8 encoding is used to support non ASCII characters in file or package names in the index file.
 

Specification

    index file :                   version-info blankline section*
    version-info :              JarIndex-Version: version-number
    version-number :        digit+{.digit+}*
    section :                      body blankline
    body :                         header name*
    header :                      char+.jar newline
    name :                        char+ newline
    char :                          any valid Unicode character except NULL, CR andLF
    blankline:                    newline newline
    newline :                      CR LF | LF | CR (not followed by LF)
    digit:                           {0-9}
 
The INDEX.LIST file is generated by running jar -i. See the jar man page for more details.

Backward Compatibility

The new class loading scheme is totally backward compatible with applications developed on top of the current extension mechanism.  When the class loader loads the first jar file and an INDEX.LIST file is found in the META-INF directory, it would construct the index hash table and use the new loading scheme for the extension. Otherwise, the class loader will simply use the original linear search algorithm.

Service Provider

Overview

Files in the META-INF/services directory are service provider configuration files. A service is a well-known set of interfaces and (usually abstract) classes. A service provider is a specific implementation of a service. The classes in a provider typically implement the interfaces and subclass the classes defined in the service itself. Service providers may be installed in an implementation of the Java platform in the form of extensions, that is, jar files placed into any of the usual extension directories. Providers may also be made available by adding them to the applet or application class path or by some other platform-specific means.

A service is represented by an abstract class. A provider of a given service contains one or more concrete classes that extend this service class with data and code specific to the provider. This provider class will typically not be the entire provider itself but rather a proxy that contains enough information to decide whether the provider is able to satisfy a particular request together with code that can create the actual provider on demand. The details of provider classes tend to be highly service-specific; no single class or interface could possibly unify them, so no such class has been defined. The only requirement enforced here is that provider classes must have a zero-argument constructor so that they may be instantiated during lookup.
 

Provider-Configuration File

A service provider identifies itself by placing a provider-configuration file in the resource directory META-INF/services. The file`s name should consist of the fully-qualified name of the abstract service class. The file should contain a newline-separated list of unique concrete provider-class names. Space and tab characters, as well as blank lines, are ignored. The comment character is `#` (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.
 

Example

Suppose we have a service class named java.io.spi.CharCodec. It has two abstract methods:

    public abstract CharEncoder getEncoder(String encodingName);
  public abstract CharDecoder getDecoder(String encodingName);

Each method returns an appropriate object or null if it cannot translate the given encoding. Typical CharCodec providers will support more than one encoding.

If sun.io.StandardCodec is a provider of the CharCodec service then its jar file would contain the file META-INF/services/java.io.spi.CharCodec. This file would contain the single line:

   sun.io.StandardCodec    # Standard codecs for the platform

To locate an encoder for a given encoding name, the internal I/O code would do something like this:

   CharEncoder getEncoder(String encodingName) {
       Iterator ps = Service.providers(CharCodec.class);
       while (ps.hasNext()) {
           CharCodec cc = (CharCodec)ps.next();
           CharEncoder ce = cc.getEncoder(encodingName);
           if (ce != null)
               return ce;
       }
       return null;
   }
 

The provider-lookup mechanism always executes in the security context of the caller. Trusted system code should typically invoke the methods in this class from within a privileged security context.

 

API Details

Package java.util.jar

See Also

Package java.security
Package java.util.zip