Whilst using an installation of Eclipse 3.7.2, I found that it silently fails to show the Javadoc provided by my ObMimic library.
The Eclipse project was pointing at the right location for this Javadoc, but flatly refused to show any of it in pop-ups or the Javadoc view.
A look at the Eclipse logs showed a pile of “StringIndexOutOfBoundsException” crashes from Eclipse’s attempt to parse the individual Javadoc files. This turns out to be a known Eclipse bug, 394382, which is marked as fixed in Eclipse 4.3 M4 onwards.
The problem arises from a change in the “Content-Type” header within Javadoc files produced by JDK 7. Prior to JDK 7, these specified the “charset” as part of the content-type string, but from JDK 7 onwards the “charset” is given by a separate attribute.
That is:
- JDK 6: <meta http-equiv=”Content-Type” content=”text/html; charset=UTF-8″>
- JDK 7: <meta http-equiv=”Content-Type” content=”text/html” charset=”UTF-8″>
The Eclipse code that fails is trying to extract the charset’s value from this line (i.e. the “UTF-8”), but it crashes when given the newer form of the header.
Obviously one solution would be to insist on Eclipse 4.3 M4 or higher, but ideally I’d like my ObMimic Javadoc to be usable on any reasonable version of Eclipse that any user might have. For the time being that ought to include 3.7.x versions. Most of all I don’t want people complaining about my Javadoc not working when it’s actually an Eclipse bug!
So as a work-around for this I’ve added a step into ObMimic’s build script to change this particular header back to its old format. As far as I know both formats of the header are valid, and there doesn’t seem to be any pressing need to use the newer format, so it seems harmless to use the older format for this header.
To achieve this, as soon as the relevant Ant script has generated the Javadoc it now uses the following “replace” task to change the relevant lines within all of the Javadoc’s HTML pages (where ${obmimic.javadoc.dir} is the root directory into which the Javadoc was generated):
<replace dir="${obmimic.javadoc.dir}" summary="true">
<include name="**/*.html"/>
<replacetoken><![CDATA[<meta http-equiv="Content-Type" content="text/html" charset="UTF-8">]]></replacetoken>
<replacevalue><![CDATA[<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">]]></replacevalue>
</replace>
Note that the above is based on the Javadoc charset being UTF-8 (from the Ant Javadoc task specifying “docencoding” and “charset” attributes of “UTF-8”), and would obviously need adjusting for any different charset or if making it variable. Also, the “summary” attribute produces a message showing how many replacements were carried out, to at least confirm that the replacments have taken place (without this, the replacement is done silently).
Recent Comments