Print-friendly Version

The Java 2 Runtime Environment Notes for Developers

Contents

Introduction
Redistribution of the Java 2 Runtime Environment
Packaging Your Application in a JAR File
Example: Creating a JAR-Packaged Application

In addition to the general information on this page, platform-specific notes are available in these files:

The Java 2 Runtime Environment on Microsoft Windows Platforms
The Java 2 Runtime Environment on Solaris Platforms

The Java 2 Runtime Environment is the minimum standard Java computing environment for running applications written in the Java programming language. It contains the Java virtual machine, Java core classes, and supporting files. It does not contain any of the development tools (such as appletviewer or javac) or classes that pertain only to a development environment.

The Java 2 Runtime Environment is available for download from the Java Software website.

This document provides information and suggestions that may be useful for developers who want to redistribute the Java 2 Runtime Environment with their software. Other useful information may be found in the Java 2 Runtime Environment README file.

To submit comments or suggestions about the Java 2 Runtime Environment, please send mail to the most appropriate engineering team from the list at Java Software email addresses.

In order for your end users to run your software, they'll need to have a Java runtime environment installed on their systems. To ensure that they do, you may redistribute either the JDK or Java 2 Runtime Environment with your software.

You may prefer to redistribute the Java 2 Runtime Environment rather than the JDK for the following reasons.

• The Java 2 Runtime Environment is smaller than the JDK. The Java 2 Runtime Environment contains everything your users will need to run your software, but it leaves out the development tools and demo applets and applications that are part of the JDK. Because the Java 2 Runtime Environment is relatively small, it's easier for you to package with your software or for your users to download themselves from the Java Software web site.
• On Microsoft Windows platforms, the Java 2 Runtime Environment's installer automatically installs the java and javaw application launchers in a location that's on the operating system's default system path. That means you don't have to worry about finding the launchers to start your application, and you don't have to provide instructions to your users for fiddling with the paths on their systems.

If you package the Java 2 Runtime Environment with your application software, the license requires that you redistribute it in its entirety except for some optional files which you may choose not to redistribute. The files that are optional are listed in the README. They are for functionality such as internationalization and localization which your particular application may or may not need. If your software needs these optional components, they are there for you to redistribute. If you don't need them, there's no requirement for you to include them in your redistribution of the Java 2 Runtime Environment.

You will probably want to consider bundling your application software in a Java Archive (JAR) file. Files stored in a JAR archive can be compressed, allowing the size of your software bundle to be relatively small. In addition, your software can take advantage of the JAR archive's manifest file which provides means for you to specify vendor information, versioning information, package sealing, etc.

For more information on working with JAR archives and their manifests, see the JAR file section of the J2SE documentation and the JAR trail in the Java tutorial.

Your application can be launched while packaged in a JAR file by using the -jar option of the java or javaw application launchers. For this option to work, the launcher must know which of the files within your JAR archive is your application's starting point. In other words, the launcher will have to know which class in your JAR file contains the method with signature:

public static void main(String[])

To specify your application's starting point, the manifest of your JAR file must have a line of this form:

Main-Class: <class name>
    

where class name is the name of your entry-point class.

With your manifest prepared in this way, your JAR-packaged application can be launched with a command of this form:

java -jar YourApp.jar

This section uses a simple HelloWorld appliction to illustrate the basic steps necessary for bundling an application in a JAR file.

The source code of the application looks like this:

class HelloWorld { public static void main(String[] args) { System.out.println("Hello World!"); } }

It's worth pointing out that there's nothing special about the code in this application that prepares it in some way for being packaged in a JAR file. The source code you write for a JAR-packaged application is the same as any other source code you write.

Let's assume that you've compiled the application and have the file HelloWorld.class ready to be bundled. In order to make the application runnable from a JAR file, you need to ensure that the JAR file's manifest contains this line:

Main-Class: HelloWorld

You can insert this line into the manifest by using the jar utility in the JDK. You first need to prepare an "auxilary" file that has the information that you want to import into the JAR file's manifest. In the present example, you would prepare an auxilary file consisting of the single line that you need:

Main-Class: HelloWorld  

Let's assume that you've named the auxilary file MyMainClass. You can import the contents of the auxiliary file into the manifest of a JAR file at the same time that you create the JAR file. To do that, you would use the following command:

jar cfm HelloWorld.jar MyMainClass HelloWorld.class

This command will create a JAR file named HelloWorld.jar containing the file HelloWorld.class and a manifest. The m flag indicates that the contents of file MyMainClass should be placed inside the manifest. The resulting manifest will look like this:

Manifest-Version: 1.0
Main-Class: HelloWorld
Created-By: 1.5.0 (Sun Microsystems Inc.)

The Main-Class line has been imported into the manifest as we desired.

If the JAR file already exists but its manifest doesn't contain the Main-Class attribute, you can import the line from the auxilary file into the manifest with this command:

jar ufm HelloWorld.jar MyMainClass

The u flag indicates that you're updating an exsiting JAR file, and the m flag indicates that the contents of the auxilary file should be imported into the manifest.

After preparing a JAR file and manifest in this manner, you can run the application with this command:

java -jar HelloWorld.jar