Date: Thu, 03 Feb 2005 16:36:32 +0100
From: ###@###.###
Subject: Minor Bug in Doclet API implementation
To: ###@###.###

Hi Javadoc Team,

while working on a custom doclet the following bug was found:
Javadoc attempts to read and parse package.html files which are contained in
JAR files of libraries specified in Javadoc's -classpath option when the
PackageDoc instance corresponding to these packages is accessed.
Unfortunatly, Javadoc fails to read the complete package.html and then aborts
with an error:

Loading source file src/test/TestJLC.java...
Constructing Javadoc information...
TestDoclet
Found package org.apache.commons.logging ...
Trying to access @author tags ...
commons-logging-1.0.4/commons-logging.jar/org/apache/commons/logging/package.
html: error - Close body tag missing from HTML file
1 error

Platforms:
Java 1.3.1_12, 1.4.2_06, 1.5.0

OS:
Linux (Fedora Core 2), kernel 2.6.6-1.435.1.3 on AMD Athlon XP 2000+, 1GB RAM
Linux (SuSE 9.0), kernel 2.4.21-266-default on Intel P3 700, 256MB RAM

CLASSPATH:
No global CLASSPATH system variable.

To reproduce this problem, just unzip the attached file, cd into the created
bug directory and run "ant complete".


The culprit is (according to the SCSL release):
class com.sun.tools.javadoc.DocImpl
method readHTMLDocumentation(InputStream input, String filename)
line 129

This method attempts to read the content of the specified stream using the
following code:
        ...
        int filesize = input.available();
        byte[] filecontents = new byte[filesize];
        input.read(filecontents, 0, filesize);
        input.close();
        ...
This is bad, since the read method is not guaranteed to actually read all the
available bytes (moreover the available method is not guaranteed to actually
return the size of the stream).
An iterative approach has to be used - maybe something along the lines of:
        ...
        filecontents = read(input);
        input.close();
        ...

private byte[] read(final InputStream is) throws IOException
{
  final byte[] buffer = new byte[1024*1024];
  final ByteArrayOutputStream baos = new ByteArrayOutputStream();
  while (true)
  {
    final int amountRead = is.read(buffer);
    if (amountRead == -1)
    {
      break;
    }
    baos.write(buffer, 0, amountRead);
  }
  return baos.toByteArray();
}

References:
- Java Platform Performance: Strategies and Tactics
  Part II Tactics, Chapter 4 I/O Performance
  http://java.sun.com/docs/books/performance/1st_edition/html/JPIOPerformance.fm.html#11352
- InputStream API Docs
  http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html
  http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html#read(byte[],
%20int,%20int)
  http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html#read(byte[])
  http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html#available()


Kind regards,
Thomas Behr

###@###.### 2005-2-09 21:35:16 GMT