Confusing about MultiValueMap

[Samuel Guo <gu...@gmail.com>]

Hi all,

I feel confused about the *put* method of MultiValueMap during using it.

as the javadoc mentioned, the return value of the *put* method will be the
value added if the map changed, or null if the map did not change.
Does "the map changed" here means that the *put* action to the multimap has
been done successfully? If so, when I put a new key/value pair to the
MultiValueMap, I should got the reference of the *value*. But I got *null*
:-(

so I decided to see the source of the common-collection. I found the source
below:

    /**
     * Adds the value to the collection associated with the specified key.
     * <p>
     * Unlike a normal <code>Map</code> the previous value is not replaced.
     * Instead the new value is added to the collection stored against the
key.
     *
     * @param key  the key to store against
     * @param value  the value to add to the collection at the key
     * @return the value added if the map changed and null if the map did
not change
     */
    public Object put(Object key, Object value) {
        boolean result = false;
        Collection coll = getCollection(key);
        if (coll == null) {
            coll = createCollection(1);
            result = coll.add(value);
            if (coll.size() > 0) {
                // only add if non-zero size to maintain class state
                getMap().put(key, coll);
                result = false;
                ~~~~~~~~~~ why the code set the result flag to false?
            }
        } else {
            result = coll.add(value);
        }
        return (result ? value : null);
    }

BTW, I found a JIRA about this problem, but it has been fixed and I can't
find any patch? And My common-collection's version is 3.2.1.

Hope for reply :-)

regards,

samuel