The documentation of putIfAbsent says it will return the "previous" value associated with the given key. However, the value will not get replaced if the key existed, so technically it is not the "previous" value, but the current value associated with the key.

putIfAbsent("existing-key", "value") -> always returns current value

putIfAbsent("new-key", "value") -> always returns null

The main documentation part does make it clear:

     * If the specified key is not already associated with a value (or is mapped
     * to {@code null}) associates it with the given value and returns
     * {@code null}, else returns the current value.

It specifically mentions that it will return the "current" value

At a minimum this is confusing (which is why I wrote this ticket), but I think its conflicting information.