Documentation Installation Instructions

Print-friendly Version

Installation Instructions | Troubleshooting

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

1. Check the bundle size
2. Where to unbundle your documentation
3. Unbundle your documentation
4. View the documentation

1. Check the bundle size

Check to see that the complete file was downloaded:

      jdk-1_2_2_006-doc.tar.Z     22,877,151  bytes
      jdk-1_2_2_006-doc.tar.gz    10,832,069  bytes
      jdk-1_2_2_006-doc.zip       17,871,213  bytes 

By default, unbundling the Java 2 SDK documentation creates a jdk 1.2.2 directory (folder) with a docs subdirectory, putting all the documentation inside that docs directory, as shown below. (If those directories already exist, the installers simply skip the steps of creating them.) You should install the Java 2 SDK software documentation into the same directory as you install the Java 2 SDK software (and can install them in either order). This enables the links between the documentation in the software and documentation bundles to work.

• Microsoft Windows: Let's say you want to end up with the jdk 1.2.2 directory located at C:\. If using a command-line zip or tar tool, you should switch the current directory to C:\ before unbundling the docs in the next step:

     C:> cd \
  

  If using WinZip, extract to C:\.

• Solaris Operating Environment: Let's say you want to end up with this jdk 1.2.2 directory located at /usr/local/, then you should switch the current directory to /usr/local/ before unbundling the docs:

      % cd /usr/local/
  

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. About 10 of the included files have unbundled paths that are 100 characters or longer, and some versions of WinZip and other non-Solaris utilties will not install these correctly from the compressed tar and gzip bundles. For more details, see the troubleshooting tips.

• For the WinZip program, run the program and extract to the directory described in the previous step.

• For .zip files:
  

  C:> unzip jdk-1_2_2_006-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 jdk-1_2_2_006-doc.zip
  

• For .tar.gz files:
  

  % gunzip jdk-1_2_2_006-doc.tar.gz
% tar xvf jdk-1_2_2_006-doc.tar
  

• For .tar.Z files:
  

  % uncompress jdk-1_2_2_006-doc.tar.Z
% tar xvf jdk-1_2_2_006-doc.tar
  

Unbundling the documentation bundle creates a jdk1.2.2/docs/ directory containing your SDK software documents, as shown below.

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

Installing the Java 2 SDK software and documentation creates the following directory structure. The directories shown in bold are installed with the documentation bundle.

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

• WinZip and other non-Solaris versions of tar may 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 may 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 Java 2 SDK 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

  
  

  The result is that the path to these files is stripped off, and they are installed in the jdk1.2.2 directory. Workaround: Download the ZIP file and unbundle it. (If on Microsoft 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.