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:

j2sdk-1_3_0-update1-doc.zip        22334884 bytes
j2sdk-1_3_0-update1-doc.tar.gz     13186129 bytes
j2sdk-1_3_0-update1-doc.tar.Z      28361013 bytes

By default, unbundling the Java 2 SDK documentation creates a jdk1.3 directory (folder) with a docs subdirectory, putting all the documentation inside that docs directory as shown here.

                          jdk1.3
                            |
                           docs
         ___________________|_____________________
        |        |     |       |         |        |
    index.html guide  api   tooldocs  relnotes  images
                 |     |       |         |        |

The Linux and Microsoft Windows versions of the Java 2 SDK are installed by default into a directory named jdk1.3. Therefore if you install the documentation in the same directory in which you installed the SDK, the docs directory will be automatically placed inside the jdk1.3 directory of your SDK installation.

• Microsoft Windows: Let's say you want to end up with the jdk1.3 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 and Linux: Let's say you want to end up with this jdk1.3 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.

Note: The jar utility included with the Java 2 SDK is capable of extracting the contents of the .zip documentation bundle. See the .zip file instructions below for details.

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 j2sdk-1_3_0-update1-doc.zip

  OR

  C:> jar xvf j2sdk-1_3_0-update1-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 j2sdk-1_3_0-update1-doc.zip
  

• For .tar.gz files:
  

  % gunzip j2sdk-1_3_0-update1-doc.tar.gz
% tar xvf j2sdk-1_3_0-update1-doc.tar
  

• For .tar.Z files:
  

  % uncompress j2sdk-1_3_0-update1-doc.tar.Z
% tar xvf j2sdk-1_3_0-update1-doc.tar
  

Unbundling the documentation bundle creates a jdk1.3/docs/ directory containing your SDK software documents.

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

    j2sdk-1_3_0-update1-doc-a.zip 	1,400,000 bytes
    j2sdk-1_3_0-update1-doc-b.zip 	1,400,000 bytes
    j2sdk-1_3_0-update1-doc-c.zip 	1,400,000 bytes
    ...
    j2sdk-1_3_0-update1-doc-p.zip	1,334,884 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 j2sdk-1_3_0-update1-doc-a.zip + 
  j2sdk-1_3_0-update1-doc-b.zip + j2sdk-1_3_0-update1-doc-c.zip + 
  j2sdk-1_3_0-update1-doc-d.zip + j2sdk-1_3_0-update1-doc-e.zip +
  j2sdk-1_3_0-update1-doc-f.zip + j2sdk-1_3_0-update1-doc-g.zip +
  j2sdk-1_3_0-update1-doc-h.zip + j2sdk-1_3_0-update1-doc-i.zip +
  j2sdk-1_3_0-update1-doc-j.zip + j2sdk-1_3_0-update1-doc-k.zip +
  j2sdk-1_3_0-update1-doc-l.zip + j2sdk-1_3_0-update1-doc-m.zip +
  j2sdk-1_3_0-update1-doc-n.zip + j2sdk-1_3_0-update1-doc-o.zip +
  j2sdk-1_3_0-update1-doc-p.zip j2sdk-1_3_0-update1-doc.zip 
  

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

  % cat j2sdk-1_3_0-update1-doc-a.zip j2sdk-1_3_0-update1-doc-b.zip \
  j2sdk-1_3_0-update1-doc-c.zip j2sdk-1_3_0-update1-doc-d.zip j2sdk-1_3_0-update1-doc-e.zip \
  j2sdk-1_3_0-update1-doc-f.zip j2sdk-1_3_0-update1-doc-g.zip j2sdk-1_3_0-update1-doc-h.zip \
  j2sdk-1_3_0-update1-doc-i.zip j2sdk-1_3_0-update1-doc-j.zip j2sdk-1_3_0-update1-doc-k.zip \
  j2sdk-1_3_0-update1-doc-l.zip j2sdk-1_3_0-update1-doc-m.zip j2sdk-1_3_0-update1-doc-n.zip \
  j2sdk-1_3_0-update1-doc-o.zip j2sdk-1_3_0-update1-doc-p.zip \
  > j2sdk-1_3_0-update1-doc.zip 
  

The resulting concatenated file should be the same size as the j2sdk-1_3_0-update1-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.3 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.