Oracle® Fusion Middleware C++ API Reference for Oracle Coherence
12c (12.2.1.1.0)

E69640-01

coherence/util/LiteSet.hpp

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