home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / README < prev    next >
Encoding:
Text File  |  1998-03-20  |  41.7 KB  |  1,038 lines
  1.                                 README
  2.  
  3.                        Java(tm) Development Kit
  4.                      JDK(tm) 1.2 Beta 3 Software
  5.                   
  6. -----------------------------------------------------------------------
  7. CONTENTS
  8.  
  9.      Introduction
  10.      Summary of Significant Known Bugs
  11.      Coming Feature Enhancements
  12.      Version Compatibility
  13.      What the JDK Software Contains
  14.      Reporting Bugs
  15.      Where to Find More Information
  16.      Just-in-Time (JIT) Compilers
  17.      Threads Packages for the Solaris JDK Software
  18.        - Native Threads versus Green Threads
  19.        - System Requirements for Native Threads
  20.        - Overriding the Default Threads Package
  21.      Deploying Java Applications
  22.  
  23.  
  24. -----------------------------------------------------------------------
  25. Introduction
  26. -----------------------------------------------------------------------
  27. Thank you for downloading this beta release of version 1.2 of the Java 
  28. Development Kit. The Java Development Kit is a development environment 
  29. for writing applets and applications that conform to the API of version 
  30. 1.2 of the Java platform. The JDK 1.2 software includes improvements in 
  31. performance and functionality over version 1.1.x.   
  32.  
  33. The primary purposes of this beta release are:
  34.  
  35.    - To let you try the new APIs and features with your applications 
  36.      and applets so you can give us feedback on the design and 
  37.      implementation.
  38.  
  39.    - To enable you to report bugs that you encounter.  See "Reporting 
  40.      Bugs" below for information on submitting bug reports.
  41.  
  42.  
  43. This release of the JDK software is available for Windows 95/NT, 
  44. Solaris SPARC, and Solaris x86.  Its compiler and other tools are run 
  45. from the command line and have no GUI interface.
  46.      
  47.      DISCLAIMER - This beta release is known to contain bugs.  Do not 
  48.      rely on this software for production-quality applications or for 
  49.      mission-critical applications. Portions of the APIs for some new 
  50.      features in this release have not been finalized, and APIs may 
  51.      change in response to feedback. Some features are not fully 
  52.      implemented in this release. See "Summary of Incomplete Features 
  53.      and Significant Known Bugs" below.
  54.  
  55.      The implementations of the new features in this beta release are 
  56.      still being tuned for performance.  The software contains 
  57.      debugging and analysis hooks that degrade performance. These will 
  58.      be removed in the final release.
  59.  
  60.  
  61. The Java platform version 1.2 API offers new functionality and 
  62. enhancements in the following areas:
  63.  
  64.       - Security Enhancements
  65.          - Policy-based Access Control
  66.          - Certificate Interfaces
  67.          - x.509 v3 Implementation
  68.          - The keytool, jar, jarsigner, and policytool tools
  69.       - Java Foundation Classes (JFC) (tm) software
  70.          - Java 2D
  71.          - User-Interface Components (Swing Package) 
  72.          - Accessibility
  73.          - Drag & Drop
  74.          - Application Services
  75.       - JavaBeans(tm) Enhancements 
  76.          - Interaction with Applet Semantics
  77.          - Better Design-Time Support
  78.          - JavaBeans Runtime Containment and Services Protocol
  79.       - Collections 
  80.       - Version Identification
  81.       - RMI Enhancements  
  82.          - Remote Object Activation
  83.          - Custom Socket Types
  84.          - Minor API Enhancements
  85.       - Serialization Enhancements
  86.          - Persistent Field API 
  87.       - Reference Objects (including weak references)  
  88.       - Audio Enhancements
  89.          - Java Sound(tm) software
  90.          - getNewAudioClip Method
  91.       - Performance Enhancements 
  92.          - Solaris Native Thread Support
  93.          - Memory Compression for Loaded Classes
  94.          - Faster Memory Allocation and Garbage Collection
  95.          - Monitor Speedups
  96.          - Native Library JNI Port
  97.          - JIT Compilers
  98.       - Extensions Framework
  99.       - Java IDL
  100.       - Input Method Framework
  101.       - JAR Enhancements
  102.       - JNI Enhancements
  103.       - Reflection Enhancements
  104.       - JDBC(tm)-ODBC Bridge Enhancements
  105.       - Servlet (a standard extension)
  106.       - Javadoc Doclets (a tool)
  107.       - Java Virtual Machine Debug Interface
  108.  
  109. In this release, some of the new features are not fully implemented or 
  110. have known bugs. See the following section for details.
  111.  
  112.  
  113. -----------------------------------------------------------------------
  114. Summary of Significant Known Bugs
  115. ----------------------------------------------------------------------- 
  116. See the disclaimer in the Introduction for comments applicable to all 
  117. new features.
  118.  
  119. ____________________
  120. Extensions Framework
  121.  
  122. This release includes a preliminary implementation of the Java
  123. Extensions Framework. However, extensions are not enabled by default. 
  124. To launch a program with extensions, use the java launcher tool with 
  125. the -new option:
  126.  
  127.     java -new MyClass
  128.     java -new -jar foo.jar
  129.  
  130. The jre launcher may also be used with the -new option to run 
  131. programs that use extensions:
  132.  
  133.     jre -new MyClass
  134.     jre -new -jar foo.jar
  135.  
  136. A later release will add full extensions support, and the -new option 
  137. will be removed.
  138.  
  139. This release does not support applets that use extensions. 
  140.  
  141. For more information on using the Extensions Framework, see 
  142. http://java/sun.com/products/jdk/1.2/docs/guide/extensions
  143.  
  144.  
  145. ___________________________________
  146. Parsing Bug and HotJava(tm) Browser
  147.  
  148. The HotJava browser may crash when run on Windows 95 using this 
  149. release as a Java runtime environment. (Bug 4098718.) This is a 
  150. result of a bug in the code for parsing security configuration files. 
  151. This bug is not in the HotJava software, and will not appear when the 
  152. browser uses its bundled Java runtime environment (JDK_HOME is not 
  153. set). A temporary workaround is to remove or rename the "groups" file 
  154. in the .hotjava\security1.1 directory off the HotJava browser 
  155. installation directory. If, for example, the HotJava browser is 
  156. installed in c:\hotjava1.1, you should remove or rename
  157.  
  158.     c:\hotjava1.1\.hotjava\security1.1\groups
  159.  
  160. This bug will be fixed in the next release.
  161.  
  162. ________
  163. JDBC(tm)
  164.  
  165. This release includes a preliminary version of the JDBC 2.0 API. It is
  166. possible that part of this API, the java.sql package, will have further
  167. changes before the JDK 1.2 API is frozen.
  168.  
  169. _________________________
  170. Windows Registry Settings
  171.  
  172. When you install the Java Development Kit, the installer will add 
  173. a registry key::
  174.  
  175.    \\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.2
  176.  
  177. It will also change the value of the CurrentVersion setting in 
  178. the 
  179.  
  180.    \\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit  
  181.  
  182. registry to 1.2.  
  183.  
  184. If you have previously installed JDK 1.1.x software on your machine, 
  185. your registry will also contain the following branch:
  186.  
  187.    \\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.1
  188.  
  189. Uninstalling the Windows version of JDK 1.2 software will erase the 
  190. registry entries for version 1.1.x as well as those for version 1.2. 
  191. If you uninstall the JDK 1.2 Beta 3 software, you should first save 
  192. the settings in the 1.1 branch of the registry by using regedit. (To 
  193. run regedit, go into the Start menu, select Run, type regedit in the 
  194. text field, and type return. You can also run regedit by issuing the 
  195. regedit command from a DOS prompt.)
  196.  
  197. BEFORE UNINSTALLING THE JDK SOFTWARE:
  198.  
  199. Select the 1.1 registry key (\\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java
  200. Development Kit\1.1), and export it to a file (jdk1.1registry, for
  201. example). You can do this by using the "Export registry file" menu item
  202. in regedit's "Registry" menu.
  203.  
  204. AFTER UNINSTALLING THE JDK SOFTWARE:
  205.  
  206. - Import the 1.1 registry file (jdk1.1registry) that you exported 
  207. before the uninstall. You can do this by using the "Import registry 
  208. file" menu item in regedit's "Registry" menu.
  209.  
  210. - In the Java Development Kit registry key
  211.  
  212. \\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit
  213.  
  214. select the "CurrentVersion" string value, and modify it to "1.1". You 
  215. can do this by using the "modify" menu item in regedit's "Edit" menu.
  216.  
  217. This problem will be corrected in the next beta release.
  218.  
  219. _________________________________________
  220. User Interface Components (Swing Package)
  221.  
  222. This version of the Java Development Kit includes release 1.0 of the 
  223. Swing user interface components.  
  224.  
  225. Performance tuning of Swing is continuing throughout the Beta cycle 
  226. of the Java Development Kit. 
  227.  
  228. To get the latest information on Swing, and download any  
  229. new versions of the Swing libraries released subsequent to this Java 
  230. Development Kit, see the Swing Connection at
  231.  
  232.     http://java.sun.com/products/jfc/swingdoc-current/
  233.  
  234.  
  235. ___
  236. AWT
  237.  
  238. When a TextField is added to a Dialog, the background and foreground 
  239. colors both default to black.  (Bug 4118918)
  240.  
  241. Mouse event objects are sometimes constructed with incorrect button
  242. modifiers. On Solaris, MousePressed never has BUTTON1_MASK set, even if
  243. Button 1 is down. On Windows, MouseDragged never has BUTTON1_MASK set,
  244. even if Button 1 is down. (Bugs 4117489, 4117523, 4117525.)
  245.  
  246. Due to synchonization problems, crashes can sometimes occur if multiple 
  247. AWT threads attempt to access the same List component. This bug 
  248. exists on both Solaris and Windows platforms. (Bug 4116233)
  249.  
  250. On Windows 95, application crashes can sometimes occur when a TextField 
  251. instance is created that contains more than 255 bytes of text.  The 
  252. problem can occur, for example, when setText() is called before calling 
  253. pack() or setVisible(). (Bug 4118571)
  254.  
  255.  
  256. ___________________
  257. Drag and Drop (JFC)
  258.  
  259. Known problems with using Drag and Drop:
  260.    - There is a four second startup overhead associated with the 
  261.      first drag on Windows platforms.
  262.    - The drag and drop subsystem gets a security exception when 
  263.      run under java -usepolicy.  The DropTarget class gets an 
  264.      ExceptionInInitializerError. (Bug 4114251)
  265.    - Drag and Drop doesn't work with Swing components on Solaris 
  266.      due to a bug in the Swing event mechanism. (Bug 4087309)
  267.    - Drag and Drop text from native (CDE) to the Java virtual 
  268.      machine crashes the virtual machine and its shell terminal 
  269.      on Solaris.  This problem is not present on Windows 
  270.      environments. (Bug 4118496)
  271.    - Drag and Drop text from native text controls to the Java virtual
  272.      machine fails on Windows 95. (Bug 4119256.)
  273.    
  274.  
  275. _____________
  276. Java 2D (JFC)
  277.  
  278. In this implementation of Java 2D, text drawn to an off-screen buffer
  279. may not look the same as text drawn directly to the screen when no 2D
  280. features are used.  The off-screen rendering uses a different rasterizer
  281. and may use different fonts.  This may also cause metrics to be different
  282. for on-screen vs. off-screen rendering.  To force Toolkit.getFontMetrics()
  283. to return off-screen metrics, you can use the following property:
  284.     
  285.    java -Djava2d.offfm=true <app>
  286.  
  287. Metrics problems will also cause the I-beam caret to appear in the
  288. wrong place in Swing, and Buttons/Tabs to have "..." in place of the
  289. full button/tab name.
  290.  
  291. Relevant text bugs:  4086564, 4100565, 4113796, 4116576
  292.  
  293. On Windows platforms, Java 2D uses the DirectDraw library, ddraw.dll,
  294. if available. If the JDK software crashes on startup, remove or rename 
  295. all copies of ddraw.dll on your system, reboot and try running the JDK 
  296. software again. If this fixes the problem, it indicates that your 
  297. ddraw.dll did not match your video card and you may want to download a 
  298. new ddraw.dll from the Microsoft DirectX web site 
  299. http://www.microsoft.com/directx/default.asp choosing "DirectX".   If 
  300. ddraw.dll is not available, Java 2D will use GDI calls, but using Direct 
  301. Draw will boost performance.
  302.  
  303. In this release, java.awt.Font does not support some non-8859-1 
  304. character sets (bug 4100565). This causes a problem, for example, on 
  305. Japanese Windows 95 where some fonts are not parsed correctly. The 
  306. TrueType Bitstream Cyberbit font, cyberbit.ttf, can be used as a 
  307. work-around for international font support.  This font can be 
  308. downloaded from 
  309.  
  310.    http://www.bitstream.com/cyberbit/ftpcyber.htm
  311.  
  312. You can set the JAVA_FONTS environment variable to point to 
  313. cyberbit.ttf or to any other non-system fonts:
  314.  
  315.    setenv JAVA_FONTS <font dir>       (on Solaris)
  316.    set JAVA_FONTS=<font dir>          (on Windows)
  317.  
  318. where <font dir> is the directory in which the fonts reside.
  319.  
  320. Use of fonts with the Solaris x86 JDK software results in a 
  321. segmentation violation. (Bug 4114152)
  322.  
  323. Lighweight text controls are sometimes slow to respond to keyboard
  324. input. The graphical complexity of the top-level container appears to
  325. be a contributing factor. This bug will be fixed in the next release.
  326. (Bug 4114384.)
  327.  
  328. ______________________
  329. Input Method Framework
  330.  
  331. To use input methods through the Internet-Intranet Input Method 
  332. Protocol (IIIMP), the extension file iiimp.jar needs to be added to 
  333. the class path. This file is located in the lib/ext directory of 
  334. your JDK installation. In the next release, this extension will be 
  335. loaded through the extension mechanism. (Bug 4118842)
  336.  
  337. In this release, text highlights are not drawn while the text is being
  338. composed. (Bug 4108510)
  339.  
  340.  
  341. ________________
  342. JAR Enhancements
  343.  
  344. The improvements to the command-line jar tool for creating and 
  345. updating signed JAR files have not been implemented in this release.
  346.  
  347. ______________________________
  348. Possible Problems with Winsock
  349.  
  350. When installing the JDK software on a Windows 95 system, the installer 
  351. will check to see if Winsock 2 is installed on the system. Winsock 2 is 
  352. the most recent version of the networking layer for Windows and is 
  353. published by Microsoft. If Winsock 2 isn't installed, the installer 
  354. will offer to install it.
  355.  
  356. Occasionally, some Windows configurations seem to be adversely 
  357. affected after installing Winsock 2.  Problems we have noted include  
  358. networking programs (such as news and mail readers, and browsers)  
  359. that stop working or crash.  (Bugs 4097887 and 4105761)
  360.  
  361. If this happens on your system, you can remove Winsock 2 using this 
  362. procedure:
  363.  
  364.    1. go to C:\Windows\WS2BAKUP directory
  365.    2. run the WS2BAKUP.BAT script
  366.    3. reboot your machine
  367.  
  368. The JDK software will continue to work properly without Winsock 2 by 
  369. using Winsock 1.1.  However, in applications that use the JDK software 
  370. and involve heavily multi-tasked network I/O, TCP connections may not 
  371. get closed properly, causing them to get reset unexpectedly. Most other 
  372. applications will be unaffected. We recommend that you upgrade to 
  373. Winsock 2 as soon as possible.
  374.  
  375. ____________
  376. Javadoc Tool
  377.  
  378. When operating on packages, the javadoc tool requires additional 
  379. memory and will taker longer to complete a run than when operating 
  380. on individual .java files (bug 4110216).  If you run into an 
  381. out-of-memory error because of this problem (or for any other 
  382. reason), you can increase the memory available to javadoc by using 
  383. the -J-ms<x> and -J-mx<x> options.  See the javadoc documentation 
  384. for more information on these options.
  385.  
  386. The -nodeprecatedlist and -nohelp javadoc options, listed in both 
  387. the command-line help and in the javadoc documentation, do not work 
  388. in this beta release.  They will be available in a future release.
  389.  
  390. ____________
  391. JIT Compiler
  392.  
  393. The JIT compilers are off by default in this release for both the 
  394. Windows and Solaris platforms.  Some bugs may be present only when 
  395. the JIT compilers are turned on.  For example, on the Solaris 
  396. platform, the Animator demo applets does not run with the JIT compiler 
  397. turned on (bug 4092493).
  398.  
  399. _____________________
  400. Locale Bug on Solaris
  401.  
  402. A bug in the class java.util.Locale can cause errors when run on
  403. Solaris. This problem only occurs when a program is run under a Solaris
  404. locale that does not include an ISO 3166 country name. Under these
  405. circumstances, the Solaris locale is mapped to a Java platform language
  406. locale, instead of a country locale. When this happens, the
  407. getISO3CountryCode() and getDisplayCountry() methods return incorrect
  408. values. This bug will be fixed in the next release. (Bug 4118731.)
  409.  
  410. As a workaround, you can directly set the default locale through the
  411. user.region property. For example, this command sets the default locale
  412. to "ja_JP":
  413.  
  414.     java -Duser.region=ja_JP MyClass
  415.  
  416. _________________
  417. Peer Bug on Win32
  418.  
  419. Some text controls, such as java.awt.TextArea, do not always handle
  420. large text strings correctly on Win32 systems. If, for example, you
  421. pass a 64K string to setText(), the control may display nothing. (Bug
  422. 4080391.)
  423.  
  424. This is not a bug in the JDK class libraries. The actual bug is in the
  425. "peer" control, the native platform control that actually appears on
  426. the screen. Win32 screen controls can only handle a limited amount of
  427. text. In theory, the limit is 32K. In practice, the limit may be as
  428. little as 20K or as much as 60K.
  429.  
  430. If you need text controls that can handle large text strings on Win32,
  431. use lightweight controls, such as java.awt.swing.JTextArea. Lightweight
  432. controls do not use peers, and can display any string that will fit in
  433. memory.
  434.  
  435. -----------------------------------------------------------------------
  436. Coming Feature Enhancements
  437. -----------------------------------------------------------------------
  438. Improvements to the new features of the 1.2 platform will be  
  439. implemented throughout the beta release cycle.   The JDK software will 
  440. continue to be tuned for performance and stability, and enhancements to 
  441. the functionality of some new features will be added prior to final 
  442. shipment.  The following list contains some of the feature improvements 
  443. that are expected in future releases of the 1.2 platform.
  444.  
  445. _____________
  446. Drag and Drop
  447.  
  448. The Beta 4 release will introduce two enhancements to Drag and Drop:
  449.  
  450.   1) support for file Drag and Drop
  451.  
  452.      This feature will allow the Java platform to more easily 
  453.      Drag and Drop lists of files to/from platform native 
  454.      applications.
  455.         
  456.      It defines a MIME "Content-Type" and data format 
  457.      (DataFlavor) to enable easier transfers of lists of files 
  458.      between applications.
  459.  
  460.   2) support for platform/device recognition of user initiating 
  461.      Drag-and-Drop gestures
  462.  
  463.      The gesture that a user uses in order to initiate a 
  464.      Drag-and-Drop operation varies from platform to platfrom, 
  465.      and also can differ in the device used to make the gesture 
  466.      itself.
  467.  
  468.      Using a DragGestureRecognizer, the developer can isolate 
  469.      their Drag-and-Drop code from these platform/device-specific 
  470.      dependencies.
  471.     
  472.     
  473. _____    
  474. Swing
  475.  
  476. Swing JText components will be enhanced to support "Complex Output" 
  477. (aka "BiDi"). This means specifically that JText will provide for 
  478. automatic reordering, shaping and placement of glyphs from the 
  479. Unicode scripts that require such processing, like Hebrew, Arabic 
  480. and Thai. For example: Hebrew and Arabic strings are ordered right-
  481. to-left, except for numerals; Arabic consonants take on different 
  482. shapes, depending on their adjoining context within words; Thai 
  483. vowel and tone diacritical marks have to be stacked properly when 
  484. more than one mark is used with a base consonant.  
  485.  
  486.  
  487. ______________________
  488. Input Method Framework
  489.  
  490. The Internet-Intranet Input Method Protocol (IIIMP) extension will 
  491. be available for use by applications in the Beta 4 release.  The 
  492. next beta release will also include these enhancements:
  493.  
  494.   - text highlights will be drawn while text is being composed. 
  495.   - expanded list of virtual key codes in java.awt.event.KeyEvent 
  496.     (RFE 4116859)
  497.  
  498.  
  499. _______
  500. Java 2D
  501.     
  502. Enhancements to the printing API will be added in Beta 4.
  503.  
  504.  
  505. ___________________
  506. Extension Framework
  507.  
  508. The Beta 4 release will add full extensions support. Extensions will be 
  509. enabled by default, and the interpreter's -new option will be removed.  
  510. The java and jre tools will be merged in Beta 4.
  511.  
  512.  
  513. ________________
  514. JAR Enhancements
  515.  
  516. Beta 4 will make improvements to the jar tool for creating and 
  517. updating signed JAR files and for adding and removing files from 
  518. JAR files.
  519.  
  520.  
  521. ____________________________
  522. Just-in-time (JIT) Compilers
  523.  
  524. The JIT compilers in the Windows and Solaris JDK software will be 
  525. on by default in Beta 4.
  526.  
  527.  
  528. -----------------------------------------------------------------------
  529. Version Compatibility
  530. -----------------------------------------------------------------------
  531. In general, any applet or application that ran in version 1.0.x or 
  532. version 1.1.x should run unmodified with this version 1.2 of the Java 
  533. platform. In a few cases, we have had to break version compatibility to 
  534. close potential security holes or fix implementation or design bugs. 
  535. All such cases are documented on the compatibility page at 
  536.  
  537.    http://java.sun.com/products/jdk/1.2/compatibility.html
  538.  
  539. We regard any version incompatibility not listed on the compatibility 
  540. page as a serious bug which we will fix, or, if that is not feasible, 
  541. document on the compatibility page.
  542.  
  543. Please report all version compatibility bugs (see the section 
  544. Reporting Bugs below).  Upwards version compatibility is critically 
  545. important to us, and is a cornerstone of the promise: Write Once, 
  546. Run Anywhere(tm).
  547.  
  548. Of course, applets that depend on any new APIs in this platform will not 
  549. work on browsers that support only earlier versions (1.0.x and 1.1.x) 
  550. of the platform.  However, in general, applets relying only on earlier 
  551. APIs but compiled with the compiler in this JDK will run on earlier 
  552. versions of browsers.  This "downwards" version compatibility has not 
  553. been extensively tested and cannot be guaranteed. 
  554.  
  555.  
  556. -----------------------------------------------------------------------
  557. What the JDK Software Contains
  558. -----------------------------------------------------------------------
  559. The executables are located in the bin directory, the class libraries
  560. are in the lib directory, and the demos are in the demo directory.
  561.  
  562. JAVA RUNTIME ----------------------------------------------------------
  563.  
  564.     - Java Core Classes (classes.zip)
  565.             DO NOT UNZIP THIS FILE!  It must remain zipped for the
  566.             compiler and interpreter to access the class files
  567.             within it properly.  This file contains all of the
  568.             the compiled .class files for the platform.
  569.  
  570.     - Libraries and Properties Files
  571.             Various supplementary files for use by the runtime 
  572.             environment.
  573.  
  574.  
  575. SOURCE FILES -----------------------------------------------------
  576.  
  577.     - Source Files for Public Classes 
  578.             (src.zip file or src directory)
  579.             This is the set of source files used to create the
  580.             classes included in the Java Core Classes classes.zip 
  581.             file (above).  These source files are provided for 
  582.             information purposes only, to help developers learn
  583.             and use the Java programming language.  They do not 
  584.             include the private java.* classes or the sun.* classes, 
  585.             and therefore cannot be compiled into a complete 
  586.             classes.zip file.
  587.  
  588.             Do not modify these classes; instead, create subclasses
  589.             and override where you need to. These classes are 
  590.             documented in the API Reference documentation, which is 
  591.             generated by the JDK software's javadoc tool.  
  592.  
  593.             How this is installed depends on the platform:
  594.  
  595.              - On Windows, these are automatically unzipped for you
  596.                during installation.
  597.  
  598.              - On Solaris, you must unzip the src.zip file yourself.
  599.               
  600. TOOLS ------------------------------------------------------------
  601.  
  602.     - Java Interpreter (java)
  603.             The launcher for the Java virtual machine that executes 
  604.             Java bytecodes. It runs programs written in the Java 
  605.             programming language and compiled to bytecodes.
  606.  
  607.     - Java Runtime Interpreter (jre)
  608.             Similar to the Java Interpreter (java), but intended for 
  609.             end users who do not require all the development-related 
  610.             options available with the java tool. 
  611.  
  612.     - Java Compiler (javac)
  613.             Compiles programs written in the Java programming language
  614.             into bytecodes.
  615.  
  616.     - Java AppletViewer (appletviewer)
  617.             Used for testing and running applets.
  618.  
  619.     - Java Debugger (jdb)
  620.             Helps you find bugs in programs written in the Java 
  621.             programming language.
  622.  
  623.     - Class File Disassembler (javap)
  624.             Disassembles compiled files and prints out a
  625.             representation of the bytecodes.
  626.  
  627.     - Java Documentation Generator (javadoc)
  628.             Parses the declarations and documentation comments in
  629.             a set of source files and produces a set of HTML pages
  630.             describing the public and protected classes, interfaces,
  631.             constructors, methods, and fields. Also produces
  632.             a class hierarchy and an index of all members. Javadoc 
  633.             now produces output with a different look and feel than 
  634.             does the JDK 1.1.x javadoc tool. 
  635.  
  636.     - C Header and Stub File Generator (javah)
  637.             For attaching native methods to code written in the 
  638.             Java programming language.
  639.  
  640.     - Java Archive Tool (jar)
  641.             Combines many class files and other resources
  642.             into a single Java ARchive (JAR) file.
  643.  
  644.     - JAR Signing and Verification Tool (jarsigner)
  645.             Generates signatures for Java ARchive (JAR) files, and 
  646.         verifies the signatures of signed JAR files.
  647.  
  648.     - Key and Certificate Management Tool (keytool)
  649.         Manages a keystore (database) of private keys and their 
  650.             associated X.509 certificate chains authenticating the 
  651.             corresponding public keys. Also manages certificates from
  652.             trusted entities.
  653.  
  654.     - Policy Tool (policytool)
  655.             Used to create and modify the external policy configuration 
  656.             files that define your installation's Java security policy.
  657.  
  658.     - Native-To-ASCII Converter (native2ascii)
  659.             Converts a native encoding file to an ascii
  660.             file that includes the \udddd Unicode notation.
  661.  
  662.     - Java RMI Stub Converter (rmic)
  663.             Generates objects from the names of compiled Java classes
  664.             that contain remote object implementations.
  665.  
  666.     - Java RMI Activation System Daemon (rmid)
  667.             Starts the activation system daemon so that objects can 
  668.             be registered and activated in a Java virtual machine.
  669.  
  670.     - Java Remote Object Registry (rmiregistry)
  671.             Creates and starts a remote object registry on the
  672.             specified port of the current host.
  673.  
  674.     - Serial Version Command (serialver)
  675.             Returns the serialVersionUID for one or more classes
  676.             in a form suitable for copying into an evolving class.
  677.  
  678.     - Java IDL Name Server (tnameserv)
  679.             Starts the Java IDL name server on the specified port.
  680.  
  681.     - Java Servlet Runner (servletrunner)
  682.             Used for running and testing servlets.
  683.  
  684.  
  685. JAVA DOCUMENTATION AND DEMOS ------------------------------------------
  686.  
  687.     - Applet Demos (demo/applets and demo/jfc directories)
  688.             The demo/applets directory contains applets that are useful 
  689.         as a "sanity" check to ensure that the JDK software is 
  690.             properly installed and running correctly. Demos of Swing 
  691.             set functionality are in the demo/jfc directory. Each Swing 
  692.             set demo has an associated README.txt file that contains 
  693.             information (such as recommended classpath settings) that 
  694.             will help you run the demos.
  695.  
  696.     - README
  697.             This file you are currently reading.
  698.  
  699.     - CHANGES
  700.             Lists new features added since version 1.1, and important 
  701.             changes since the previous release of this platform.
  702.  
  703.     - COPYRIGHT
  704.             Copyright notice for the JDK software.
  705.  
  706.     - LICENSE
  707.             License agreement for the JDK software.
  708.  
  709. NOTE: The JDK software does NOT include a Web browser.  To obtain the 
  710. HotJava(tm) Browser, see the HotJava Browser web page:
  711.  
  712.       http://java.sun.com/products/hotjava/
  713.  
  714.  
  715. -----------------------------------------------------------------------
  716. Reporting Bugs
  717. -----------------------------------------------------------------------
  718. To report bugs or feature requests, go to this web page:
  719.  
  720.      http://java.sun.com/cgi-bin/bugreport.cgi
  721.  
  722. Before submitting a bug report, you should check the Bug Parade web site 
  723. at 
  724.      
  725.      http://java.sun.com/jdc/bugParade
  726.  
  727. to see if your bug is a duplicate of a known problem.
  728.  
  729. When submitting a bug, be sure you include the version number of
  730. the JDK software you are running.  You can get the version number of 
  731. the JDK software by executing:
  732.  
  733.      java -version
  734.  
  735.  
  736. -----------------------------------------------------------------------
  737. Where to Find More Information
  738. -----------------------------------------------------------------------
  739. This README file and the accompanying LICENSE file, CHANGES file, 
  740. COPYRIGHT file, demo directory, and source code (src.zip) are the 
  741. only documentation included in the JDK software bundle.
  742.  
  743. You can find the full JDK documentation online at 
  744.    http://java.sun.com/products/jdk/1.2/docs
  745.  
  746. You can also download a complete set of JDK documentation from the Java 
  747. Developer Connection(sm) (JDC) web site: 
  748.  
  749.      http://java.sun.com/jdc/earlyAccess
  750.  
  751. The Java Developer Connection also has sites for technical support, 
  752. discussion forums and on-line training.  There is no charge to join 
  753. JDC; once you register, you have immediate access to the full site.
  754.  
  755.  
  756. -----------------------------------------------------------------------
  757. Just-in-Time (JIT) Compilers
  758. -----------------------------------------------------------------------
  759. This release includes JITs for Win32 and Solaris. A Just-In-Time
  760. bytecode compiler, or JIT, improves program performance by translating
  761. bytecodes into native code. In this release, the JIT is disabled by
  762. default. To enable the JIT, assign the JIT name to the JAVA_COMPILER
  763. environment variable or the java.compiler property.
  764.  
  765. On Windows the JIT name is symcjit. Either of the following command
  766. sequences runs an application under the JIT:
  767.  
  768.     java -Djava.compiler=symcjit MyClass
  769.  
  770.     set JAVA_COMPILER=symcjit
  771.     java MyClass
  772.  
  773. On Solaris, the JIT name is sunwjit. Either of the following command
  774. sequences runs an application under the JIT:
  775.  
  776.     java -Djava.compiler=sunwjit MyClass
  777.  
  778.     setenv JAVA_COMPILER sunwjit
  779.     java MyClass
  780.  
  781. For more information, see:
  782.     
  783.     http://java.sun.com/products/jdk/1.2/docs/#tools
  784.  
  785. The Win32 version of the JDK includes the Symantec JIT,
  786. Copyright ⌐ 1996-1998 by Symantec Corporation. All rights reserved.
  787.  
  788. -----------------------------------------------------------------------
  789. Threads Packages for the Solaris JDK Software
  790. -----------------------------------------------------------------------
  791. You have a choice of two threads packages on the Solaris JDK software. 
  792. One threads package enables the Java virtual machine (JVM) to use 
  793. Solaris native threads and the second threads package (called "green 
  794. threads") does not. By default, the JDK software uses the green threads 
  795. package. Some comparisons of the two threads packages are provided in 
  796. the section "Native Threads versus Green Threads" below.
  797.  
  798. IF YOU WANT TO USE THE GREEN THREADS PACKAGE: Green threads is the 
  799. default threads package for this JDK software. You will be using the 
  800. green threads package unless you specifically override it. See the 
  801. section "Overriding the Default Threads Package" below.
  802.  
  803. IF YOU WANT TO USE THE SOLARIS NATIVE THREADS PACKAGE: To use the
  804. native threads packages you will have to override the default green
  805. threads package. See the section "Overriding the Default Threads
  806. Package" below. Only specific versions of Solaris support native
  807. threads.  See the section "System Requirements for Native Threads"
  808. below.
  809.  
  810. IF YOU DON'T CARE WHICH THREADS PACKAGE YOU USE: If you don't run on 
  811. a multi-processor environment or for any reason don't care which 
  812. threads package you use, you can simply use the default green threads 
  813. package.
  814.  
  815.  
  816. Native Threads versus Green Threads -----------------------------------
  817.  
  818. Among the benefits of using the native threads JVM are:
  819.  
  820.      - If you run code in a multi-processor environment, the Solaris
  821.        kernel can schedule even threads at the level of the Java
  822.        programming language on multiple processors for increased
  823.        performance. By contrast, green threads exist only at the
  824.        user-level and are not mapped to multiple kernel threads by the
  825.        operating system. Performance enhancement from multiple
  826.        processors cannot be realized using green threads.
  827.  
  828.      - The native threads JVM can call into C libraries that use
  829.        Solaris native threads. Such libraries cannot be used with green
  830.        threads.
  831.  
  832.      - When using the native threads, the JVM can avoid some
  833.        inefficient remapping of I/O system calls that are necessary
  834.        when green threads are used.
  835.  
  836. In some instances, it may be advisable to use the green threads 
  837. package. Native code that is not multithread safe (MT-safe) may not 
  838. work correctly with native threads, and may not work correctly with 
  839. green threads either.  In general, if you aren't using the native 
  840. Solaris threads mechanisms directly, then you need to compile your 
  841. native code with the option -D_REENTRANT to make sure that they work 
  842. correctly in a threaded environment.  You may also need to use 
  843. reentrant versions of certain Solaris interfaces.  
  844.  
  845. Specific information concerning multithreaded programming on Solaris 
  846. may be found in the Multithreaded Programming Guide of the Solaris 
  847. Software Developer AnswerBook. This information is also available 
  848. at http://docs.sun.com. Navigate to the Tools link under the 
  849. Programming heading and go to the link Solaris 2.6 Software 
  850. Developer Collection Vol. 1.
  851.  
  852. It is possible that thread-synchronization bugs in code that you run 
  853. may be hidden when using green threads, but may manifest themselves 
  854. when run under native threads. You should consider this possibility if 
  855. your code runs differently under the two threads packages.
  856.  
  857.  
  858. System Requirements for Native Threads -------------------------------
  859.  
  860. To use Solaris Native Threads, you need Solaris 2.5.1 or Solaris 2.6.
  861. Earlier versions of Solaris, including Solaris 2.5, are not supported.
  862.  
  863. To support Native Threads, Solaris 2.5.1 needs two patches which
  864. resolve thread synchronization problems. On Solaris-SPARC, the
  865. required patches are 103566-08 and 103640-08. On Solaris-x86, the
  866. required patches are 104241-01 and 103641-08. The last two digits of
  867. the patch numbers indicate the patch version; you can use the
  868. indicated patch versions or later versions of the same patches.
  869.  
  870. To determine which patches are installed, use the shell command
  871. "showrev":
  872.  
  873. % showrev -p
  874.  
  875. You can obtain patches from your warranty provider, from SunService
  876. (if you have a SunSpectrum contract) or from the SunSolve web site.
  877. To obtain these patches from the SunSolve web site:
  878.  
  879.     1. Access the web site at http://sunsolve.sun.com/.
  880.  
  881.     2. Choose the "Public Patches" link.
  882.  
  883.     3. Download either the Solaris 2.5.1 Recommended Patch Cluster or
  884.        the Solaris 2.5.1 x86_Recommended Patch Cluster.
  885.  
  886.     4. Follow the instructions in the Patch Cluster README, available
  887.        from the "Public Patches" page.
  888.  
  889.  
  890. Overriding the Default Thread Packages --------------------------------
  891.  
  892. ---------------- The THREADS_FLAG Environment Variable ----------------
  893.  
  894. All the tools in the Solaris JDK software use green threads by default. 
  895. To specify that native threads should be used instead, set the 
  896. THREADS_FLAG environment variable to the value native:
  897.  
  898.     % setenv THREADS_FLAG native
  899.  
  900. You can revert to use of green threads by setting THREADS_FLAG to 
  901. the value green:
  902.  
  903.     % setenv THREADS_FLAG green
  904.  
  905.  
  906. ------------ The -native and -green Convenience Options ---------------
  907.  
  908. When using any of the JDK tools, you can specify native threads or 
  909. green threads by using the -native and -green convenience options. If 
  910. you use -native or -green, they must be the first option specified on 
  911. the command line. The convenience options can be used as in these 
  912. examples:
  913.  
  914.     % java -native mypkg.MyClass
  915.     % appletviewer -green foo.html
  916.  
  917. Using a convenience option overrides the setting of the THREADS_FLAG 
  918. environment variable.
  919.  
  920.  
  921.  
  922. =======================================================================
  923.               DEPLOYING JAVA APPLICATIONS
  924. =======================================================================
  925.  
  926. A Java application, unlike a Java applet, cannot rely on a web browser
  927. for installation and runtime services. When you deploy a Java
  928. application, your software bundle will probably consist of the
  929. following parts:
  930.  
  931.       * Your own class, resource, and data files.
  932.  
  933.       * A runtime environment.
  934.  
  935.       * An installation procedure or program.
  936.  
  937. The first item, you already have, of course. The remainder of this
  938. section covers the other two items.
  939.  
  940. -----------------------------------------------------------------------
  941. RUNTIME ENVIRONMENT
  942. -----------------------------------------------------------------------
  943. To run your application, a user needs a Java virtual machine, the Java
  944. platform core classes, and various support programs and files. This
  945. collection of software is known as a runtime environment.
  946.  
  947. The JDK software serves as a runtime environment. However, you probably
  948. can't assume your users have the JDK software installed, and your JDK
  949. software license doesn't allow you to redistribute JDK software files.
  950.  
  951. JavaSoft provides a free, redistributable runtime environment called
  952. the Java Runtime Environment. Versions of this are are available for
  953. all platforms that run the JDK software. The Java Runtime Environment
  954. Version 1.2 Beta 3 is available for download at: 
  955.  
  956.     http://developer.javasoft.com/developer/earlyAccess/jdk12/
  957.  
  958. The Win32 versions comes with a built-in installation program suitable
  959. for end-users. Solaris versions require the developer to provide
  960. installation support.
  961.  
  962. The Java Runtime Environment for Win32 is available both with and
  963. without international support. The non-international version is much
  964. smaller, but is suitable only for English-speaking users. 
  965.  
  966. JavaSoft is not the only supplier of runtime software for Java
  967. programs. If you use a third-party runtime, you should make sure it is
  968. fully compatible with the Java Runtime Environment.
  969.  
  970. For information on third-party runtime environments, see:
  971.  
  972.     http://java.sun.com/cgi-bin/java-ports.cgi
  973.  
  974.  
  975. -----------------------------------------------------------------------
  976. INSTALLATION
  977. -----------------------------------------------------------------------
  978. The final step in the deployment process occurs when the software is
  979. installed on individual user system. Installation consists of copying
  980. software onto the user's system, then configuring the user's system to
  981. support that software.
  982.  
  983. This step includes installing and configuring the runtime environment.
  984. If you use the Java Runtime Environment, you must make sure that your
  985. installation procedure never overwrites an existing installation,
  986. unless the existing Java Runtime Environment is an older version.
  987.  
  988. The Win32 version of the Java Runtime Environment is distributed as a
  989. self-installing executable. A simple way to redistribute the Java
  990. Runtime Environment is to include this executable in your software
  991. bundle. You can then have your installation program run the executable,
  992. or simply instruct the user to install the Java Runtime Environment
  993. before installing the rest of your bundle.
  994.  
  995. The Win32 installation program records program information in the
  996. Windows Registry. This registry information includes the software
  997. version, which you should compare with the Java Runtime Environment
  998. version in your software bundle. For more information, refer to the the
  999. Java Runtime Environment Notes for Developers at:
  1000.  
  1001.     http://java.sun.com/products/jdk/1.2/runtime.html
  1002.  
  1003. A more sophisticated approach is to install the Java Runtime
  1004. Environment on your own system, then copy the files you need into your
  1005. own installation set. If you choose this approach, you must include all
  1006. files described as "required" in the Java Runtime Environment README.
  1007. The Java Runtime Environment software can only be redistributed if all
  1008. "required" files are included. See the LICENSE file for specifics.
  1009.  
  1010. If you use this approach, do not try to emulate the installation steps
  1011. performed by the Java Runtime Environment installer. You might "break"
  1012. an existing Java Runtime Environment installation by missing a new or
  1013. undocumented installation step. Instead, you should include the Java
  1014. Runtime Environment files in your own application directory. In effect,
  1015. your application has its own "private" copy of the Java Runtime
  1016. Environment.
  1017.  
  1018. If your application uses the networking classes, it may not run
  1019. reliably under Winsock 1.1. (See "Possible Problems with Winsock,"
  1020. above.) If your networking application must support Windows 95, which
  1021. comes with Winsock 1.1, you will want to include a Winsock 2.0 install
  1022. in your installation procedure. (Windows NT 4.0 and Windows 98 come
  1023. with Winsock 2.0.) To provide Winsock 2.0, you need the Microsoft
  1024. Windows Sockets 2.0 Software Development Kit. This free software can be
  1025. downloaded from the following addresses:
  1026.  
  1027.     http://www.microsoft.com/win32dev/netwrk/winsock2/ws295sdk.html
  1028.     http://www.microsoft.com/windows95/info/ws2.htm
  1029.     ftp://ftp.microsoft.com/bussys/WinSock/winsock2/
  1030.  
  1031. ======================================================================
  1032. The Java Development Kit is a product of Sun Microsystems(tm), Inc.  
  1033. JavaSoft(tm) is the operating company of Sun that develops the JDK.
  1034.  
  1035. Copyright ⌐ 1997, 1998 Sun Microsystems, Inc.
  1036. 901 San Antonio Road, Palo Alto, California 94303-4900 USA.
  1037. All rights reserved.
  1038.