Is the JDK documentation part of the language specification?

Question

There is only one official Java Language Specification and all Java implementations must comply with it.

How about the API documentation: do all Java implementations need to comply with this version or could an implementation define the behaviour of some methods and classes differently, as long as it's compatible with the JLS?

Let's throw a concrete example: could a Java implementation include a HashMap that doesn't accept null elements?

Answer 1

I believe, that, yes it is.

Upon closer examination, I think it is not.

As JLS 8 states in p.1.4:

1.4. Relationship to Predefined Classes and Interfaces

As noted above, this specification often refers to classes of the Java SE platform API. In particular, some classes have a special relationship with the Java programming language. Examples include classes such as Object, Class, ClassLoader, String, Thread, and the classes and interfaces in package java.lang.reflect, among others. This specification constrains the behavior of such classes and interfaces, but does not provide a complete specification for them. The reader is referred to the Java SE platform API documentation.

From one hand they state, that JLS document does not provide a complete specification and send reader to the Java SE platform API documentation.

From other hand, there are various places in the JLS when some APIs (plural form) of Java SE are mentioned. Furthermore, it seems that JLS does not contain links to the particular Java SE API specification:

3.1. Unicode

Some APIs of the Java SE platform, primarily in the Character class, use 32-bit integers to represent code points as individual entities. The Java SE platform provides methods to convert between 16-bit and 32-bit representations.

3.10.4. Character Literals

Character literals can only represent UTF-16 code units (§3.1), i.e., they are limited to values from \u0000 to \uffff. Supplementary characters must be represented either as a surrogate pair within a char sequence, or as an integer, depending on the API they are used with.

9.6.4. Predefined Annotation Types

Several annotation types are predefined in the libraries of the Java SE platform. Some of these predefined annotation types have special semantics. These semantics are specified in this section. This section does not provide a complete specification for the predefined annotations contained here in; that is the role of the appropriate API specifications. Only those semantics that require special behavior on the part of a Java compiler or Java Virtual Machine implementation are specified here.