/*
 * 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_COLLECTION_H_
#define _DECAF_UTIL_COLLECTION_H_

#include <decaf/util/Config.h>
#include <decaf/lang/exceptions/UnsupportedOperationException.h>
#include <decaf/lang/exceptions/NullPointerException.h>
#include <decaf/lang/exceptions/IllegalArgumentException.h>
#include <decaf/lang/Iterable.h>
#include <decaf/util/Iterator.h>
#include <decaf/util/concurrent/Synchronizable.h>

namespace decaf {
namespace util {

    /**
     * The root interface in the collection hierarchy. A collection represents
     * a group of objects, known as its elements. Some collections allow
     * duplicate elements and others do not. Some are ordered and others
     * unordered. This interface is typically used to pass collections
     * around and manipulate them where maximum generality is desired.
     *
     * All general-purpose Collection implementation classes (which typically
     * implement Collection indirectly through one of its subinterfaces) should
     * provide two "standard" constructors: a void (no arguments) constructor,
     * which creates an empty collection, and a constructor with a single argument
     * of type Collection, which creates a new collection with the same elements
     * as its argument. In effect, the latter constructor allows the user to copy
     * any collection, producing an equivalent collection of the desired
     * implementation type. There is no way to enforce this convention
     * (as interfaces cannot contain constructors) but all of the general-purpose
     * Collection implementations in the Decaf platform libraries comply.
     *
     * The "destructive" methods contained in this interface, that is, the methods
     * that modify the collection on which they operate, are specified to throw
     * UnsupportedOperationException if this collection 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 collection. For example, invoking the addAll(Collection)
     * method on an unmodifiable collection may, but is not required to, throw
     * the exception if the collection to be added is empty.
     *
     * Many methods in Collections Framework interfaces are defined in terms of
     * the equals method. For example, the specification for the
     * contains(Object o) method says: "returns true if and only if this
     * collection contains at least one element e such that
     * (o==null ? e==null : o.equals(e))."
     *
     * @since 1.0
     */
    template< typename E >
    class Collection : public virtual lang::Iterable<E>,
                       public virtual util::concurrent::Synchronizable {
    public:

        virtual ~Collection() {}

        /**
         * Renders this Collection as a Copy of the given Collection
         *
         * @param collection
         *      The collection to mirror.
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         * @throws IllegalStateException if the elements cannot be added at this time due
         *         to insertion restrictions.
         */
        virtual void copy(const Collection<E>& collection) = 0;

        /**
         * Returns true if this collection changed as a result of the call.
         * (Returns false if this collection does not permit duplicates and
         * already contains the specified element.)
         *
         * Collections that support this operation may place limitations on
         * what elements may be added to this collection. In particular,
         * some collections will refuse to add null elements, and others
         * will impose restrictions on the type of elements that may be
         * added. Collection classes should clearly specify in their
         * documentation any restrictions on what elements may be added.
         *
         * If a collection refuses to add a particular element for any
         * reason other than that it already contains the element, it must
         * throw an exception (rather than returning false). This preserves
         * the invariant that a collection always contains the specified
         * element after this call returns.
         *
         * For non-pointer values, i.e. class instances or string's the object
         * will be copied into the collection, thus the object must support
         * being copied, must not hide the copy constructor and assignment
         * operator.
         *
         * @param value
         *      The reference to the element to add to this Collection.
         *
         * @return true if the element was added to this Collection.
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         * @throws NullPointerException if the Collection is a container of pointers
         *         and does not allow NULL values.
         * @throws IllegalArgumentException if some property of the element prevents it
         *         from being added to this collection
         * @throws IllegalStateException if the element cannot be added at this time due
         *         to insertion restrictions.
         */
        virtual bool add(const E& value) = 0;

        /**
         * Adds all of the elements in the specified collection to this
         * collection. The behavior of this operation is undefined if the
         * specified collection is modified while the operation is in progress.
         * (This implies that the behavior of this call is undefined if the
         * specified collection is this collection, and this collection is
         * nonempty.)
         *
         * @param collection
         *      The Collection whose elements are added to this one.
         *
         * @return true if this collection changed as a result of the call
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         * @throws NullPointerException if the Collection is a container of pointers
         *         and does not allow NULL values.
         * @throws IllegalArgumentException if some property of an element prevents it
         *         from being added to this collection
         * @throws IllegalStateException if an element cannot be added at this time due
         *         to insertion restrictions.
         */
        virtual bool addAll(const Collection<E>& collection) = 0;

        /**
         * Removes all of the elements from this collection (optional operation).
         * This collection will be empty after this method returns unless it throws
         * an exception.
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         */
        virtual void clear() = 0;

        /**
         * Returns true if this collection contains the specified element. More
         * formally, returns true if and only if this collection contains at
         * least one element e such that (value == NULL ? e == NULL : value == e ).
         *
         * @param value
         *      The value to check for presence in the collection.
         *
         * @return true if there is at least one of the elements in the collection
         *
         * @throws NullPointerException if the Collection contains pointers and the
         *         Collection does not allow for NULL elements (optional check).
         */
        virtual bool contains(const E& value) const = 0;

        /**
         * Returns true if this collection contains all of the elements in
         * the specified collection.
         *
         * @param collection
         *      The Collection to compare to this one.
         *
         * @throws NullPointerException if the Collection contains pointers and the
         *         Collection does not allow for NULL elements (optional check).
         */
        virtual bool containsAll(const Collection<E>& collection) const = 0;

        /**
         * Compares the passed collection to this one, if they contain the
         * same elements, i.e. all their elements are equivalent, then it
         * returns true.
         *
         * @return true if the Collections contain the same elements.
         */
        virtual bool equals(const Collection<E>& value) const = 0;

        /**
         * @return true if this collection contains no elements.
         */
        virtual bool isEmpty() const = 0;

        /**
         * Removes a single instance of the specified element from the
         * collection.  More formally, removes an element e such that
         * (value == NULL ? e == NULL : value == e), if this collection contains one
         * or more such elements. Returns true if this collection contained
         * the specified element (or equivalently, if this collection changed
         * as a result of the call).
         *
         * @param value
         *      The reference to the element to remove from this Collection.
         *
         * @return true if the collection was changed, false otherwise.
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         * @throws NullPointerException if the Collection is a container of pointers
         *         and does not allow NULL values.
         */
        virtual bool remove(const E& value) = 0;

        /**
         * Removes all this collection's elements that are also contained in
         * the specified collection (optional operation). After this call returns,
         * this collection will contain no elements in common with the specified
         * collection.
         *
         * @param collection
         *      The Collection whose elements are to be removed from this one.
         *
         * @return true if the collection changed as a result of this call.
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         * @throws NullPointerException if the Collection is a container of pointers
         *         and does not allow NULL values.
         */
        virtual bool removeAll(const Collection<E>& collection) = 0;

        /**
         * Retains only the elements in this collection that are contained in the
         * specified collection (optional operation). In other words, removes from
         * this collection all of its elements that are not contained in the
         * specified collection.
         *
         * @param collection
         *      The Collection whose elements are to be retained.
         *
         * @return true if the collection changed as a result of this call.
         *
         * @throws UnsupportedOperationExceptio if this is an unmodifiable collection.
         * @throws NullPointerException if the Collection is a container of pointers
         *         and does not allow NULL values.
         */
        virtual bool retainAll(const Collection<E>& collection) = 0;

        /**
         * Returns the number of elements in this collection. If this collection
         * contains more than Integer::MAX_VALUE elements, returns Integer::MAX_VALUE.
         *
         * @return the number of elements in this collection
         */
        virtual int size() const = 0;

        /**
         * Returns an array containing all of the elements in this collection. If
         * the collection makes any guarantees as to what order its elements are
         * returned by its iterator, this method must return the elements in the
         * same order.
         *
         * This method acts as bridge between array-based and collection-based APIs.
         *
         * @return an array of the elements in this collection in the form of an
         *          STL vector.
         */
        virtual std::vector<E> toArray() const = 0;

    };

}}

#endif /*_DECAF_UTIL_COLLECTION_H_*/