Java 2 Runtime Environment (JRE) 1.3.0 Configuration Guide
=============================================================

This document includes information about the JRE which corresponds to the 
Java(tm) 2 SDK, Standard Edtion, v1.3.0 (J2SDK 1.3.0). The JRE is 
intended for redistribution with products of software vendors.

Contents
--------

o  	"Overview of Java Runtime"
o  	"The Java Runtime"
o  	"Required vs. Optional Files"
o	"Solaris Optional Files and Directories"
o       "Redistribution of MIDI Soundbanks"
o	"How to Bundle and Run the Java Runtime"
o	"Bundling the Java Runtime"
o	"Java Runtime Example"
o	"Runtime Documentation"
o	"Version and Vendor Identification"

Overview of Java Runtime
-------------------------

The JRE is the minimum standard Java Platform for running Java programs.  
It contains the Java Virtual Machine (JVM), Java Core Classes and 
supporting files.
 
Invoke the JRE from the command line by using the 'java' tool (see the 
following section). Specify an application's class path by using the 
-cp option. The JRE includes all of the non-debuggable .so files plus 
the necessary classes from the J2SE core libraries to support a runtime-only 
program.  The JRE does not include any of the development tools (such 
as appletviewer or javac) or classes that would pertain only to a 
development system.

In this document, the term "vendors" refers to licensees, developers, and 
independent software vendors (ISVs) who license and distribute the JRE with
their Java programs.  Vendors must follow the terms of the JRE Binary Code 
License agreement, which includes these terms:

1.  Do not distribute a subset the required files and directories of the 
JRE. You may omit only the files listed below as optional.
 
2.  Include in your product's license the provisions called out in the JRE 
Binary Code License.

Vendors should also be aware of the support conditions relating to the JRE.  
For information:

http://www.sun.com/solaris/java/support.html

The Java Runtime
----------------

The jre command is obsolete and has been merged with the java
command.  The only environment variable still used is CLASSPATH and this 
can now be overridden by using the java command's -classpath or -cp option.
The -cp option which used to prepend the system class path in the JRE is 
identical to -classpath in the new java command.

The java command invokes the Java Runtime for executing Java applications.
It is available in the Solaris SPARC(tm) and Solaris Intel downloads of 
the JRE. The syntax for the java command is:

java [ threads-flag ] [ options ] class [ argument ... ]

java [ threads-flag ] [ options ] -jar file.jar [ argument ... ]

The classname argument is the name of the class file to be executed. Put
arguments to be passed to the class following the classname on the command
line.  Use the -cp option to specify an application's class path.

Options for the java command are as follows (from the java.1 man page):

     -client             Selects the Java HotSpot Client VM. This
                         is the default.

     -server             Selects the Java HotSpot Server VM.

     -classpath classpath
     -cp classpath       Specifies a  list  of  directories,  JAR
                         archives, and ZIP archives to search for
                         class files.   Class  path  entries  are
                         separated   by  colons  (:).  Specifying
                         -classpath or -cp overrides any  setting
                         of the CLASSPATH environment variable.

                         Used with java, the  -classpath  or  -cp
                         options  only specify the class path for
                         user  classes.    Used   with   oldjava,
                         -classpath or -cp specify the class path
                         for  both  user  classes  and  bootstrap
                         classes.

                         If -classpath and -cp are not  used  and
                         CLASSPATH  is  not  set,  the user class
                         path consists of the  current  directory
                         (.).

     -debug              This has been replaced by -Xdebug.

     -Dproperty=value    Sets a system property value.

     -jar                Executes a program encapsulated in a JAR
                         archive.  The first argument is the name
                         of a JAR file instead of a startup class
                         name.  In order for this option to work,
                         the manifest of the JAR file  must  con-
                         tain   a   line   of   the   form  Main-
                         Class:classname. Here, classname identi-
                         fies  the class having the public static
                         void  main(String[]  args)  method  that
                         serves  as  your  application's starting
                         point.  See the Jar tool reference  page
                         and  the  Jar trail of the Java Tutorial
                         for information about working  with  Jar
                         files  and Jar-file manifests.  When you
                         use this option, the  JAR  file  is  the
                         source  of  all  user classes, and other
                         user class path settings are ignored.

                         On Solaris 8, JAR files that can be  run
                         with  the  "java  -jar"  option can have
                         their permissions set so they can be run
                         without using "java -jar".

     -noclassgc          This has been replaced by -Xnoclassgc.

     -ms<n>              This has been replaced by -Xms<n>.

     -mx<n>              This has been replaced by -Xmx<n>.

     -ss<n>              This has been replaced by -Xss<n>.

     -verbose
     -verbose:class      Displays information  about  each  class
                         loaded.

     -verbosegc          This has been replaced by -verbose:gc.

     -verbose:gc         Reports  on  each   garbage   collection
                         event.

     -verbose:jni        Reports information about use of  native
                         methods  and other Java Native Interface
                         activity.

     -version            Displays version information and exit.

     -showversion        Displays version information and contin-
                         ues.

     -?
     -help               Displays usage information and exit.

     -X                  Displays information about  non-standard
                         options and exit.

  Non-Standard Options
     -Xint               Operates in interpreted-only mode.  Com-
                         pilation to native code is disabled, and
                         all bytecodes are executed by the inter-
                         preter.     The   performance   benefits
                         offered by the Java HotSpot  VMs'  adap-
                         tive  compiler  will  not  be present in
                         this mode.

     -Xbootclasspath:bootclasspath
                         Specifies  a  colon-separated  list   of
                         directories,   JAR   archives,  and  ZIP
                         archives to search for boot class files.
                         These  are  used  in  place  of the boot
                         class files included in the Java  2  SDK
                         and Java 2 Runtime Environment.

     -Xbootclasspath/a:path
                         Specifies  a  colon-separated  path   of
                         directories,   JAR   archives,  and  ZIP
                         archives  to  append  to   the   default
                         bootstrap class path.

     -Xbootclasspath/p:path
                         Specifies  a  colon-separated  path   of
                         directories,   JAR   archives,  and  ZIP
                         archives to  prepend  in  front  of  the
                         default  bootstrap  class  path.   Note:
                         Applications that use  this  option  for
                         the  purpose  of  overriding  a class in
                         rt.jar should not be deployed, as  doing
                         so  would  contravene the Java 2 Runtime
                         Environment binary code license.

     -Xdebug             Starts with the debugger  enabled.   The
                         Java  interpreter  prints out a password
                         for the use of jdb(1).  Refer to  jdb(1)
                         for  more details and an example.  Note:
                         In this release, the compiler must  have
                         been  disabled  beforehand by specifying
                         -Djava.compiler=NONE before this option.
                         This  restriction  may  be  lifted  in a
                         future release.

     -Xfuture            Performs   strict   class-file    format
                         checks.   For purposes of backwards com-
                         patibility, the  default  format  checks
                         performed  by  the  Java 2 SDK's virtual
                         machine are no stricter than the  checks
                         performed  by  1.1.x versions of the JDK
                         software.  The -Xfuture  flag  turns  on
                         stricter  class-file  format checks that
                         enforce  closer   conformance   to   the
                         class-file     format     specification.
                         Developers are encouraged  to  use  this
                         flag  when  developing  new code because
                         the  stricter  checks  will  become  the
                         default  in  future releases of the Java
                         application launcher.

     -Xnoclassgc         Disables class garbage collection

     -Xmsn               Specifies the initial size of the memory
                         allocation  pool.   This  value  must be
                         greater than 1000.  To modify the  mean-
                         ing of n, append either the letter k for
                         kilobytes or the letter m for megabytes.

                         The default value is 8m.

     -Xmxn               Specifies the maximum size of the memory
                         allocation  pool.   This  value  must be
                         greater than 1000.  To modify the  mean-
                         ing of n, append either the letter k for
                         kilobytes or the letter m for megabytes.
                         The default value is 24m.

     -Xprof              Profiles the running program, and  sends
                         profiling data to standard output.  This
                         option is provided as a utility that  is
                         useful in program development and is not
                         intended to be  be  used  in  production
                         systems.

     -Xrunhprof[:help][:suboption=value,...]
                         Enables cpu, heap, or monitor profiling.
                         This  option  is typically followed by a
                         list of comma-separated  suboption=value
                         pairs.     Run    the    command    java
                         -Xrunhprof:help  to  obtain  a  list  of
                         suboptions and their default values.

     -Xssn               Each Java thread has two stacks: one for
                         Java  code and one for C code.  The -Xss
                         option sets the maximum stack size  that
                         can  be used by C code in a thread to n.
                         Every thread that is spawned during  the
                         execution  of the program passed to java
                         has n as its C stack size.  The  default
                         units  for  n  are bytes and n must be >
                         1000 bytes.

                         To  modify  the  meaning  of  n,  append
                         either the letter k for kilobytes or the
                         letter m  for  megabytes.   The  default
                         stack size is 512 kilobytes (-Xss512k).


Required vs. Optional Files
--------------------------- 

You must follow the terms of the accompanying LICENSE. The files 
that make up the JRE are divided into two categories: required and 
optional.  Files that are marked "optional" here do not need to be 
included with the licensee's program. Most of the optional files provide 
localization support for languages.

The term "required" means that licensees who distribute the runtime 
must include those files with their program, regardless of whether 
those files are used by their program.  These files are a required part 
of the Java Platform.  All files not explicitly listed as optional 
are required.

The Solaris Production JRE ships with native threads support only; green
threads support is not included.  Vendors must include the files providing
native threads support, which reside in the directory 
lib/<sys>/native_threads.

The JRE includes the bin and lib directories which both must reside in 
the same directory, <runtime-dir>.

In the following lists, all paths are relative to the <runtime-dir> 
directory (the top-level directory in which the JRE is installed).

Solaris Optional Files and Directories
--------------------------------------

The directory <sys> varies depending on the hardware architecture
implementation.  For Solaris it will be either sparc or i386.

All font properties files in the lib directory other than the default 
lib/font.properties file are optional, and vendors may choose not to 
include them in redistributions of the JRE.  In addition, the
following may be optionally excluded from redistributions:

    lib/i18n.jar                  
       Character conversion classes and all other locale support
    lib/ext/                      
       Directory containing extension jar files
    bin/rmid
       Java RMI Activation System Daemon
    bin/rmiregistry
       Java Remote Object Registry
    bin/tnameserv
       Java IDL Name Server
    bin/keytool
       Key and Certificate Management Tool
    bin/policytool
       Policy File Creation and Management Tool


Redistribution of MIDI Soundbanks
---------------------------------

The Java 2 Runtime Environment ships with a default, minimal MIDI soundbank 
located at lib/audio/soundbank.gm.  This minimal soundbank 
and a selection of enhanced MIDI soundbanks are available from the Java 
Sound web site: http://java.sun.com/products/java-media/sound/
Any of these soundbanks may be included in redistributions of the 
Java 2 Runtime Environment. These soundbanks also may be installed to 
enable software MIDI synthesis in distributions which did not include a 
soundbank, or to upgrade the quality of software MIDI synthesis in 
distributions which included the minimal soundbank file.


How to Bundle and Run the Java Runtime
======================================

Bundling the Java Runtime
-------------------------

When bundling the JRE with application software on Solaris, consider the 
following points:

1. Install the JRE in its own subdirectory,referred to below as 
<runtime-dir>. Include all the required files in the bin and lib 
subdirectories of <runtime-dir>, following the same directory hierarchy 
and relative placement of files created upon installation of the JRE.  
The internationalization files marked optional can be included for 
language localization support, if desired.

2. The example shows all application-specific classes in the file
<app-dir>/lib/app.jar.  To make maintenance easier it is suggested that 
all application-specific classes be placed in a  directory other than 
<runtime-dir>.  Application-specific classes may be individual .class 
files, .jar files, or .zip files. 

An example directory structure might look like the following:

              <app-dir>
  _________________|_________
  |          |               |
 bin        lib          <runtime-dir>
  |          |	     ________|________	     
	  app.jar    |		     |
                    bin             lib
		     |               |


3. If native code support is required, then the native library must be 
located in LD_LIBRARY_PATH. One way to do this is to install the native 
libraries in <app-dir>/lib/<sys>. Then set LD_LIBRARY_PATH to include 
these directories.

4. The application can be invoked by using the JRE command-line tool, 
using the -cp option to specify the application's class path. In the 
example directory tree above, for example, the command might look like 
this:

<app-dir>/<runtime-dir>/bin/java -cp <app-dir>/lib/app.jar <classname>

For more information that might be relevant to installing and running 
the JRE, refer to the installation instructions and to this web page:

http://java.sun.com/j2se/1.3/runtime_solaris.html


Java Runtime Example
--------------------

The following Web page has a "Hello World" example that you can download, 
which demonstrates how to create a simple Java application that runs on 
and is bundled with a JRE.
  
http://java.sun.com/j2se/1.3/runtime.html

This example shows how to make a simple, seamless transition from developing 
an application with the Java 2 SDK to deploying it with the more lightweight 
JRE.

Runtime Documentation
---------------------

Runtime documentation is any documentation that an end-user might need after 
installing a Java program that runs on the JRE. We supply the following 
runtime documentation:

1.  Each property file contains comments that describe what the file is useful 
for and how to modify it.

2.  awt.properties file - KeyEvent uses it to print out properties of key 
events, usually for debugging purposes.  This might be used by a GUI debugger 
that needs to print out events.

3.  fontprop.html file has a Web page describing how to add fonts to the 
runtime:

http://java.sun.com/j2se/1.3/docs/guide/intl/fontprop.html

Version and Vendor Identification
---------------------------------

To enable customers to identify the JRE version and vendor for troubleshooting 
purposes, once the JVM is running, reference one of these methods:

java.lang.System.getProperties() (all properties)
	or
java.lang.System.getProperty("java.version") (single property)

The relevant properties are:

Properties		Description

java.version		Java version number
java.vendor		Java vendor-specific string
java.vendor.url		Java vendor URL
java.class.version	Java class format version number
java.compiler		Java compiler
os.name			Operating system name
os.arch			Operating system architecture
os.version		Operating system version

Optionally:
 
Properties	Description

java.home	Java installation directory
java.class.path	Java class path

-----------------------------------------------------------
Copyright 2001 Sun Microsystems, Inc. All rights reserved.
Copyright 2001 Sun Microsystems, Inc. Tous droits réservés. 

