00001 /* 00002 * Collection.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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