United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4697040 javadoc is reporting errors when classpath jar files have package.html files
JDK-4697040 : javadoc is reporting errors when classpath jar files have package.html files

Details
Type:
Bug
Submit Date:
2002-06-04
Status:
Resolved
Updated Date:
2003-04-25
Project Name:
JDK
Resolved Date:
2002-11-08
Component:
docs
OS:
linux
Sub-Component:
doclet
CPU:
x86
Priority:
P2
Resolution:
Fixed
Affected Versions:
1.4.0,1.4.1
Fixed Versions:
1.4.2 (mantis)

Related Reports
Duplicate:

Sub Tasks

Description

Name: gm110360			Date: 06/04/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)


FULL OPERATING SYSTEM VERSION :
generic

ADDITIONAL OPERATING SYSTEMS :

Linux draught.bbn.com 2.4.19-pre8 #1 SMP Tue May 21 14:23:08
EDT 2002 i686 unknown

A DESCRIPTION OF THE PROBLEM :

javadoc is reporting bogus errors when classpath-referenced jar files have package.html files.

I've used jar to package a single set of files as examples for all the associated bug reports.When running javadoc in a large autobuild process, I see a number of messages like:
  server.jar: Body tag missing from HTML
  1 error

On the assumption that there was something wrong with the
jar file, I tried:
  A. removing all html files from the jar file: there were
two "package.html" files.  The result is "bar.jar"
  B. leaving exactly one "package.html" file with only
simplified content in the jar file.  The result is "foo.jar"

  Interestingly, in case A (no package.html files), the error
disappears but in case B (a single package.html with
standard content), the error is back.  In case B, it doesn't
even matter what the content of the file is - the existence
of the complained about body tags doesn't effect the message
at all - I even tried the canonical package.html from the
javadoc documentation to no avail.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
[I attached javadocbug.jar to this bug report - dkramer]
The minimal examples may be found at:
http://www.alpine.bbn.com/~mthome/javadocbug.jar
grab the the above file and unpack it into a clean directory
of your choosing.  It contains some .java files and some
.jar files used in the various "steps to reproduce" sections.
% cd /tmp/foo
% jar xf /tmp/javadocbug.jar
% mkdir api
# test 1
% javadoc -classpath server.jar -quiet -d api -sourcepath src org.cougaar
Loading source files for package org.cougaar...
Constructing Javadoc information...
server.jar: Body tag missing from HTML
1 error

# test 4 case A (tests 2,3 is not relevant for this report)
% rm -rf api; mkdir api
% javadoc -classpath bar.jar -quiet -d api -sourcepath src org.cougaar
Loading source files for package org.cougaar...
Constructing Javadoc information...

# test 4 case B
% rm -rf api; mkdir api
% javadoc -classpath foo.jar -quiet -d api -sourcepath src org.cougaar
Loading source files for package org.cougaar...
Constructing Javadoc information...
foo.jar: Body tag missing from HTML
1 error
% 


EXPECTED VERSUS ACTUAL BEHAVIOR :
Actual:
see above

Expected:
test 4B should complete without error - there is nothing
wrong with the package.html file, even if were required by
this javadoc run (and it isn't).

ERROR MESSAGES/STACK TRACES THAT OCCUR :
server.jar: Body tag missing from HTML

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
not relevant.  The source code used in the example can be anything at all to
generate the same error.
---------- END SOURCE ----------
(Review ID: 146962) 
======================================================================

                                    

Comments
PUBLIC COMMENTS

The tool tries to read package.html from a JAR file without checking if it is really in there.  I added a check to avoid the null pointer that the user was seeing.  A regression test has been added with the test case given by the user.

###@###.### 2002-09-21
                                     
2002-09-21
WORK AROUND

This bug is in both 1.4.0 and 1.4.1.
If a jar file contains classes or packages that javadoc is documenting, 
avoid putting that jar file on the classpath.  

If you are forced to put that jar file on the classpath, then put a valid package.html file in the jar file at the package directory being documented.  
For example, if documenting com.package1, then make sure the jar file 
contains com/package1/package.html

###@###.### 2002-09-29
                                     
2002-09-29
EVALUATION

I reproduced this.  javadocbug.jar is attached to this bug report.
###@###.### 2002-09-16

I inquired from the submitter why he had a package.html file in his .jar
file that contains no .java files, and this was his reply:

> Actually, it arose because our build recipes install all source
> html files into our jars for use as resources by applets and such
> (online help).  We just happened to have one called package.html...
> In any case, we avoid putting the jar on the classpath during the
> javadoc anyway nowadays.

This bug has been fixed.  The tool now checks for a null ZipEntry before reading package.html.
###@###.### 2002-09-21

PIT reports that this bug has not been fixed on Windows2000.

-- iag@sfbay 2002-10-23

I deleted the shell script based regression test and rewrote the test in Java.  The test now runs properly on Windows.
###@###.### 2002-11-04
                                     
2002-10-23
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis
mantis-b05


                                     
2004-06-14



Hardware and Software, Engineered to Work Together