Java Doclet API change for jdk 8

Question

I am a newbie to Java. I was trying to upgrade to jdk 1.8 and found the following errors on doing a "gradle test":

/u01/sv/home/sv900t1/sv_test/Test_Suites/SeleniumLibraries/src/main/java/com/csgi/svtest/selenium/CustomWriter.java:57: error: cannot find symbol
        h2("Class "+classDoc.toString());
        ^
  symbol:   method h2(String)
  location: class CustomWriter
/u01/sv/home/sv900t1/sv_test/Test_Suites/SeleniumLibraries/src/main/java/com/csgi/svtest/selenium/CustomWriter.java:58: error: cannot find symbol
        printHyperLink(classDoc.toString()+".html","","Class description<br>",true);
        ^
  symbol:   method printHyperLink(String,String,String,boolean)
  location: class CustomWriter

I referred to http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/8-b132/com/sun/tools/doclets/formats/html/SubWriterHolderWriter.java/

and http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/7u40-b43/com/sun/tools/doclets/formats/html/SubWriterHolderWriter.java/

(our code imports this: import com.sun.tools.doclets.formats.html.SubWriterHolderWriter;)

and found that many apis like h2(), printHyperLink(), hr(), table(), tableHeaderStart(), tableHeaderEnd(), tableEnd(), pre(), strong(), preEnd(), ul(), print(), li(), ulEnd(), printHtmlHeader(), center(), today(), printTop(), navLinks(), printBottom() and printBodyHtmlEnd() have been removed.

Is there a quick workaround that can enable us to bypass the symbol errors? Or should we replace the missing apis with existing ones. This looks like a lot of work to me - being an entrant. Are there any existing examples on how to do that? I have searched the internet a lot, but could not find anything useful.

The code in CustomWriter.java is for outputting a Javadoc page using custom System Test tags. Any help is appreciated - we are short on time.

Answer 1

Well here's the problem. The classes in the com.sun.tools.* packages should be treated as internal APIs. There are clear warnings in the Java documentation that say that you should not write code that against these APIs.

For example:

• Why Developers Should Not Write Programs That Call 'sun' Packages
• Closing the closed APIs

In Java 8, the header of the class that your code is trying to use says:

This is NOT part of any supported API. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.

(The bolding is in the original!)

It didn't say that in Java 7 (ouch!) Indeed there are versions of the Javadoc FAQ which seem to encourage people reuse the standard doclet classes. Unfortunately, Oracle have decided to close off these classes, and have also made some breaking API changes which reinforces this, whether or not that was the intention of the changes

What can you do about it? Unfortunately, there is no easy solution:

• Maybe you could find an truly open source Doclet codebase that you could modify.

• Maybe you could find a commercial vendor or consultant who will do the work for you.

• Or maybe you just "suck it up" and rewrite your code to work with the latest version of the (internal) APIs. And live with the possibility that you may need to take more pain in the future.

• Or ... you could reinstall Java 7 on your build / test boxes and use it (just) for running your custom doclets.

---

UPDATE - It has been pointed out that the "rule" above is for sun.* packages. However:

• The document doesn't say anything about com.sun.* packages, so it is not valid to infer that they fall into the same category as java.*, javax.* and others that are explicitly stated to be reserved for Java supported APIs.

• There are other examples of com.sun.* packages that are explicitly stated to be NOT supported. For example, Oracle's "Compatibility Guide for Java 8" says things like this:

  The com.sun.media.sound package is an internal, unsupported package and is not meant to be used by external applications.

  The JDK internal package com.sun.corba.se and sub-packages have been added to the restricted package list and cannot be used directly when running with a security manager.

  The apt tool and its associated API contained in the package com.sun.mirror have been removed in this release.

Conclusion, even if there is no explicit statement that com.sun.* packages are internal, Oracle is >>now<< treating them as internal when it suits them. In some cases, retrospectively.