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_LITE_SET_HPP 00008 #define COH_LITE_SET_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/util/AbstractSet.hpp" 00013 #include "coherence/util/Enumeration.hpp" 00014 #include "coherence/util/Iterator.hpp" 00015 00016 COH_OPEN_NAMESPACE2(coherence,util) 00017 00018 00019 /** 00020 * An implementation of coherence::util::Set that is optimal (in terms of both 00021 * size and speed) for very small sets of data but still works excellently 00022 * with large sets of data. This implementation is not thread-safe. 00023 * 00024 * The LiteSet implementation switches at runtime between several different 00025 * sub-implementations for storing the set of objects, described here: 00026 * 00027 * <ol> 00028 * <li>"empty set" - a set that contains no data; 00029 * <li>"single entry" - a reference directly to an item is used to represent 00030 * a set with exactly one item in it; 00031 * <li>"ObjectArray" - a reference is held to an array of Objects that store 00032 * the contents of the Set; the item limit for this implementation is 00033 * determined by the threshold constant; 00034 * <li>"delegation" - for more than threshold items, a set is created to 00035 * delegate the set management to; sub-classes can override the default 00036 * delegation class (HashSet) by overriding the factory method 00037 * #instantiateSet(). 00038 * </ol> 00039 * 00040 * The LiteSet implementation supports the NULL value. 00041 * 00042 * @author cp/lh 10/18/2010 00043 */ 00044 class COH_EXPORT LiteSet 00045 : public cloneable_spec<LiteSet, 00046 extends<AbstractSet> > 00047 { 00048 friend class factory<LiteSet>; 00049 00050 // ----- constructors --------------------------------------------------- 00051 00052 protected: 00053 /** 00054 * Construct a LiteSet 00055 */ 00056 LiteSet(); 00057 00058 /** 00059 * Construct a LiteSet containing the elements of the passed Collection. 00060 * 00061 * @param vCollection a Collection 00062 */ 00063 LiteSet(Collection::View vCollection); 00064 00065 /* 00066 * Copy constructor 00067 * 00068 * @param that the LiteSet instance to copy from 00069 */ 00070 LiteSet(const LiteSet& that); 00071 00072 00073 // ----- Set interface -------------------------------------------------- 00074 00075 public: 00076 /** 00077 * {@inheritDoc} 00078 */ 00079 virtual bool isEmpty() const; 00080 00081 /** 00082 * {@inheritDoc} 00083 */ 00084 virtual size32_t size() const; 00085 00086 /** 00087 * {@inheritDoc} 00088 */ 00089 virtual bool contains(Object::View v) const; 00090 00091 /** 00092 * {@inheritDoc} 00093 */ 00094 virtual Iterator::Handle iterator() const; 00095 00096 /** 00097 * {@inheritDoc} 00098 */ 00099 virtual Muterator::Handle iterator(); 00100 00101 /** 00102 * {@inheritDoc} 00103 */ 00104 ObjectArray::Handle toArray(ObjectArray::Handle haDest = NULL) const; 00105 00106 /** 00107 * {@inheritDoc} 00108 */ 00109 bool add(Object::Holder oh); 00110 00111 /** 00112 * {@inheritDoc} 00113 */ 00114 bool remove(Object::View v); 00115 00116 /** 00117 * {@inheritDoc} 00118 */ 00119 virtual bool containsAll(Collection::View vCollection) const; 00120 00121 /** 00122 * {@inheritDoc} 00123 */ 00124 virtual bool addAll(Collection::View vCollection); 00125 00126 /** 00127 * {@inheritDoc} 00128 */ 00129 virtual bool retainAll(Collection::View vCollection); 00130 00131 /** 00132 * {@inheritDoc} 00133 */ 00134 virtual bool removeAll(Collection::View vCollection); 00135 00136 /** 00137 * {@inheritDoc} 00138 */ 00139 virtual void clear(); 00140 00141 00142 // ----- internal methods ----------------------------------------------- 00143 00144 protected: 00145 /** 00146 * (Factory pattern) Instantiate a Set object to store items in once 00147 * the "lite" threshold has been exceeded. This method permits 00148 * inheriting classes to easily override the choice of the Set object. 00149 * 00150 * @return an instance of Set 00151 */ 00152 Set::Handle instantiateSet(); 00153 00154 /** 00155 * (Factory pattern) Instantiate a Set object to store items in once 00156 * the "lite" threshold has been exceeded. This method permits 00157 * inheriting classes to easily override the choice of the Set object. 00158 * 00159 * @return an instance of Set 00160 */ 00161 Set::View instantiateSet() const; 00162 00163 /** 00164 * Initialize the contents of this Set from the passed array <tt>ao</tt> 00165 * containing <tt>c</tt> values. 00166 * 00167 * @param va the array that contains the values to place in this Set 00168 * @param c the number of values that will be placed into this Set 00169 */ 00170 void initFromArray(ObjectArray::View va, size32_t c); 00171 00172 /** 00173 * After a mutation operation has reduced the size of an underlying 00174 * Set, check if the delegation model should be replaced with a more 00175 * size-efficient storage approach, and switch accordingly. 00176 */ 00177 void checkShrinkFromOther(); 00178 00179 private: 00180 /** 00181 * Scan up to the first <tt>c</tt> elements of the passed array 00182 * <tt>ao</tt> looking for the specified Object <tt>o</tt>. If it is 00183 * found, return its position <tt>i</tt> in the array such that 00184 * <tt>(0 <= i < c)</tt>. If it is not found, return <tt>npos</tt>. 00185 * 00186 * @param va the array of objects to search 00187 * @param c the number of elements in the array to search 00188 * @param v the object to look for 00189 * 00190 * @return the index of the object, if found; otherwise npos 00191 */ 00192 static size32_t indexOf(ObjectArray::View va, size32_t c, Object::View v); 00193 00194 00195 // ----- constants ------------------------------------------------------ 00196 00197 public: 00198 /** 00199 * The largest possible value of type size32_t. 00200 */ 00201 static const size32_t npos = size32_t(-1); 00202 00203 private: 00204 /** 00205 * The default point above which the LiteSet delegates to another set 00206 * implementation. 00207 */ 00208 static const size32_t threshold = 8; 00209 00210 /** 00211 * Implementation: Empty set. 00212 */ 00213 static const size32_t i_empty = 0; 00214 00215 /** 00216 * Implementation: Single-item set. 00217 */ 00218 static const size32_t i_single = 1; 00219 00220 /** 00221 * Implementation: Array set of 1 item. 00222 */ 00223 static const size32_t i_array_1 = 2; 00224 00225 /** 00226 * Implementation: Array set of 2 items. 00227 */ 00228 static const size32_t i_array_2 = 3; 00229 00230 /** 00231 * Implementation: Array set of 3 items. 00232 */ 00233 static const size32_t i_array_3 = 4; 00234 00235 /** 00236 * Implementation: Array set of 4 items. 00237 */ 00238 static const size32_t i_array_4 = 5; 00239 00240 /** 00241 * Implementation: Array set of 5 items. 00242 */ 00243 static const size32_t i_array_5 = 6; 00244 00245 /** 00246 * Implementation: Array set of 6 items. 00247 */ 00248 static const size32_t i_array_6 = 7; 00249 00250 /** 00251 * Implementation: Array set of 7 items. 00252 */ 00253 static const size32_t i_array_7 = 8; 00254 00255 /** 00256 * Implementation: Array set of 8 items. 00257 */ 00258 static const size32_t i_array_8 = 9; 00259 00260 /** 00261 * Implementation: Delegation. 00262 */ 00263 static const size32_t i_other = 10; 00264 00265 00266 // ----- data members --------------------------------------------------- 00267 00268 private: 00269 /** 00270 * Implementation, one of i_empty, i_single, i_array_* or i_other. 00271 */ 00272 octet_t m_nImpl; 00273 00274 /** 00275 * The set contents, based on the implementation being used. 00276 */ 00277 MemberHolder<Object> m_hContents; 00278 }; 00279 00280 COH_CLOSE_NAMESPACE2 00281 00282 #endif // COH_LITE_SET_HPP