Solaris Java Runtime Environment (JRE) 1.2.2_05a Configuration Guide
=================================================================

This document includes information about the JRE which corresponds to the 
Java(tm) Development Kit (JDK(tm)) 1.2.2_05a FCS. This FCS release is
suitable for inclusion with a deployed product.

Note - For information about the JDK 1.2.2_05a FCS, refer to the Solaris(tm)
JDK 1.2.2_05a FCS Release Notes at: 

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

o  	"Overview of Java Runtime"
o  	"The Java Runtime"
o  	"Required vs. Optional Files"
o	"Solaris Optional Files and Directories"
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 JDK 1.2.2_05a 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 for JRE 1.2 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 now
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):

     -classpath classpath
     -cp classpath
                    Specify 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,  -classpath  or  -cp  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 (.).

                    For more information on class paths, see Set-
                    ting the Class Path.

     -debug         This has been replaced by -Xdebug.

     -Dproperty=value
                    Set a system property value.

     -jar           Execute  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 contain a  line  of  the
                    form  Main-Class:classname.  Here,  classname
                    identifies 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 work-
                    ing  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.

                    The oldjava tool does not  support  the  -jar
                    option.

    -noclassgc     This has been replaced by -Xnoclassgc.

     -ossn          This has been replaced by -X0ssn.

     -msh           This has been replaced by -Xmsn.

     -mxn           This has been replaced by -Xmxn.

     -ssn           This has been replaced by -Xssn.

     -t             This has been replaced by -Xt.

     -tm            This has been replaced by -Xtm.

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

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

     -verbose:gc    Report on each garbage collection event.

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

     -version       Display version information and exit.

     -?
     -help
                    Display usage information and exit.

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

     -Xbootclasspath:bootclasspath
                    Specify  a  colon-separated  list  of  direc-
                    tories,  JAR  archives,  and  ZIP archives to
                    search for boot class files.  These are  used
                    in  place of the boot class files included in
                    the JDK 1.2 software.

     -Xdebug        Start with the  debugger  enabled.  The  Java
                    interpereter  prints  out  a password for the
                    use of jdb(1).  Refer to  jdb(1)  description
                    for more details and an example.

     -Xcheck:jni    Perform  additional  check  for  Java  Native
                    Interface functions.

     -Xmaxjitcodesize
                    Sets the maximum size (in bytes) for JIT code
                    area.

     -Xnoclassgc    Disable class garbage collection

     -Xmsn          Specify the initial size of the memory  allo-
                    cation  pool.  This  value must greather than
                    1000. To multiply the value by  1000,  append
                    the  letter  k.   To  multiply the value by 1
                    million, append the letter  m.   The  default
                    value is 1m.

     -Xmxn          Specify the maximum size of the memory  allo-
                    cation  pool.  This  value must greather than
                    1000. To multiply the value by  1000,  append
                    the  letter  k.   To  multiply the value by 1
                    million, append the letter  m.   The  default
                    value is 16m.

    -Xossn         Each Java thread has two stacks: one for Java
                    code  and  one  for  C code. The -Xoss option
                    sets the maximum stack size that can be  used
                    by  Java  code in a thread to n. Every thread
                    that is spawned during the execution  of  the
                    program  passed  to  java  has  n as its Java
                    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  400
                    kilobytes (-Xoss400k).

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

     -Xprof[:file]  Enable profiling. If no  file  is  specified,
                    write  results  to  java.prof  in the current
                    directory.

     -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  128
                    kilobytes (-Xss128k).

     -Xrs           Reduce the use of operating system signals.

     -Xsqnopause    Do not pause for user interaction on siqquit.

     -Xt            Turns on instruction tracing.

     -Xtm           Turns on method tracing.

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

Licensees must follow the terms of the accompanying LICENSE. The files that make
up the JRE are divided into two categories: required and optional.  To 
paraphrase that license, 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 
(which is originally Solaris_JRE_1.2.2_05a).

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 for Solaris 2.6 and 7 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

The following files are optional: 

 lib/i18n.jar 			I18N character conversion classes from sun.io
 lib/font.properties.cs 	AWT font properties for Czech locale
 lib/font.properties.pl 	AWT font properties for Polish locale
 lib/font.properties.hu 	AWT font properties for Hungarian locale
 lib/font.properties.lt 	AWT font properties for Lithuanian locale
 lib/font.properties.lv 	AWT font properties for Latvian locale
 lib/font.properties.el 	AWT font properties for Greek locale
 lib/font.properties.tr 	AWT font properties for Turkish locale
 lib/font.properties.ja 	AWT font properties for Japanese locale
 lib/psfont.properties.ja 	AWT psfont properties for Japanese locale
 lib/font.properties.ru 	AWT font properties for Russian locale
 lib/font.properties.ko 	AWT font properties for Korean locale
 lib/font.properties.zh_G
				B2312 AWT font properties for Simplified 
				Chinese locale 
 lib/font.properties.zh_T	
				W_Big5 AWT font properties for Traditional 
				Chinese locale
 lib/font.properties.zh_TW_CNS11643 	
				Alternative AWT font properties for Traditional 
				Chinese locale

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 JDK installation instructions:

http://www.java.sun.com/products/jdk/1.2/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://www.java.sun.com/products/jdk/1.2/runtime.html

This example shows how to make a simple, seamless transition from developing an 
application with the JDK 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://www.java.sun.com/products/jdk/1.2/docs/guide/internat/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 2000 Sun Microsystems, Inc. All rights reserved.
Copyright 2000 Sun Microsystems, Inc. Tous droits rservs. 
