Documentation Installation Instructions

This procedure describes how to install the Java^TM 2 SDK 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

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.

Check to see that the complete file was downloaded:

      jdk1_2_2-001-doc.tar.Z     22,796,527  bytes
      jdk1_2_2-001-doc.tar.gz    10,781,242  bytes
      jdk1_2_2-001-doc.zip       17,628,120  bytes 

By default, unbundling the Java 2 SDK documentation creates a jdk1.2.2 directory 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 jdk1.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: Let's say you want to end up with this jdk1.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. 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 extract to the directory described in the previous step.

• For .zip files:
  

  C:> unzip jdk1_2_2-001-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 jdk1_2_2-001-doc.zip
  

• For .tar.gz files:
  

  % gunzip jdk1_2_2-001-doc.tar.gz
% tar xvf jdk1_2_2-001-doc.tar
  

• For .tar.Z files:
  

  % uncompress jdk1_2_2-001-doc.tar.Z
% tar xvf jdk1_2_2-001-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.

    jdk1_2_2-doc-001-a.zip 	1,400,000 bytes
    jdk1_2_2-001-doc-b.zip 	1,400,000 bytes
    jdk1_2_2-001-doc-c.zip 	1,400,000 bytes
    ...
    jdk1_2_2-001-doc-m.zip  828,120 bytes

• Windows - Open the DOS Prompt window (on 95 or 98) or Command Prompt window (on NT). Switch to the directory containing the files you downloaded. Use copy to join all the pieces into a single file:

  C:\>  copy /b jdk1_2_2-001-doc-a.zip + 
  jdk1_2_2-001-doc-b.zip + jdk1_2_2-001-doc-c.zip + 
  jdk1_2_2-001-doc-d.zip + jdk1_2_2-001-doc-e.zip +
  jdk1_2_2-001-doc-f.zip + jdk1_2_2-001-doc-g.zip +
  jdk1_2_2-001-doc-h.zip + jdk1_2_2-001-doc-i.zip +
  jdk1_2_2-001-doc-j.zip + jdk1_2_2-001-doc-k.zip +
  jdk1_2_2-001-doc-l.zip + jdk1_2_2-001-doc-m.zip
  jdk1_2_2-001-doc.zip 
  

• Solaris - Open a command shell. Switch to the directory containing the files you downloaded. Use cat to join the pieces into a single file:

  % cat jdk1_2_2-001-doc-a.zip jdk1_2_2-001-doc-b.zip \
  jdk1_2_2-001-doc-c.zip jdk1_2_2-001-doc-d.zip jdk1_2_2-001-doc-e.zip \
  jdk1_2_2-001-doc-f.zip jdk1_2_2-001-doc-g.zip jdk1_2_2-001-doc-h.zip \
  jdk1_2_2-001-doc-i.zip jdk1_2_2-001-doc-j.zip jdk1_2_2-001-doc-k.zip \
  jdk1_2_2-001-doc-l.zip jdk1_2_2-001-doc-m.zip \
  > jdk1_2_2-001-doc.zip 
  

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

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

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