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