Do JDK classes have any additional specifications outside of Javadoc?

Question

Do JDK classes have any additional specifications outside of their Javadoc? If so, where?

For example, consider Collections.unmodifiableMap . His Javadoc says nothing about thread safety; therefore, simply by switching from Javadoc, I cannot assume that it is safe to bring the received map to other streams without taking some special steps to increase the safety of streams. But IMHO, any realistic implementation will save the internal map in the final field, therefore, in Java 5 and higher, the resulting map will be thread safe if the internal map (with the "happen earlier" relationship between any access to the received map and any previous changes to the internal map). This is what the OpenJDK implementation does, for example.

So, how can I understand if I can portablely accept the given behavior?

Answer 1

Javadoc is a specification. However, writing a good specification is extremely difficult, balancing both without leaving useful material, without exaggerating (and undermining the future ability to develop implementation.)

If I were to guess, I would say that the reason why this was excluded from the specification (except, perhaps, supervision) is that any thread safety would be conditional than the base collection (a) would not be published and (b) do not change after the creation of an unmodifiable representation, and this must also be carefully defined.

Answer 2

In the end, only the continuum from never changes, can change the behavior in the next version of the point, just to work on your platform. Even the specified behavior may be outdated and then deleted at some point, this is extremely rare (for example, Thread.destroy ). Therefore, whether you can rely on reasonable, but unspecified behavior, depends on how much you need a guarantee, how much effort you want to spend on coding around things in protecting / adding tests to ensure that future changes are detected, etc.

But yes, javadocs are the strongest guarantee you can get, everything else means moving to thinner ice.

Many projects rely on APIs that are not only undocumented, but are considered internal and supposedly implementation-specific. sun.misc.Unsafe is the prime example here, right up to the point where most of its features have been reinforced as proper JDK APIs in 9.

In the case of Collections.unmodifiableMap , if you want to really protect a secure publication, you can insert a store fence after it is created.