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