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