Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/util/Collection.hpp

00001 /*
00002 * Collection.hpp
00003 *
00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
00005 *
00006 * Oracle is a registered trademarks of Oracle Corporation and/or its
00007 * affiliates.
00008 *
00009 * This software is the confidential and proprietary information of Oracle
00010 * Corporation. You shall not disclose such confidential and proprietary
00011 * information and shall use it only in accordance with the terms of the
00012 * license agreement you entered into with Oracle.
00013 *
00014 * This notice may not be removed or altered.
00015 */
00016 #ifndef COH_COLLECTION_HPP
00017 #define COH_COLLECTION_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 #include "coherence/util/Iterator.hpp"
00022 #include "coherence/util/Muterator.hpp"
00023 
00024 COH_OPEN_NAMESPACE2(coherence,util)
00025 
00026 
00027 /**
00028 * The base interface of all <i>collections</i> managed by Coherence. A
00029 * collection is a group of objects also known as elements. The following
00030 * behaviors of a collection are implementation dependent:
00031 * <ul>
00032 *   <li>ordered iteration</li>
00033 *   <li>support for duplicate elements</li>
00034 *   <li>element equivalency by state equality (Object::equals())</li>
00035 *   <li>accessibility of elements only as views</li>
00036 *   <li>retention of elements by copy</li>
00037 *   <li>thread-safe</li>
00038 * </ul>
00039 *
00040 * Unless otherwise stated, collections are assumed to not support any of the
00041 * above.
00042 *
00043 * @see Iterator
00044 * @see List
00045 * @see Map
00046 * @see Set
00047 *
00048 * @author jh/mf/nsa  2008.01.28
00049 */
00050 class COH_EXPORT Collection
00051     : public interface_spec<Collection>
00052     {
00053     // ----- Collection interface -------------------------------------------
00054 
00055     public:
00056         /**
00057         * Return the number of elements in this collection.
00058         *
00059         * @return the number of elements in this collection
00060         */
00061         virtual size32_t size() const = 0;
00062 
00063         /**
00064         * Determine whether this collection contains any elements.
00065         *
00066         * @return true if this collection has no elements
00067         */
00068         virtual bool isEmpty() const = 0;
00069 
00070         /**
00071         * Determine if this collection contains the specified element.
00072         *
00073         * @param v  the element to test for containment
00074         *
00075         * @return true iff this collection contains the given element
00076         */
00077         virtual bool contains(Object::View v) const = 0;
00078 
00079         /**
00080         * Determine if this collection contains all elements from the
00081         * supplied collection.
00082         *
00083         * @param vCol  the collection of elements to test for containment
00084         *
00085         * @return true iff this collection contains all elements from the
00086         *         supplied collection
00087         *
00088         * @throws coherence::lang::NullPointerException if the specified
00089         *         collection is NULL
00090         *
00091         * @see contains()
00092         */
00093         virtual bool containsAll(Collection::View vCol) const = 0;
00094 
00095         /**
00096         * Return an Iterator over this collection.
00097         *
00098         * @return an Iterator over this collection
00099         */
00100         virtual Iterator::Handle iterator() const = 0;
00101 
00102         /**
00103         * Return an Iterator over this collection.
00104         *
00105         * @return an Iterator over this collection
00106         */
00107         virtual Muterator::Handle iterator() = 0;
00108 
00109         /**
00110         * Return the contents of this collection as an ObjectArray.
00111         * If the collection fits in the specified array, it is returned,
00112         * otherwise, a new array is allocated that is the size of this
00113         * collection.
00114         *
00115         * If this collection fits in the array with aditional room
00116         * then the element in the array immediately following the end of the
00117         * collection is set to NULL.  This can be useful in determining the
00118         * length of this collection if the caller knows that the collection
00119         * does not contain any NULL elements.
00120         *
00121         * @param hao  an array in which to store the collection's contents
00122         *
00123         * @return a ObjectArray containing all the elements of the collection
00124         *         in the same order as returned by the collection's Iterator
00125         *
00126         * @see Iterator
00127         */
00128         virtual ObjectArray::Handle toArray(
00129                 ObjectArray::Handle hao = NULL) const = 0;
00130 
00131         /**
00132         * Add the given element to this collection.
00133         *
00134         * @param oh  the element to add
00135         *
00136         * @return true iff this collection was modified as a result of this
00137         *         operation
00138         */
00139         virtual bool add(Object::Holder oh) = 0;
00140 
00141         /**
00142         * Add all elements from the supplied collection to this collection.
00143         *
00144         * @param vCol  the collection of elements to add
00145         *
00146         * @return true iff this collection was modified as a result of this
00147         *         operation
00148         *
00149         * @throws coherence::lang::NullPointerException if the specified
00150         *         collection is NULL
00151         *
00152         * @see add()
00153         */
00154         virtual bool addAll(Collection::View vCol) = 0;
00155 
00156         /**
00157         * Remove the supplied element from this collection.
00158         *
00159         * @param v     the element to remove
00160         *
00161         * @return true iff this collection was modified as a result of this
00162         *         operation
00163         */
00164         virtual bool remove(Object::View v) = 0;
00165 
00166         /**
00167         * Remove all instances of the elements in the supplied collection
00168         * from this collection. Upon completion, contains() on this
00169         * collection will return false for all elements in the supplied
00170         * collection.
00171         *
00172         * @param vCol  the collection of elements to remove
00173         *
00174         * @return true iff this collection was modified as a result of this
00175         *         operation
00176         *
00177         * @throws coherence::lang::NullPointerException if the specified
00178         *         collection is NULL
00179         *
00180         * @see remove()
00181         * @see contains()
00182         */
00183         virtual bool removeAll(Collection::View vCol) = 0;
00184 
00185         /**
00186         * Remove all elements from this collection that are not present in
00187         * the supplied collection.
00188         *
00189         * @param vCol  the collection of elements to retain
00190         *
00191         * @return true iff this collection was modified as a result of this
00192         *         operation.
00193         *
00194         * @throws coherence::lang::NullPointerException if the specified
00195         *         collection is NULL
00196         *
00197         * @see remove()
00198         * @see contains()
00199         */
00200         virtual bool retainAll(Collection::View vCol) = 0;
00201 
00202         /**
00203         * Remove all elements from this collection.
00204         */
00205         virtual void clear() = 0;
00206     };
00207 
00208 COH_CLOSE_NAMESPACE2
00209 
00210 #endif // COH_COLLECTION_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.