00001 /* 00002 * LongArray.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_LONG_ARRAY_HPP 00017 #define COH_LONG_ARRAY_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/LongArrayIterator.hpp" 00022 00023 #include "coherence/io/pof/PofIntrinsic.hpp" 00024 00025 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 00028 /** 00029 * An interface, similar in its methods to List, and similar in its purpose 00030 * to an array, designed for sparse storage and indexed by long values. 00031 * 00032 * Unlike the List interface, the LongArray interface assumes that every 00033 * valid index (i.e. greater than or equal to zero) can be accessed and has 00034 * storage available. 00035 * 00036 * @author js 2008.04.03 00037 */ 00038 class COH_EXPORT LongArray 00039 : public interface_spec<LongArray, 00040 implements<coherence::io::pof::PofIntrinsic> > 00041 { 00042 // ----- LongArray interface -------------------------------------------- 00043 00044 public: 00045 /** 00046 * Return the value stored at the specified index. 00047 * 00048 * @param lIndex a long index value 00049 * 00050 * @return the object stored at the specified index, or NULL 00051 */ 00052 virtual Object::Holder get(int64_t lIndex) const = 0; 00053 00054 /** 00055 * Add the passed item to the LongArray at the specified index. 00056 * 00057 * If the index is already used, the passed value will replace the 00058 * current value stored with the key, and the replaced value will be 00059 * returned. 00060 * 00061 * It is expected that LongArray implementations will "grow" as 00062 * necessary to support the specified index. 00063 * 00064 * @param lIndex a long index value 00065 * @param ohValue the object to store at the specified index 00066 * 00067 * @return the object that was stored at the specified index, or NULL 00068 */ 00069 virtual Object::Holder set(int64_t lIndex, Object::Holder ohValue) = 0; 00070 00071 /** 00072 * Add the passed element value to the LongArray and return the index 00073 * at which the element value was stored. 00074 * 00075 * @param ohValue the object to add to the LongArray 00076 * 00077 * @return the long index value at which the element value was stored 00078 */ 00079 virtual int64_t add(Object::Holder ohValue) = 0; 00080 00081 /** 00082 * Determine if the specified index is in use. 00083 * 00084 * @param lIndex a long index value 00085 * 00086 * @return true if a value (including NULL) is stored at the specified 00087 * index, otherwise false 00088 */ 00089 virtual bool exists(int64_t lIndex) const = 0; 00090 00091 /** 00092 * Remove the specified index from the LongArray, returning its 00093 * associated value. 00094 * 00095 * @param lIndex the index into the LongArray 00096 * 00097 * @return the associated value (which can be NULL) or NULL if the 00098 * specified index is not in the LongArray 00099 */ 00100 virtual Object::Holder remove(int64_t lIndex) = 0; 00101 00102 /** 00103 * Determine if the LongArray contains the specified element. 00104 * 00105 * More formally, returns <tt>true</tt> if and only if this LongArray 00106 * contains at least one element <tt>e</tt> such that 00107 * <tt>(o==NULL ? e==NULL : o.equals(e))</tt>. 00108 * 00109 * @param vElement element whose presence in this list is to be 00110 * tested 00111 * 00112 * @return <tt>true</tt> if this list contains the specified element 00113 */ 00114 virtual bool contains(Object::View vElement) const = 0; 00115 00116 /** 00117 * Remove all nodes from the LongArray. 00118 */ 00119 virtual void clear() = 0; 00120 00121 /** 00122 * Test for empty LongArray. 00123 * 00124 * @return true if LongArray has no nodes 00125 */ 00126 virtual bool isEmpty() const = 0; 00127 00128 /** 00129 * Determine the size of the LongArray. 00130 * 00131 * @return the number of nodes in the LongArray 00132 */ 00133 virtual size32_t getSize() const = 0; 00134 00135 /** 00136 * Obtain a LongArray.Iterator of the contents of the LongArray. 00137 * 00138 * @return an instance of LongArray.Iterator 00139 */ 00140 virtual LongArrayIterator::Handle iterator() = 0; 00141 00142 /** 00143 * Obtain a "read-only" LongArray.Iterator of the contents of the 00144 * LongArray. Any attempt to modify the backing LongArray through 00145 * this iterator will result in an exception. 00146 * 00147 * @return an instance of LongArray.Iterator 00148 */ 00149 virtual LongArrayIterator::Handle iterator() const = 0; 00150 00151 /** 00152 * Obtain a LongArray.Iterator of the contents of the LongArray, 00153 * starting at a particular index such that the first call to 00154 * <tt>next</tt> will set the location of the iterator at the first 00155 * existent index that is greater than or equal to the specified 00156 * index, or will throw a NoSuchElementException if there is no such 00157 * existent index. 00158 * 00159 * @param lIndex the LongArray index to iterate from 00160 * 00161 * @return an instance of LongArray.Iterator 00162 */ 00163 virtual LongArrayIterator::Handle iterator(int64_t lIndex) = 0; 00164 00165 /** 00166 * Obtain a "read-only" LongArray.Iterator of the contents of the 00167 * LongArray, starting at a particular index such that the first call 00168 * to <tt>next</tt> will set the location of the iterator at the first 00169 * existent index that is greater than or equal to the specified 00170 * index, or will throw a NoSuchElementException if there is no such 00171 * existent index. Any attempt to modify the backing LongArray through 00172 * this iterator will result in an exception. 00173 * 00174 * @param lIndex the LongArray index to iterate from 00175 * 00176 * @return an instance of LongArray.Iterator 00177 */ 00178 virtual LongArrayIterator::Handle iterator(int64_t lIndex) const = 0; 00179 00180 /** 00181 * Determine the first index that exists in the LongArray. 00182 * 00183 * @return the lowest long value, 0 <= n <= Long.max_value, that 00184 * exists in this LongArray, or -1 if the LongArray is empty 00185 */ 00186 virtual int64_t getFirstIndex() const = 0; 00187 00188 /** 00189 * Determine the last index that exists in the LongArray. 00190 * 00191 * @return the highest long value, 0 <= n <= Long.max_value, that 00192 * exists in this LongArray, or -1 if the LongArray is empty 00193 */ 00194 virtual int64_t getLastIndex() const = 0; 00195 }; 00196 00197 COH_CLOSE_NAMESPACE2 00198 00199 #endif // COH_LONG_ARRAY_HPP