Why does the Double.valueof javadoc say it caches values, when it doesn't?

Question

In OpenJDK, for the method:

public static Double valueOf(double d)

The javadoc says:

Returns a Double instance repre

Answer 1

Remember that the JVM was created to reduce code size for embedded devices (mostly)--it's a set-top box operating system. I've worked on a few embedded java platforms and on those the "value of" valueOf would be more obvious, it would save quite a bit of space in some cases.

Mostly the method exists because "new" cannot ever use cached instances. valueOf MAY be implemented to use cached instances (otherwise you would just always use new) and likely does wherever it proves to save time.

If they (or you) replaced that method with one that actually did cache values then all your code would gain the advantage of that change, but without preparing by providing a method like "valueOf" it could never happen (well, practically never--you could tweak the compiler/bytecode executor to have "new" return cached values but I think that would break some contracts)

So the cache isn't really a lie, just a state of mind.