Runtime Environment Notes for Developers

Contents

Introduction
Redistribution of the Java SE 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 SE Runtime Environment on Microsoft Windows Platforms
The Java SE Runtime Environment on Solaris Platforms

Introduction

The Java SE 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 SE 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 SE Runtime Environment with their software. Other useful information may be found in the Java SE Runtime Environment README file.

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

Redistribution of the Java SE Runtime Environment

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 Runtime Environment with your software.

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

• The Java SE Runtime Environment is smaller than the JDK. The Java SE 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 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 SE 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 SE 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 SE Runtime Environment.

Packaging Your Application in a JAR File

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 Java SE 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
                


              

Example: Creating a JAR-Packaged Application

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