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