00001 /* 00002 * List.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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_LIST_HPP 00017 #define COH_LIST_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Collection.hpp" 00022 #include "coherence/util/ListIterator.hpp" 00023 #include "coherence/util/ListMuterator.hpp" 00024 00025 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 00028 /** 00029 * An ordered collection (also known as a sequence). 00030 * 00031 * The user of this interface has precise control over where in the list each 00032 * element is inserted. The user can access elements by their integer index 00033 * (position in the list), and search for elements in the list. Unlike sets, 00034 * lists typically allow duplicate elements. 00035 * 00036 * The List interface places additional stipulations, beyond those specified 00037 * in the Collection interface, on the contracts of the iterator, add, remove, 00038 * equals, and hashCode methods. 00039 * 00040 * @see Collection 00041 * 00042 * @author js/nsa 2008.01.03 00043 */ 00044 class COH_EXPORT List 00045 : public interface_spec<List, 00046 implements<Collection> > 00047 { 00048 // ----- constants ------------------------------------------------------ 00049 00050 public: 00051 /** 00052 * The largest possible value of type size32_t. 00053 */ 00054 static const size32_t npos = size32_t(-1); 00055 00056 00057 // ----- List interface ------------------------------------------------- 00058 00059 public: 00060 /** 00061 * Add the given element to this collection at the position specified. 00062 * If an element is already at that position it will be shifted to the 00063 * right by 1. 00064 * 00065 * @param i the position to insert the element at 00066 * @param oh the element to add 00067 * 00068 * @return true iff this list was modified as a result of this 00069 * operation 00070 * 00071 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00072 * out of range 00073 */ 00074 virtual bool add(size32_t i, Object::Holder oh) = 0; 00075 00076 /** 00077 * Add all the elements from the supplied collection to this 00078 * collection at the position specified. 00079 * 00080 * @param i the index of the list to add the elements to 00081 * @param vc the collection to add to this list 00082 * 00083 * @return true iff this list was modified as a result of this 00084 * operation 00085 * 00086 * @throw coherence::lang::IndexOutOfBoundsException if the inedex 00087 * is out of range 00088 */ 00089 virtual bool addAll(size32_t i, Collection::View vc) = 0; 00090 00091 /** 00092 * Return the element from the specified position in the list. 00093 * 00094 * @param i the position of the item to return 00095 * 00096 * @return the element from the specified position in the list 00097 * 00098 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00099 * out of range 00100 */ 00101 virtual Object::Holder get(size32_t i) const = 0; 00102 00103 /** 00104 * Return the element from the specified position in the list. 00105 * 00106 * @param i the position of the item to return 00107 * 00108 * @return the element from the specified position in the list 00109 * 00110 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00111 * out of range 00112 */ 00113 virtual Object::Holder get(size32_t i) = 0; 00114 00115 /** 00116 * Return the position in the list of the first instance of the 00117 * specified element. 00118 * 00119 * @param v The object in the list to return the index of 00120 * 00121 * @return the position of the object if found, or List::npos 00122 */ 00123 virtual size32_t indexOf(Object::View v) const = 0; 00124 00125 /** 00126 * Return the position in this list of the last instance of the 00127 * specified element. 00128 * 00129 * @param v The element to search for in the list 00130 * 00131 * @return the position of the element if found, or List::npos 00132 */ 00133 virtual size32_t lastIndexOf(Object::View v) const = 0; 00134 00135 /** 00136 * Return a ListIterator for this list starting at index 00137 * 00138 * @param i the index to start the ListIterator at 00139 * 00140 * @return a ListIterator for this list start at index 00141 */ 00142 virtual ListIterator::Handle listIterator(size32_t i = 0) const = 0; 00143 00144 /** 00145 * Return a ListIterator for this list starting at index 00146 * 00147 * @param i the index to start the ListIterator at 00148 * 00149 * @return a ListIterator for this list start at index 00150 */ 00151 virtual ListMuterator::Handle listIterator(size32_t i = 0) = 0; 00152 00153 /** 00154 * Remove the element at the specified position in the list. 00155 * 00156 * @param i the index from which to remove an element 00157 * 00158 * @return the element at the specified position prior to this 00159 * operation 00160 * 00161 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00162 * out of range 00163 */ 00164 virtual Object::Holder remove(size32_t i) = 0; 00165 00166 /** 00167 * Replace the element at the specified position in this list with the 00168 * specified element. 00169 * 00170 * @param i the position in the list to replace 00171 * @param oh the object to replace at the specified position 00172 * 00173 * @return the element at the specified position prior to this 00174 * operation 00175 * 00176 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00177 * out of range 00178 */ 00179 virtual Object::Holder set(size32_t i, Object::Holder oh) = 0; 00180 00181 /** 00182 * Return a new list containing the contents of the list between the 00183 * specified fromIndex (inclusive) and toIndex (exclusive). 00184 * 00185 * @param iFrom the start position in this list to create the 00186 * sublist from (inclusive). 00187 * @param iTo the end position in this list to end the sublist 00188 * at (exclusive). 00189 * 00190 * @return the new sublist of this list 00191 */ 00192 virtual List::View subList(size32_t iFrom, size32_t iTo) const = 0; 00193 00194 /** 00195 * Return a new list containing the contents of the list between the 00196 * specified fromIndex (inclusive) and toIndex (exclusive). 00197 * 00198 * @param iFrom the start position in this list to create the 00199 * sublist from (inclusive). 00200 * @param iTo the end position in this list to end the sublist 00201 * at (exclusive). 00202 * 00203 * @return the new sublist of this list 00204 */ 00205 virtual List::Handle subList(size32_t iFrom, size32_t iTo) = 0; 00206 00207 00208 // ----- Collection interface ------------------------------------------- 00209 00210 public: 00211 /** 00212 * Add the given element to the end of this list. 00213 * 00214 * @param oh element to be added to this list 00215 * 00216 * @return true 00217 */ 00218 using Collection::add; 00219 00220 /** 00221 * {@inheritDoc} 00222 */ 00223 using Collection::addAll; 00224 00225 /** 00226 * {@inheritDoc} 00227 */ 00228 using Collection::remove; 00229 00230 00231 // ----- Object interface ----------------------------------------------- 00232 00233 public: 00234 /** 00235 * Compares the specified object with this list for equality. 00236 * 00237 * Two lists are defined to be equal iff they contain the same 00238 * elements in the same order. This definition ensures that the equals 00239 * method works properly across different implementations of the List 00240 * interface. 00241 * 00242 * @param vObj the Object to be compared for equality with this list 00243 * 00244 * @return true if the specified Object is equal to this list. 00245 */ 00246 using Object::equals; 00247 00248 /** 00249 * The hash code of a List is defined as follows: 00250 * <code> 00251 * size32_t nHash = 1; 00252 * for (Iterator::Handle hIter = list.iterator(); hIter->hasNext(); ) 00253 * { 00254 * Object::View v = hIter->next(); 00255 * nHash = 31 * nHash + Object::hashCode(v); 00256 * } 00257 * </code> This ensures that <code>l1->equals(l2)</code> implies that 00258 * <code>l1->hashCode() == l2->hashCode()</code> for any two lists 00259 * <tt>l1</tt> and <tt>l2</tt>, as required by the general contract of 00260 * Object::hashCode(). 00261 * 00262 * @return the hash code value for this list 00263 */ 00264 using Object::hashCode; 00265 }; 00266 00267 COH_CLOSE_NAMESPACE2 00268 00269 #endif // COH_LIST_HPP