activemq-cpp/src/main/decaf/util/Map.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _DECAF_UTIL_MAP_H_
#define _DECAF_UTIL_MAP_H_

#include <functional>
#include <vector>
#include <decaf/lang/exceptions/UnsupportedOperationException.h>
#include <decaf/util/NoSuchElementException.h>
#include <decaf/util/concurrent/Synchronizable.h>
#include <decaf/util/Set.h>
#include <decaf/util/Collection.h>
#include <decaf/util/MapEntry.h>

namespace decaf{
namespace util{

    /**
     * An object that maps keys to values. A map cannot contain duplicate keys; each key can map
     * to at most one value.
     *
     * The Map interface provides three collection views, which allow a map's contents to be viewed
     * as a set of keys, collection of values, or set of key-value mappings. The order of a map is
     * defined as the order in which the iterators on the map's collection views return their
     * elements. Some map implementations, like the TreeMap class, make specific guarantees as to
     * their order; others, like the HashMap class, do not.
     *
     * Note: great care must be exercised if mutable objects are used as map keys. The behavior
     * of a map is not specified if the value of an object is changed in a manner that affects
     * equals comparisons while the object is a key in the map. A special case of this prohibition
     * is that it is not permissible for a map to contain itself as a key. While it is permissible
     * for a map to contain itself as a value, extreme caution is advised: the equals and hashCode
     * methods are no longer well defined on such a map.
     *
     * All general-purpose map implementation classes should provide two "standard" constructors:
     * a void (no arguments) constructor which creates an empty map, and a constructor with a
     * single argument of type Map, which creates a new map with the same key-value mappings as
     * its argument. In effect, the latter constructor allows the user to copy any map, producing
     * an equivalent map of the desired class.
     *
     * The "destructive" methods contained in this interface, that is, the methods that modify the
     * map on which they operate, are specified to throw UnsupportedOperationException if this map
     * does not support the operation. If this is the case, these methods may, but are not required
     * to, throw an UnsupportedOperationException if the invocation would have no effect on the map.
     * For example, invoking the putAll(Map) method on an unmodifiable map may, but is not required
     * to, throw the exception if the map whose mappings are to be "superimposed" is empty.
     *
     * Some map implementations have restrictions on the keys and values they may contain. For
     * example, some implementations prohibit NULL keys and values, and some have restrictions on
     * the types of their keys. Attempting to insert an ineligible key or value throws an exception,
     * typically NullPointerException or ClassCastException. Attempting to query the presence of an
     * ineligible key or value may throw an exception, or it may simply return false; some
     * implementations will exhibit the former behavior and some will exhibit the latter. More
     * generally, attempting an operation on an ineligible key or value whose completion would not
     * result in the insertion of an ineligible element into the map may throw an exception or it
     * may succeed, at the option of the implementation. Such exceptions are marked as "optional"
     * in the specification for this interface.
     *
     * Many methods in Collections Framework interfaces are defined in terms of the equals method.
     * For example, the specification for the containsKey(Object key) method says: "returns true if
     * and only if this map contains a mapping for a key k such that (key == k)." This specification
     * should not be construed to imply that invoking Map.containsKey with a non-null argument key
     * will cause (key == k) to be invoked for any key k. Implementations are free to implement
     * optimizations whereby the equals invocation is avoided, for example, by first comparing the
     * hash codes of the two keys. (The Object.hashCode() specification guarantees that two objects
     * with unequal hash codes cannot be equal.) More generally, implementations of the various
     * Collections Framework interfaces are free to take advantage of the specified behavior of
     * underlying Object methods wherever the implementor deems it appropriate.
     *
     * @since 1.0
     */
    template <typename K, typename V>
    class Map : public concurrent::Synchronizable {
    public:

        /**
         * Default constructor - does nothing.
         */
        Map() : concurrent::Synchronizable() {}

        virtual ~Map() {}

        /**
         * Compares the specified object with this map for equality. Returns true if the two
         * maps represent the same mappings. More formally, two maps m1 and m2 represent the
         * same mappings if m1.entrySet().equals(m2.entrySet()). This ensures that the equals
         * method works properly across different implementations of the Map interface.
         *
         * @param source
         *      Map to compare to this one.
         *
         * @return true if the Map passed is equal in value to this one.
         */
        virtual bool equals(const Map& source) const = 0;

        /**
         * Copies the content of the source map into this map.  Erases all existing mappings
         * in this map.  The copy is performed by using the entrySet of the source Map and
         * iterating over those entries, inserting each into the target.
         *
         * @param source
         *      The source object to copy from.
         */
        virtual void copy(const Map& source) = 0;

        /**
         * Removes all of the mappings from this map (optional operation). The map will
         * be empty after this call returns.
         *
         * @throw UnsupportedOperationException if the clear operation is not supported by this map.
         */
        virtual void clear() = 0;

        /**
         * Returns true if this map contains a mapping for the specified key. More formally,
         * returns true if and only if this map contains a mapping for a key k such that
         * (key == k). (There can be at most one such mapping.)
         *
         * @param key
         *      The key to look up.
         *
         * @return true if this map contains the key mapping, otherwise false.
         */
        virtual bool containsKey(const K& key) const = 0;

        /**
         * Returns true if this map maps one or more keys to the specified value. More
         * formally, returns true if and only if this map contains at least one mapping to
         * a value v such that (value==v). This operation will probably require time linear
         * in the map size for most implementations of the Map interface.
         *
         * @param value
         *      The Value to look up in this Map.
         *
         * @return true if this map contains at least one mapping for the value, otherwise false.
         */
        virtual bool containsValue(const V& value) const = 0;

        /**
         * @return if the Map contains any element or not, TRUE or FALSE
         */
        virtual bool isEmpty() const = 0;

        /**
         * @return The number of elements (key/value pairs) in this map.
         */
        virtual int size() const = 0;

        /**
         * Gets the value mapped to the specified key in the Map.  If there is no
         * element in the map whose key is equivalent to the key provided then a
         * NoSuchElementException is thrown.
         *
         * @param key
         *      The search key whose value should be returned if present.
         *
         * @return A reference to the value for the given key if present in the Map.
         *
         * @throws NoSuchElementException if the key requests doesn't exist in the Map.
         */
        virtual V& get(const K& key) = 0;

        /**
         * Gets the value mapped to the specified key in the Map.  If there is no
         * element in the map whose key is equivalent to the key provided then a
         * NoSuchElementException is thrown.
         *
         * @param key
         *      The search key whose value should be returned if present.
         *
         * @return A const reference to the value for the given key if present in the Map.
         *
         * @throws NoSuchElementException if the key requests doesn't exist in the Map.
         */
        virtual const V& get(const K& key) const = 0;

        /**
         * Associates the specified value with the specified key in this map (optional
         * operation). If the map previously contained a mapping for the key, the old value
         * is replaced by the specified value. (A map m is said to contain a mapping for a
         * key k if and only if m.containsKey(k) would return true.)
         *
         * @param key
         *      The target key.
         * @param value
         *      The value to be set.
         *
         * @return true if the put operation replaced a value that was associated with
         *          an existing mapping to the given key or false otherwise.
         *
         * @throws UnsupportedOperationException if this map is unmodifiable.
         * @throws IllegalArgumentException if some property of the specified key or value
         *                                  prevents it from being stored in this map
         */
        virtual bool put(const K& key, const V& value) = 0;

        /**
         * Associates the specified value with the specified key in this map (optional
         * operation). If the map previously contained a mapping for the key, the old value
         * is replaced by the specified value. (A map m is said to contain a mapping for a
         * key k if and only if m.containsKey(k) would return true.)
         *
         * This method accepts a reference to a value which will be assigned the previous
         * value for the given key (if any).  If there was no previous mapping for the
         * given key the out value is not written to.  A return of true indicates that a
         * value was replaced by this put operation.
         *
         * @param key
         *      The target key.
         * @param value
         *      The value to be set.
         * @param oldValue (out)
         *      The value previously held in the mapping for this key.  .
         *
         * @return true if the put operation replaced a value that was associated with
         *          an existing mapping to the given key or false otherwise.
         *
         * @throws UnsupportedOperationException if this map is unmodifiable.
         * @throws IllegalArgumentException if some property of the specified key or value
         *                                  prevents it from being stored in this map
         */
        virtual bool put(const K& key, const V& value, V& oldValue) = 0;

        /**
         * Copies all of the mappings from the specified map to this map (optional operation).
         * The effect of this call is equivalent to that of calling put(k, v) on this map once
         * for each mapping from key k to value v in the specified map. The behavior of this
         * operation is undefined if the specified map is modified while the operation is in
         * progress.
         *
         * @param other
         *      A Map instance whose elements are to all be inserted in this Map.
         *
         * @throws UnsupportedOperationException
         *      If the implementing class does not support the putAll operation.
         */
        virtual void putAll(const Map<K, V>& other) = 0;

        /**
         * Removes the value (key/value pair) for the specified key from the map, returns
         * a copy of the value that was mapped to the key.  Care must be taken when using this
         * operation as it will throw an exception if there is no mapping for the given key.
         *
         * @param key
         *      The search key whose mapping is to be removed.
         *
         * @return a copy of the element that was previously mapped to the given key.
         *
         * @throw NoSuchElementException if this key is not in the Map.
         * @throw UnsupportedOperationException if this map is unmodifiable.
         */
        virtual V remove(const K& key) = 0;

        /**
         * Returns a Set view of the mappings contained in this map. The set is backed by the
         * map, so changes to the map are reflected in the set, and vice-versa. If the map is
         * modified while an iteration over the set is in progress (except through the iterator's
         * own remove operation, or through the setValue operation on a map entry returned by
         * the iterator) the results of the iteration are undefined. The set supports element
         * removal, which removes the corresponding mapping from the map, via the
         * Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not
         * support the add or addAll operations.
         *
         * @return a reference  to a Set<MapEntry<K,V>> that is backed by this Map.
         */
        virtual Set< MapEntry<K,V> >& entrySet() = 0;
        virtual const Set< MapEntry<K,V> >& entrySet() const = 0;

        /**
         * Returns a Set view of the keys contained in this map. The set is backed by the map,
         * so changes to the map are reflected in the set, and vice-versa. If the map is modified
         * while an iteration over the set is in progress (except through the iterator's own
         * remove operation), the results of the iteration are undefined. The set supports element
         * removal, which removes the corresponding mapping from the map, via the Iterator.remove,
         * Set.remove, removeAll, retainAll, and clear operations. It does not support the add or
         * addAll operations.
         *
         * @return a set view of the keys contained in this map,
         */
        virtual Set<K>& keySet() = 0;
        virtual const Set<K>& keySet() const = 0;

        /**
         * Returns a Collection view of the values contained in this map. The collection is backed
         * by the map, so changes to the map are reflected in the collection, and vice-versa. If
         * the map is modified while an iteration over the collection is in progress (except
         * through the iterator's own remove operation), the results of the iteration are
         * undefined. The collection supports element removal, which removes the corresponding
         * mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll
         * and clear operations. It does not support the add or addAll operations.  For the const
         * version of this method the Collection can only be used as a view into the Map.
         *
         * @return a collection view of the values contained in this map.
         */
        virtual Collection<V>& values() = 0;
        virtual const Collection<V>& values() const = 0;

    };

}}

#endif /*_DECAF_UTIL_MAP_H_*/