/*
 * 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 <devaf/lang/exceptions/UnsupportedOperationException.h>
#include <devaf/lang/exceptions/NullPointerException.h>
#include <devaf/lang/exceptions/IllegalArgumentException.h>
#include <decaf/util/Iterator.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 T >
    class DECAF_API Collection
    {
    public:

        virtual ~Collection() {}

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

        /**
         * @returns true if this collection contains no elements.
         */
        virtual bool isEmpty() = 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 (o==null ? e==null : o.equals(e)).
         * @param value - value to check for presence in the collection
         * @returns true if there is at least one of the elements in the collection
         * @thorws NullPointerException
         */
        virtual bool contains( const E& value )
            throw ( lang::exceptions::NullPointerException ) = 0;

        /**
         * Returns an iterator over the elements in this collection. There are
         * no guarantees concerning the order in which the elements are
         * returned (unless this collection is an instance of some class that
         * provides a guarantee).
         * @returns an Iterator over the elements in this collection
         */
        virtual Iterator<E>* iterator() = 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.
         * @returns an array of the elements in this collection.
         */
        virtual std::vector<E> toArray() = 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 - reference to the element to add.
         * @returns true if the element was added
         * @throw UnsupportedOperationException
         * @throw NullPointerException
         * @throw IllegalArgumentException
         */
        virtual bool add( const E& value )
            throw ( lang::exceptions::UnsupportedOperationException,
                    lang::exceptions::NullPointerException,
                    lang::exceptions::IllegalArgumentException ) = 0;

        /**
         * Removes a single instance of the specified element from the
         * collection.  More formally, removes an element e such that
         * (o==null ? e==null : o.equals(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 - reference to the element to remove.
         * @returns true if the collection was changed
         * @throw UnsupportedOperationException
         * @throw NullPointerException
         */
        virtual bool remove( const E& value )
            throw ( lang::exceptions::UnsupportedOperationException,
                    lang::exceptions::NullPointerException ) = 0;

        /**
         * Returns true if this collection contains all of the elements in
         * the specified collection.
         * @param source - Collection to compare to this one.
         * @thorw Exception
         */
        virtual bool containsAll( const Collection<E>& source )
            throw ( lang::Exception ) = 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 source - Collection whose elements are added to this one.
         * @return true if this collection changed as a result of the call
         * @throw UnsupportedOperationException
         * @throw NullPointerException
         * @throw IllegalArgumentException
         */
        virtual bool addAll( const Collection<E>& source )
            throw ( lang::exceptions::UnsupportedOperationException,
                    lang::exceptions::NullPointerException,
                    lang::exceptions::IllegalArgumentException ) = 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 value - The Collection whose elements are to be removed
         * @returns true if the collection changed as a result of this call
         * @throw UnsupportedOperationException
         * @throw NullPointerException
         * @throw IllegalArgumentException
         */
        virtual bool removeAll( const Collection<E>& value )
            throw ( lang::exceptions::UnsupportedOperationException,
                    lang::exceptions::NullPointerException,
                    lang::exceptions::IllegalArgumentException ) = 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 value - The Collection whose elements are to be retained
         * @returns true if the collection changed as a result of this call
         * @throw UnsupportedOperationException
         * @throw NullPointerException
         * @throw IllegalArgumentException
         */
        virtual bool retainAll( const Collection<E> value )
            throw ( lang::exceptions::UnsupportedOperationException,
                    lang::exceptions::NullPointerException,
                    lang::exceptions::IllegalArgumentException ) = 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.
         * @throw UnsupportedOperationException
         */
        virtual void clear()
            throw ( lang::exceptions::UnsupportedOperationException ) = 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.
         * @returns true if the Collections contain the same elements.
         */
        virtual bool equals( const Collection<E>& value ) = 0;

    };

}}

#endif /*_DECAF_UTIL_COLLECTION_H_*/