License and Usage Terms of generated API documentation

Volker Simonis volker.simonis at
Thu May 3 12:16:11 UTC 2018

On Thu, May 3, 2018 at 12:21 PM, Magnus Ihse Bursie
<magnus.ihse.bursie at> wrote:
> On 2018-05-02 17:03, Volker Simonis wrote:
>> Hi,
>> we currently build OpenJDK and make it available from various sources
>> (e.g. GitHub, apt-get server, DockerHub). We also build the API
>> documentation (i.e. JavaDoc) and would like to make it available from
>> our project page as well. However the default API doc produced by the
>> build looks as follows:
>> Especially the footer seems to be weired and only valid for the API
>> doc hosted by Oracle itself. It reads as follows:
>> Use is subject to "license terms" and the "documentation redistribution
>> policy".
>> "license terms" links to
>> which redirects to
>> "documentation redistribution policy" links to
>> Especially the "documentation redistribution policy" is very strict. It
>> states:
>> "The Java SE API Specification is not redistributable."
>> This is a very strong statement. While it may be fine for the API
>> documentation hosted by Oracle (under
>> I
>> doubt this can be valid for the OpenJDK API documentation which was
>> produced exclusively from GPLv2 licensed sources (actually even GPLv2
>> plus Classpath Exception). From my understanding the whole HTML tree
>> generated by "make docs-image" should be by default licensed under
>> GPLv2 as well.
>> I would therefore like to propose to make the following variables from
>> "make/Docs.gmk" configurable with corresponding configure flags:
>> COPYRIGHT_URL := {@docroot}/../legal/copyright.html
>> "JAVADOC_BASE_URL" should by default point to an OpenJDK site
>> (although I'm not sure which one will be best suited). It seems
>> strange that the default documentation generated from an OpenSource
>> project like OpenJDK points to some Oracle-proprietary documentation.
>> "BUG_SUBMIT_URL" should use the value of the already existing
>> "--with-vendor-bug-url" if that was set at configure time.
>> "COPYRIGHT_URL" currently points to "copyright.html" which doesn't
>> exist neither in the OpenJDK sources nor in the generated images. Not
>> sure what would be a useful default value here. Maybe just leave it
>> empty? "Copyright © 1993, 2018, Oracle.." already seems
>> self-explanatory and clear enough.
>> "LICENSE_URL" and "REDISTRIBUTION_URL" should both by default point to
>> the GPLv2+CPE LICENSE file and this LICENSE file should be copied into
>> the API doc HTML tree (much like it is copied into the various
>> subdirectories of the "legel/" directory of an OpenJDK image)
>> I can open an issue for this topic and propose an implementation if
>> there's consensus on this topic.
>> Thank you and best regards,
>> Volker
> Since you added build-dev, I'll chip in some of my cents.
> The code in the make file has been around like Forever<tm>. The current
> implementation is just what has been ported between frameworks and source
> control systems and updated for changes in release version and URL schemes.

Thanks for confirming this. That was my impression as well :)

> I agree that is odd that the Oracle URL is hard-coded. On the other hand,
> there is no common place where generated OpenJDK documents are published.
> (The Oracle site technically speaking documents the Java Platform API, not
> the OpenJDK, even if any actual difference is minimal to non-existant wrt
> docs.)
> It would make sense to me to have a OpenJDK-based documentation driven by
> the community. I'm guessing it's no easy thing to create this, though. A lot
> of links on the interwebz are pointing to the docs at, and
> it would probably be quite messy if the same (or even worse, almost the
> same) documentation were published both at and
> Also, the question arises as to who should do the hosting, and how.
> So it's definitely a community issue to resolve, and one in which Oracle's
> legacy is important to take into consideration.
> Until a consensus of a better solution for hosting the generated
> documentation is reached, I'd like to avoid changing the build code. That
> will just open for an uneccessary split in what constitutes the proper
> documentation URL.

The JAVADOC_BASE_URL is the minor issue here and I agree that it would
be not easy to create a community driven documentation of the same or
at least similar quality as we have today from Oracle. Nevertheless I
don't see why we shouldn't be able to make this URL configurable at
configure time.

The main issue are the two links to "LICENSE_URL" and
"REDISTRIBUTION_URL" which clearly refer to the API-docs published by
Oracle. I just want to be able to publish these API-docs myself
without having to refer to these restrictive licenses. The change
itself, to make these URLs configurable at configure time, would be
trivial (and again, I'm not against leaving the default "as-is" if
this is important for you).

> /Magnus

More information about the jdk-dev mailing list