Java Technology Home Page

   Try the Applet Menu

What's New Products & APIs Documentation Applets For Developers Java Technology in the Real World Business & Licensing Support & Services Employment Java Store A-Z Index

java.sun.com - The Source for Java Technology java.sun.com - The Source for Java Technology Feedback Map Search
JDK 1.2
Documentation Installation Instructions
Solaris and Microsoft Windows

Japanese

Documentation Installation Instructions

This procedure describes how to install the JDK documentation that you have already downloaded. The compressed file that you download is called the documentation bundle.

  1. If necessary, concatenate all the pieces together
  2. Check the bundle size
  3. Where to unbundle your documentation
  4. Unbundle your documentation
  5. View the documentation
If you have installation problems, please send us email at: Website Feedback. If the installation instructions could be clearer, please send email to Documentation.

1. If necessary, concatenate all the pieces together

If you have downloaded the documentation in pieces instead of a single bundle, do this step:

Steps to concatenate the pieces together (below)

The final size should be the same as that given in the next step.

2. Check the bundle size
Check to see that the complete file was downloaded:
      jdk12-doc.zip       16,897,834 bytes 
      jdk12-doc.tar.gz    10,164,574 bytes
      jdk12-doc.tar.Z     21,669,598 bytes
3. Where to unbundle your documentation
By default, unbundling the JDK documentation creates a jdk1.2 directory with a docs subdirectory, putting all the documentation inside that docs directory, as shown below. You should install the JDK documentation into the same directory as you install the JDK software (and can install them in either order). This enables the links between the software and documentation to work.

  • If using WinZip -- accept the default directory of jdk1.2.

  • If using a command-line zip or tar tool -- you should unbundle the documentation in the parent directory of the jdk1.2 directory. For example:
    • Windows: If your jdk1.2 directory is located at C:\jdk1.2, then you should switch the current directory to C:\ before unbundling the docs:
         C:> cd \
      
    • Solaris: if your jdk1.2 directory is located at /usr/local/jdk1.2, then you should switch the current directory to /usr/local/ before unbundling the docs:
          % cd /usr/local/
      

4. Unbundle your documentation
Unbundle the documentation using the appropriate utility: winzip, unzip, gunzip, pkunzip, uncompress, or tar. Your utility must support long file names.

Choosing a program to install the docs: The download bundles have identical documentation content and differ only in the compression format, so theoretically any bundle can be installed on any OS with a program that handles that format. However, do not try to install the COMPRESS tar or GZIP tar formats with WinZip or other non-Solaris versions of tar. About 10 of the included files have unbundled paths that are 100 characters or longer, and these programs will not install them correctly. For more details, see the troubleshooting tip.

  • For the WinZip program, run the program and accept jdk1.2 as the default directory.

  • For .zip files:

    C:> unzip jdk12-doc.zip

    Note: If you're using another tool that doesn't preserve path names by default, be sure to specify that path names be preserved. If you're using pkunzip, for example, specify -d:

    C:> pkunzip -d jdk12-doc.zip

  • For .tar.gz files:

    % gunzip jdk12-doc.tar.gz
    % tar xvf jdk12-doc.tar

  • For .tar.Z files:

    % uncompress jdk12-doc.tar.Z
    % tar xvf jdk12-doc.tar

Unbundling the documentation bundle creates a jdk1.2/docs/ directory containing your JDK documents, as shown below.
5. View the documentation

Open the jdk1.2/docs/index.html page in a browser. This is the front page and contents of the JDK documentation.


JDK Directory Structure
Installing the JDK software and documentation creates the following directory structure. The directories shown in bold are installed with the JDK documentation bundle.
                      jdk1.2
     ______________________|____________________________
    |    |    |    |     |   |  |   |     |   |     |   |
    |  README | LICENSE bin lib | include | src.jar | docs
    |         |          |   |  |   |     |         |   |
README.html COPYRIGHT          jre    include-old  demo |
                              __|__       |         |   |
                             |     |                    |
                            bin   lib                   |
                             |     |                    |
                                                        |
                 _______________________________________|_
                |        |     |       |         |        |
           index.html  guide  api  tooldocs  relnotes  images 
                         |     |       |         |        |
If you don't unbundle the documentation at the proper directory, the HTML links from docs/index.html to the README, CHANGES, COPYRIGHT, LICENSE, and demo files will be broken.

Steps to concatenate the pieces together 

After downloading these files, follow the steps below to join them into one. Unbundle the documentation using the appropriate utility: winzip, unzip, gunzip or pkunzip. Your utility must support long file names.

You need enough disk space for these files plus the resulting file.

    jdk12-doc-a.zip 
    jdk12-doc-b.zip 
    jdk12-doc-c.zip 
    jdk12-doc-d.zip 
    jdk12-doc-e.zip 
  • Windows - Use copy to join the pieces into a single file:

    C:\>  copy /b jdk12-doc-a.zip + jdk12-doc-b.zip + 
    jdk12-doc-c.zip + jdk12-doc-d.zip + jdk12-doc-e.zip 
    jdk12-doc.zip 
    

  • Solaris - Use cat to join the pieces into a single file:

    % cat jdk12-doc-a.zip jdk12-doc-b.zip jdk12-doc-c.zip \ 
    jdk12-doc-d.zip jdk12-doc-e.zip > jdk12-doc.zip 
    

The resulting concatenated file should be the same size as the jdk12-doc.zip file as given in the next step.


Troubleshooting the Doc Installation
  • WinZip and other non-Solaris versions of tar do not properly unbundle the Compressed tar (tar.Z) and GZIP tar (tar.gz) versions of the docs. WinZip and Cygnus GNU tar are two such incompatible programs. This problem occurs because about 10 of the included files have paths (including filenames) that exceed 99 characters, and there is no universal way of handling files of this length in the tar format. If you're not on Solaris, use the zip format instead. If you have a version of the jar tool, you can use that to unbundle the zip format. WinZip does unbundle "tar" files, but not if they contain paths that exceed 99 characters. Developers prefer to download the tar versions because they are smaller than the zip version.

    If you have downloaded a tar version and installed it with a non-Solaris program, the files whose paths exceed 99 characters will be installed in the same directory where you are expanding the tar package, which is the wrong location, so links to them will be broken. The JDK doc bundle contains the following files whose paths (including filename) exceed 99 characters:

    JComponent.AccessibleJComponent.AccessibleContainerHandler.html
    JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink.html
    JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry.html
    BasicFileChooserUI.ChangeToParentDirectoryAction.html
    BasicInternalFrameTitlePane.PropertyChangeHandler.html
    BasicTreeUI.SelectionModelPropertyChangeHandler.html
    BasicInternalFrameUI.InternalFramePropertyChangeListener.html
    BasicInternalFrameUI.BasicInternalFrameListener.html
    BeanContextServicesSupport.BCSSServiceProvider.html
    BeanContextServicesSupport.BCSSProxyServiceProvider.html
    
    For the full, correct paths, see: Correct Paths.

    The result is that the path to these files is stripped off, and they are installed in the jdk1.2 directory. Workaround: Download the ZIP file and unbundle it. (If on Windows, unbundle it with WinZip.)

    Background: The original tar format supports a maximum path size of 99 characters. If you use Solaris tar, you will not see a problem, because Solaris tar extends this format beyond 99 characters but in a Solaris-only way. GNU tar has a different way of extending the format, so is incompatible with the Solaris tar. WinZip and Cygnus GNU tar 1.11.8 do not support the Solaris way. We recommended that you use Solaris tar to extract the archive, or use the jar tool or WinZip to extract the zip version.


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

 

This page was updated: Thursday, 10-Dec-1998 08:24:46 PST


What's New | Read | Products | Applets | For Developers
Real World Java | Business | Marketing | Employment | Java Store
FEEDBACK | SUPPORT & SERVICES | MAP | A-Z INDEX
 

For information, call:
(800) 786-7638
Outside the U.S. and Canada, dial your country's AT&T Direct Access Number first.

Copyright © 1995-99 Sun Microsystems, Inc.
All Rights Reserved. Legal Terms. Privacy Policy.