home *** CD-ROM | disk | FTP | other *** search
/ The UNIX CD Bookshelf / OREILLY_TUCB_UNIX_CD.iso / netresults / jvm / readme < prev   
Text File  |  1998-08-31  |  19KB  |  432 lines
  1.  
  2.                              README
  3.  
  4.                   The Java(tm) Runtime Environment
  5.                            JRE 1.1.3 
  6.  
  7. -----------------------------------------------------------------------
  8. CONTENTS
  9.  
  10.  
  11.   Overview of Java Runtime
  12.     - Introduction
  13.     - The Java Runtime Interpreter
  14.     - Required vs. Optional Files
  15.     - Win 32 Files 
  16.        - Required Files
  17.        - Optional Files
  18.     - Solaris Files 
  19.        - Required Files
  20.        - Optional Files
  21.  
  22.   Bundling and Running the Java Runtime
  23.     - Bundling the Java Runtime
  24.     - Java Runtime Example
  25.     - Runtime Documentation
  26.  
  27.  
  28. =======================================================================
  29.                         OVERVIEW OF JAVA RUNTIME
  30. =======================================================================
  31.  
  32. -----------------------------------------------------------------------
  33. INTRODUCTION
  34. -----------------------------------------------------------------------
  35.  
  36. This is version 1.1.3 of the Java Runtime Environment, also known as 
  37. the Java Runtime, or JRE.  The Java Runtime is the minimum standard
  38. Java Platform for running Java programs.  It contains the Java 
  39. Virtual Machine, Java Core Classes and supporting files. 
  40.  
  41. The JRE can be invoked from the command line by using the jre (see the 
  42. following section). On Windows platforms, the jre tool will ignore the 
  43. CLASSPATH environment variable. For both Windows and Solaris 
  44. platforms, the -cp option is recommended to specify an application's 
  45. class path.
  46.  
  47. This document uses the term "vendors" to refer to licensees, 
  48. developers, and independent software vendors (ISVs) who 
  49. license and distribute the JRE with their Java programs.
  50.  
  51. The Win32 version of JRE 1.1.3 has an installer suitable for use 
  52. by end-users. This gives software developers the option of not 
  53. bundling the JRE with their applications. Instead, they can direct 
  54. end-users to download and install the JRE themselves.
  55.  
  56. An installer is not available for Solaris versions of the JRE. 
  57. Developers should bundle the JRE and an installer with their Solaris 
  58. applications. 
  59.  
  60. The JRE includes all of the non-debuggable .dll or .so files plus
  61. the necessary classes from the JDK 1.1.3 to support a runtime-only 
  62. program.  The JRE does not include any of the development tools
  63. (such as appletviewer or javac) or classes that would pertain only 
  64. to a development system.
  65.  
  66. Vendors must follow the terms of the JRE Binary Code License agreement, 
  67. which includes these terms:
  68.  
  69.  - Don't arbitrarily subset the JRE. You may omit only the
  70.    files listed below as optional. 
  71.  
  72.  - Include in your product's license the provisions called out
  73.    in the JRE Binary Code License.
  74.     
  75. The JRE is a product of Sun Microsystems, Inc.  
  76. JavaSoft is an operating company of Sun, and develops the JRE.
  77.  
  78.  
  79. -----------------------------------------------------------------------
  80. THE JAVA RUNTIME INTREPRETER
  81. -----------------------------------------------------------------------
  82.  
  83. The jre tool invokes the Java Runtime interpreter for executing Java 
  84. applications. The tool is available in the Win32, Solaris-Sparc, and 
  85. Solaris x86 downloads of the JRE. The syntax for the jre command is:
  86.  
  87.     jre [ options ] classname <args>
  88.  
  89. The classname argument is the name of the class file to be 
  90. executed. Any arguments to be passed to the class must be placed 
  91. after the classname on the command line.
  92.  
  93. An alternative version of the tool, jrew, is available for Win32. The 
  94. jrew command is identical to jre, except that a console window is not 
  95. invoked. The syntax of the jrew command is 
  96.  
  97.     jrew [ options ] classname <args>
  98.  
  99. On Windows platforms, the jre tool will ignore the CLASSPATH 
  100. environment variable. For both Windows and Solaris platforms, the 
  101. -cp option is recommended to specify an application's class path.
  102.  
  103. Options for the jre and the jrew commands are as follows:
  104.  
  105.    -classpath path    Specifies the path that jre uses to 
  106.                look up classes. Overrides the default 
  107.                classpath.  
  108.  
  109.    -cp path        Prepends the specified path to the default 
  110.                classpath that jre uses to look up classes. 
  111.  
  112.    -help        Print a usage message.
  113.  
  114.    -mx x        Sets the maximum size of the memory allocation 
  115.                pool (the garbage collected heap) to x. The 
  116.                default is 16 megabytes of memory. x must be
  117.             greater than or equal to 1000 bytes.
  118.  
  119.    -ms x        Sets the startup size of the memory allocation 
  120.                pool (the garbage collected heap) to x. The 
  121.                default is 1 megabyte of memory. x must be
  122.             greater than 1000 bytes.
  123.  
  124.    -noasyncgc        Turns off asynchronous garbage collection. When 
  125.                activated, no garbage collection takes place 
  126.                unless it is explicitly called or the program 
  127.             runs out of memory.
  128.  
  129.    -noclassgc        Turns off garbage collection of Java classes. 
  130.                By default, the Java interpreter reclaims space 
  131.                for unused Java classes during garbage collection.
  132.  
  133.    -nojit        Specifies that any JIT compiler should be 
  134.             ignored. The default Java interpreter is invoked.
  135.  
  136.    -ss x        The -ss option sets the maximum stack size that 
  137.                can be used by C code in a thread to x. The 
  138.             default units for x are bytes. The value of x 
  139.             must be greater than or equal to 1000 bytes.
  140.  
  141.    -oss x        The -oss option sets the maximum stack size 
  142.             that can be used by Java code in a thread to x. 
  143.             The default units for x are bytes. The value of 
  144.             x must be greater than or equal to 1000 bytes.
  145.  
  146.    -v, -verbose        Causes jre to print a message to stdout each 
  147.             time a class file is loaded.
  148.  
  149.    -verify        Performs byte-code verification on the class 
  150.             file. Beware, however, that java -verify does 
  151.             not perform a full verification in all 
  152.             situations. Any code path that is not actually 
  153.             executed by the interpreter is not verified. 
  154.             Therefore, java -verify cannot be relied upon to 
  155.             certify class files unless all code paths in 
  156.             the class file are actually run.
  157.  
  158.    -verifyremote    Runs the verifier on all code that is loaded 
  159.             into the system via a classloader. verifyremote 
  160.             is the default for the interpreter.
  161.  
  162.    -noverify        Turns verification off.
  163.  
  164.    -verbosegc        Causes the garbage collector to print out 
  165.             messages whenever it frees memory.
  166.    
  167.    -DpropName=value    Defines a property value. propName is the name 
  168.             of the property whose value you want to change 
  169.             and value is the value to change it to. For 
  170.             example, the command 
  171.             java -Dawt.button.color=green ...
  172.             sets the value of the property awt.button.color 
  173.             to "green".
  174.  
  175.  
  176. -----------------------------------------------------------------------
  177. REQUIRED vs. OPTIONAL FILES
  178. -----------------------------------------------------------------------
  179.  
  180. Licensees must follow the terms of the accompanying LICENSE.  
  181. The files that make up the JRE are divided into two categories:
  182. required and optional.  To paraphrase that license, files that 
  183. are marked "optional" here do not need to be included with the 
  184. licensee's program.
  185.  
  186. The term "required" means licensees who distribute the runtime 
  187. must include those files with their program, whether or not 
  188. their program ever uses those files.  Those files are a 
  189. required part of the Java Platform.
  190.  
  191. In general, the optional files provide localization support for
  192. languages.
  193.  
  194. The JRE includes the bin and lib directories which both must
  195. reside in the same directory.  We call this directory <runtime-dir>.
  196.  
  197. In the following lists, all paths are relative to the <runtime-dir>
  198. directory (which is originally "jre1.1.3").
  199.  
  200. -----------------------------------------------------------------------
  201. WIN32 FILES
  202. -----------------------------------------------------------------------
  203.  
  204. Two versions of JRE 1.1.3 for Win32 are available. One version contains 
  205. files for internationalization support. This version contains all the 
  206. files listed below under both the REQUIRED FILES and OPTIONAL FILES 
  207. subsections. A smaller version of the Win32 JRE is available that does
  208. not contain those optional files that provide internationalization 
  209. support.
  210.  
  211. REQUIRED FILES --------------------------------------------------------
  212.  
  213.    The Win32 bin directory contains the executables and native libraries:
  214.  
  215.    bin\jre.exe                   Java runtime executable
  216.    bin\jrew.exe                  Java runtime executable, no console window
  217.    bin\javai.dll                 Java runtime native code library
  218.    bin\jdbcodbc.dll              native code support for sun.jdbc
  219.    bin\jpeg.dll                  native code support for sun.jpeg
  220.    bin\math.dll                  native code support for java.math
  221.    bin\mmedia.dll                native code support for sun.audio
  222.    bin\net.dll                   native code support for java.net
  223.    bin\sysresource.dll           native code support for sun.net.www.protocol
  224.    bin\winawt.dll                native code support for sun.awt
  225.    bin\zip.dll                   native code support for java.util.zip
  226.  
  227.    The Win32 lib directory contains the classes and property files:
  228.  
  229.    lib\rt.jar                    Java runtime core classes
  230.    lib\awt.properties            properties for key events for java.awt
  231.    lib\font.properties           Win32 font properties for java.awt
  232.    lib\serialver.properties      serialization properties
  233.    lib\security\java.security    properties for java.security
  234.  
  235. OPTIONAL FILES --------------------------------------------------------
  236.  
  237. The following files are optional:
  238.  
  239.    lib\i18n.jar                  I18N character conversion classes from sun.io
  240.    lib\content-types.properties  MIME-type properties 
  241.    lib\font.properties.ja        AWT font properties for Japanese locale
  242.    lib\font.properties.ko        AWT font properties for Korean locale
  243.    lib\font.properties.ru        AWT font properties for Russian locale
  244.    lib\font.properties.zh        AWT font properties for Simplified Chinese locale
  245.    bin\msvcrt.dll                native code C runtime library
  246.  
  247.  
  248. -----------------------------------------------------------------------
  249. SOLARIS FILES
  250. -----------------------------------------------------------------------
  251.  
  252. The following is a complete list of files included with the JRE 1.1.3 
  253. for Solaris.  
  254.  
  255. REQUIRED FILES --------------------------------------------------------
  256.  
  257. The directory <sys> varies depending on the hardware architecture and
  258. threads implementation. For this release only Solaris/SPARC with Green 
  259. threads is supported, so <sys> should be 'sparc/green_threads'.
  260.  
  261.    The Solaris bin directory contains the shell scripts and executables:
  262.  
  263.    bin/jre                      Java runtime shell script
  264.    bin/<sys>/jre    Java runtime executable
  265.  
  266.    The Solaris lib directory and its subdirectories contain the 
  267.    classes, properties files and native libraries:
  268.  
  269.    lib/rt.jar                    Java runtime core classes
  270.    lib/awt.properties            properties for key events for java.awt
  271.    lib/font.properties           Solaris font properties for java.awt
  272.    lib/serialver.properties      serialization properties
  273.    lib/security/java.security    properties for java.security
  274.  
  275.    lib/<sys>/libjava.so          Java runtime library
  276.    lib/<sys>/libnet.so           native code support for java.net
  277.    lib/<sys>/libmath.so          native code support for java.math
  278.    lib/<sys>/libmmedia.so        native code support for sun.audio
  279.    lib/<sys>/libawt.so           native code support for sun.awt
  280.    lib/<sys>/libjpeg.so          native code support for sun.jpeg
  281.    lib/<sys>/libJdbcOdbc.so      native code support for sun.jdbc
  282.    lib/<sys>/libsysresource.so   native code support for sun.net
  283.    lib/<sys>/libzip.so           native code support for java.util.zip
  284.  
  285. OPTIONAL FILES --------------------------------------------------------
  286.  
  287. The following files are optional.
  288.  
  289.    lib/i18n.jar                  I18N character conversion classes from sun.io
  290.    lib/content-types.properties  MIME-type properties 
  291.    lib/font.properties.cs        AWT font properties for Czech locale
  292.    lib/font.properties.pl        AWT font properties for Polish locale
  293.    lib/font.properties.hu        AWT font properties for Hungarian locale
  294.    lib/font.properties.lt        AWT font properties for Lithuanian locale
  295.    lib/font.properties.lv        AWT font properties for Latvian locale
  296.    lib/font.properties.el        AWT font properties for Greek locale
  297.    lib/font.properties.tr        AWT font properties for Turkish locale
  298.    lib/font.properties.ja        AWT font properties for Japanese locale
  299.    lib/font.properties.ru        AWT font properties for Russian locale
  300.    lib/font.properties.ko        AWT font properties for Korean locale
  301.    lib/font.properties.zh        AWT font properties for Simplified Chinese locale
  302.    lib/font.properties.zh_TW     AWT font properties for Traditional Chinese locale
  303.    lib/<sys>/libXm.so            Symbolic link to Motif runtime library 
  304.    lib/<sys>/libXm.so.3          Motif runtime library
  305.  
  306. libXm.so.3 is present in Solaris 2.5 and later, so is needed only if the 
  307. ultimate target of your program is to run on Solaris 2.4 or earlier.
  308.  
  309.  
  310. =======================================================================
  311.                 BUNDLING AND RUNNING THE JAVA RUNTIME
  312. =======================================================================
  313.  
  314. -----------------------------------------------------------------------
  315. BUNDLING THE JAVA RUNTIME
  316. -----------------------------------------------------------------------
  317.  
  318. This release of the JRE for Win32 comes with its own installer that 
  319. makes is suitable for downloading by end users. Java application 
  320. developers have the option of not bundling the JRE with their software. 
  321. Instead, they can direct end-users to download and install the JRE 
  322. themselves.
  323.  
  324. Solaris versions of the JRE do not have an installer. Software 
  325. developers should bundle the JRE and installer with their Solaris 
  326. software. 
  327.  
  328. When bundling the JRE with application software on Solaris, the 
  329. following points should be considered:
  330.  
  331. 1) It is suggested that the JRE be installed in its own subdirectory
  332.    (referred to below as <runtime-dir>).  Include all the the required
  333.    files listed above in the bin and lib subdirectories of 
  334.    <runtime-dir>, following the same directory hierarchy and 
  335.    relative placement of files.  The internationalization files 
  336.    marked optional can be included for language localization support.
  337.  
  338. 2) It is suggested that all application-specific classes be placed 
  339.    in a directory other than <runtime-dir>. Application-specific 
  340.    classes may be individual .class files, .jar files, or .zip 
  341.    files.
  342.  
  343.    An example directory structure might look like the following:
  344.  
  345.                <app-dir>
  346.        ________________|___________
  347.       |         |               |
  348.          bin       lib           <runtime-dir>
  349.           |         |          ________|________
  350.                  app.jar      |                 | 
  351.                              bin               lib         
  352.                               |                 |
  353.                        
  354.  
  355. 3) If native code support is required, then the native library must be 
  356.    located in LD_LIBRARY_PATH on Solaris or the executable search PATH 
  357.    on Win32. The best way to do this is to install the native libraries
  358.    in either <app-dir>/lib/<sys> on Solaris or <app-dir>\bin 
  359.    on Win32. LD_LIBRARY_PATH (on Solaris) or PATH (on Win32) should 
  360.    then be set to include these directories.
  361.  
  362. 4) The application can be invoked by using the jre command-line tool, 
  363.    using the -cp option to specify the application's class path. In 
  364.    the example directory tree above, for example, the command might 
  365.    look like this:
  366.  
  367.    <app-dir>/<runtime-dir>/bin/jre -cp <app-dir>/lib/app.jar <classname>
  368.  
  369.    Information on the jre command-line tool can be found in the 
  370.    JRE 1.1.3 CHANGES file and on the JavaSoft web site at 
  371.    http://java.sun.com/products/jdk1.1/docs/tooldocs/solaris/jre.html
  372.    and
  373.    http://java.sun.com/products/jdk1.1/docs/tooldocs/win32/jre.html
  374.  
  375.    Source code for the jre tool can be found in the Windows JDK 1.1.3 
  376.    directory tree in the jdk1.1.3\demo\jre\win32 folder. For the 
  377.    Solaris JDK 1.1.3, jre source code files can be found in the 
  378.    jdk1.1.3/demo/jre/solaris directory.
  379.  
  380.   
  381. For more information that might be relevant to installing and running
  382. the JRE, refer to the JDK installation instructions:
  383.  
  384.     http://java.sun.com/products/jdk/1.1/installation-win32-x86.html
  385.     http://java.sun.com/products/jdk/1.1/installation-solaris2.html
  386.  
  387.  
  388. -----------------------------------------------------------------------
  389. JAVA RUNTIME EXAMPLE
  390. -----------------------------------------------------------------------
  391.  
  392. The following web page has a Hello World example that you can download 
  393. demonstrating how to create a simple Java application that runs on, 
  394. and is bundled with, the Java Runtime Environment.  
  395.  
  396.      http://java.sun.com/products/jdk/1.1/jre/example/
  397.  
  398. This example shows how to make a simple, seamless transition
  399. from developing an application with the JDK, to deploying it with 
  400. the more-lightweight JRE.
  401.  
  402.  
  403. -----------------------------------------------------------------------
  404. RUNTIME DOCUMENTATION
  405. -----------------------------------------------------------------------
  406.  
  407. Runtime documentation is any documentation that an end-user might
  408. need after they have installed a Java program that runs on the JRE.
  409.  
  410. We supply the following runtime documentation:
  411.  
  412.   - Each property file contains comments that describe what the
  413.     file is useful for and how to modify it.
  414.  
  415.   - awt.properties file - KeyEvent uses it to print out properties of
  416.     key events, usually for debugging purposes.  This might be used
  417.     by a GUI debugger that needs to print out events.
  418.  
  419.   - fontprop.html file has a web page describing how to add 
  420.     fonts to the runtime.  This document is part of the 
  421.     JDK documentation, and is located both in the JDK documentation
  422.     download bundle and at the JavaSoft website:
  423.  
  424.     http://java.sun.com/products/jdk/1.1/docs/guide/intl/fontprop.html
  425.  
  426.  
  427. -----------------------------------------------------------------------
  428. Copyright ⌐ 1997 Sun Microsystems, Inc.
  429. 2550 Garcia Ave., Mountain View, CA 94043-1100 USA.
  430. All rights reserved.
  431.  
  432.