This is an automated email from the ASF dual-hosted git repository. bchapuis pushed a commit to branch data-refactoring in repository https://gitbox.apache.org/repos/asf/incubator-baremaps.git
commit 766781bc5950d90b2b61d6a75caf25bab208cff4 Author: Bertil Chapuis <[email protected]> AuthorDate: Sat Apr 5 14:05:38 2025 +0200 Improve the javadoc and make it more consistent --- .../baremaps/data/collection/AppendOnlyLog.java | 46 +++++++------- .../baremaps/data/collection/DataCollection.java | 49 +++++++------- .../data/collection/DataCollectionException.java | 22 ++++--- .../data/collection/DataCollectionMapper.java | 11 ++-- .../baremaps/data/collection/DataConversions.java | 48 ++++++++------ .../apache/baremaps/data/collection/DataList.java | 21 +++--- .../apache/baremaps/data/collection/DataMap.java | 74 +++++++++++----------- .../data/collection/DirectHashDataMap.java | 42 +++++++----- .../data/collection/FixedSizeDataList.java | 23 ++++--- .../baremaps/data/collection/IndexedDataList.java | 15 ++--- .../baremaps/data/collection/IndexedDataMap.java | 19 +++--- .../data/collection/MemoryAlignedDataList.java | 27 ++++---- .../data/collection/MemoryAlignedDataMap.java | 24 +++++-- .../baremaps/data/collection/MonotonicDataMap.java | 19 +++--- .../data/collection/MonotonicFixedSizeDataMap.java | 5 +- .../data/collection/MonotonicPairedDataMap.java | 17 +++-- 16 files changed, 248 insertions(+), 214 deletions(-) diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/AppendOnlyLog.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/AppendOnlyLog.java index d7b03482d..c5e9adbdc 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/AppendOnlyLog.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/AppendOnlyLog.java @@ -30,11 +30,10 @@ import org.apache.baremaps.data.memory.OffHeapMemory; import org.apache.baremaps.data.type.DataType; /** - * A log of records backed by a {@link DataType} and a {@link Memory}. Elements are appended to the - * log and can be accessed by their position in the {@link Memory}. Appending elements to the log is - * thread-safe. + * A log of elements that can only be appended to. Elements are stored in memory and can be accessed + * by their position. Append operations are thread-safe. * - * @param <E> The type of the data. + * @param <E> The type of elements in the log */ public class AppendOnlyLog<E> implements DataCollection<E> { @@ -47,7 +46,7 @@ public class AppendOnlyLog<E> implements DataCollection<E> { private final Lock lock = new ReentrantLock(); /** - * Static factory method to create a new builder. + * Creates a new builder for an AppendOnlyLog. * * @param <E> the type of elements * @return a new builder @@ -57,7 +56,7 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Builder for {@link AppendOnlyLog}. + * Builder for AppendOnlyLog. * * @param <E> the type of elements */ @@ -90,7 +89,7 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Sets the values memory for the log. This is an alias for {@link #memory(Memory)}. + * Sets the memory for the log values. * * @param memory the memory * @return this builder @@ -100,7 +99,7 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Builds a new {@link AppendOnlyLog}. + * Builds a new AppendOnlyLog. * * @return a new AppendOnlyLog * @throws IllegalStateException if required parameters are missing @@ -119,7 +118,7 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Constructs an append only log. + * Constructs an AppendOnlyLog. * * @param dataType the data type * @param memory the memory @@ -140,10 +139,11 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Appends the value to the log and returns its position in the memory. + * Appends an element to the log and returns its position in memory. * - * @param value the value - * @return the position of the value in the memory. + * @param value the element to add + * @return the position of the element in memory + * @throws DataCollectionException if the element is too large for a segment */ public long addPositioned(E value) { int valueSize = dataType.size(value); @@ -172,10 +172,10 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Returns a values at the specified position in the memory. + * Returns the element at the specified position in memory. * - * @param position the position of the value - * @return the value + * @param position the position of the element + * @return the element */ public E getPositioned(long position) { long segmentIndex = position / segmentSize; @@ -208,10 +208,9 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * Returns an iterator over the values of the log, starting at the beginning of the log. The - * iterator allows to get the current position in the memory. + * Returns an iterator over the elements of this log. * - * @return an iterator over the values of the log + * @return an iterator over the elements */ @Override public AppendOnlyLogIterator iterator() { @@ -228,15 +227,12 @@ public class AppendOnlyLog<E> implements DataCollection<E> { } /** - * An iterator over the values of the log that can be used to iterate over the values of the log - * and to get the current position in the memory. + * An iterator over the elements in this log. */ public class AppendOnlyLogIterator implements Iterator<E> { private final long size; - private long index; - private long position; private AppendOnlyLogIterator(long size) { @@ -280,9 +276,13 @@ public class AppendOnlyLog<E> implements DataCollection<E> { return dataType.read(segment, (int) segmentOffset); } + /** + * Returns the current position in memory. + * + * @return the current position + */ public long getPosition() { return position; } - } } diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollection.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollection.java index 7df3aaf25..5c5f549f6 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollection.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollection.java @@ -22,29 +22,31 @@ import java.util.stream.Stream; import java.util.stream.StreamSupport; /** - * A {@code DataCollection<E>} is a group of elements that can be iterated over. It is similar to a - * {@link java.util.Collection<E> Collection}, but can hold up to {@link Long#MAX_VALUE} elements. + * A collection of elements that can be iterated over. Similar to {@link java.util.Collection} but + * supports up to {@link Long#MAX_VALUE} elements. + * + * @param <E> The type of elements in the collection */ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { /** - * Returns the number of values stored in the data collection. + * Returns the number of elements in this collection. * - * @return the number of values + * @return the number of elements */ long size(); /** - * Returns true if the data collection is empty. + * Returns true if this collection contains no elements. * - * @return true if the data collection is empty + * @return true if this collection is empty */ default boolean isEmpty() { return size() == 0; } /** - * Returns an iterator over the elements in the data collection. + * Returns an iterator over the elements in this collection. * * @return an iterator */ @@ -52,7 +54,7 @@ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { Iterator<E> iterator(); /** - * Returns a spliterator over the elements in the data collection. + * Returns a spliterator over the elements in this collection. * * @return a spliterator */ @@ -62,16 +64,16 @@ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { } /** - * Returns a stream over the elements in the data collection. + * Returns a sequential stream over the elements in this collection. * - * @return a stream + * @return a sequential stream */ default Stream<E> stream() { return StreamSupport.stream(spliterator(), false); } /** - * Returns a parallel stream over the elements in the data collection. + * Returns a parallel stream over the elements in this collection. * * @return a parallel stream */ @@ -80,20 +82,20 @@ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { } /** - * Adds a value to the data collection. + * Adds an element to this collection. * - * @param e the value to add - * @return true if the data collection has been modified + * @param e the element to add + * @return true if the collection changed as a result of the call */ default boolean add(E e) { throw new UnsupportedOperationException(); } /** - * Adds all the values in the specified collection to the data collection. + * Adds all elements from the specified collection to this collection. * - * @param c the collection of values to add - * @return true if the data collection has been modified + * @param c the collection of elements to add + * @return true if this collection changed as a result of the call */ default boolean addAll(Iterable<? extends E> c) { boolean modified = false; @@ -106,9 +108,10 @@ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { } /** - * Returns true if the data collection contains the specified value. + * Returns true if this collection contains the specified element. * - * @param o the value to search for + * @param o the element to check for + * @return true if this collection contains the element */ default boolean contains(Object o) { for (E e : this) { @@ -120,10 +123,10 @@ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { } /** - * Returns true if the data collection contains all the values in the specified collection. + * Returns true if this collection contains all elements in the specified collection. * - * @param c the collection of values to search for - * @return true if the data collection contains all the values + * @param c the collection to check against + * @return true if this collection contains all elements in the specified collection */ default boolean containsAll(Iterable<?> c) { for (Object o : c) { @@ -135,7 +138,7 @@ public interface DataCollection<E> extends Iterable<E>, AutoCloseable { } /** - * Removes all the values from the data collection. + * Removes all elements from this collection. */ void clear(); diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionException.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionException.java index a4300ccf8..7720b2023 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionException.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionException.java @@ -17,35 +17,39 @@ package org.apache.baremaps.data.collection; -/** Signals that an exception occurred in a store. */ +/** + * Exception thrown when an error occurs in a data collection operation. + */ public class DataCollectionException extends RuntimeException { - /** Constructs a {@code DataCollectionException} with {@code null} as its error detail message. */ + /** + * Constructs a new exception with null as its detail message. + */ public DataCollectionException() {} /** - * Constructs an {@code DataCollectionException} with the specified detail message. + * Constructs a new exception with the specified detail message. * - * @param message the message + * @param message the detail message */ public DataCollectionException(String message) { super(message); } /** - * Constructs a {@code DataCollectionException} with the specified cause. + * Constructs a new exception with the specified cause. * - * @param cause the cause + * @param cause the cause of this exception */ public DataCollectionException(Throwable cause) { super(cause); } /** - * Constructs a {@code DataCollectionException} with the specified detail message and cause. + * Constructs a new exception with the specified detail message and cause. * - * @param message the message - * @param cause the cause + * @param message the detail message + * @param cause the cause of this exception */ public DataCollectionException(String message, Throwable cause) { super(message, cause); diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionMapper.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionMapper.java index b8c545088..9ab9101c4 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionMapper.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataCollectionMapper.java @@ -22,7 +22,10 @@ import java.util.Iterator; import java.util.function.Function; /** - * A decorator for a table that transforms the geometries of the rows. + * A decorator that transforms elements of a data collection using a function. + * + * @param <S> The source element type + * @param <T> The transformed element type */ public class DataCollectionMapper<S, T> implements DataCollection<T> { @@ -31,10 +34,10 @@ public class DataCollectionMapper<S, T> implements DataCollection<T> { private final Function<S, T> mapper; /** - * Constructs a new table decorator. + * Constructs a new mapper for a data collection. * - * @param collection the table to decorate - * @param mapper the row transformer + * @param collection the source collection + * @param mapper the function to transform elements */ public DataCollectionMapper(DataCollection<S> collection, Function<S, T> mapper) { this.collection = collection; diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataConversions.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataConversions.java index 3e361d77f..8f1957c16 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataConversions.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataConversions.java @@ -21,7 +21,7 @@ import java.util.*; import java.util.Map.Entry; /** - * Utility class for converting between collections and data collections. + * Utility class for converting between standard Java collections and data collections. */ public class DataConversions { @@ -30,11 +30,11 @@ public class DataConversions { } /** - * Converts a {@code DataCollection} to a {@code Collection}. + * Converts a DataCollection to a Collection. * - * @param dataCollection - * @return - * @param <E> + * @param dataCollection the data collection to convert + * @return a Collection view of the data collection + * @param <E> the type of elements */ public static <E> Collection<E> asCollection(DataCollection<E> dataCollection) { if (dataCollection instanceof DataCollectionAdapter<E>adapter) { @@ -45,11 +45,11 @@ public class DataConversions { } /** - * Converts a {@code Collection} to a {@code DataCollection}. + * Converts a Collection to a DataCollection. * - * @param collection - * @return - * @param <E> + * @param collection the collection to convert + * @return a DataCollection view of the collection + * @param <E> the type of elements */ public static <E> DataCollection<E> asDataCollection(Collection<E> collection) { if (collection instanceof CollectionAdapter<E>adapter) { @@ -60,10 +60,11 @@ public class DataConversions { } /** - * Converts a {@code DataList} to a {@code List}. + * Converts a DataList to a List. * - * @param dataList the data list - * @return the list + * @param dataList the data list to convert + * @return a List view of the data list + * @param <E> the type of elements */ public static <E> List<E> asList(DataList<E> dataList) { if (dataList instanceof DataListAdapter<E>adapter) { @@ -74,10 +75,11 @@ public class DataConversions { } /** - * Converts a {@code List} to a {@code DataList}. + * Converts a List to a DataList. * - * @param list the list - * @return the data list + * @param list the list to convert + * @return a DataList view of the list + * @param <E> the type of elements */ public static <E> DataList<E> asDataList(List<E> list) { if (list instanceof ListAdapter<E>adapter) { @@ -88,10 +90,12 @@ public class DataConversions { } /** - * Converts a {@code DataMap} to a {@code Map}. + * Converts a DataMap to a Map. * - * @param dataMap the data map - * @return the map + * @param dataMap the data map to convert + * @return a Map view of the data map + * @param <K> the type of keys + * @param <V> the type of values */ public static <K, V> Map<K, V> asMap(DataMap<K, V> dataMap) { if (dataMap instanceof DataMapAdapter<K, V>adapter) { @@ -102,10 +106,12 @@ public class DataConversions { } /** - * Converts a {@code Map} to a {@code DataMap}. + * Converts a Map to a DataMap. * - * @param map the map - * @return the data map + * @param map the map to convert + * @return a DataMap view of the map + * @param <K> the type of keys + * @param <V> the type of values */ public static <K, V> DataMap<K, V> asDataMap(Map<K, V> map) { if (map instanceof MapAdapter<K, V>adapter) { diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataList.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataList.java index de711d101..39c6c95c6 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataList.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataList.java @@ -23,19 +23,18 @@ import java.util.Iterator; import java.util.NoSuchElementException; /** - * A {@code DataList<E>} is a sequence of elements that can be iterated over and accessed by index. - * It is similar to a {@link java.util.List<E> List}, but can hold up to {@link Long#MAX_VALUE} - * elements. + * A sequence of elements that can be accessed by index. Similar to {@link java.util.List} but + * supports up to {@link Long#MAX_VALUE} elements. * - * @param <E> The type of the elements. + * @param <E> The type of elements in the list */ public interface DataList<E> extends DataCollection<E> { /** - * Adds a value to the data list and returns its index. + * Adds an element to this list and returns its index. * - * @param value the value - * @return the index of the value. + * @param value the element to add + * @return the index of the added element */ long addIndexed(E value); @@ -47,18 +46,18 @@ public interface DataList<E> extends DataCollection<E> { } /** - * Sets the value at the specified index + * Sets the element at the specified index. * * @param index the index - * @param value the value + * @param value the element to set */ void set(long index, E value); /** - * Returns the value at the specified index. + * Returns the element at the specified index. * * @param index the index - * @return the value + * @return the element at the specified index */ E get(long index); diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataMap.java index 1ae196bf3..ecd4738d6 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DataMap.java @@ -25,34 +25,34 @@ import java.util.Map.Entry; import java.util.function.BiConsumer; /** - * A {@code DataMap<E>} maps keys to values. It is similar to a {@link java.util.Map<K, V> Map}, but - * can hold up to {@link Long#MAX_VALUE} entries. + * A map that associates keys with values. Similar to {@link java.util.Map} but supports up to + * {@link Long#MAX_VALUE} entries. * - * @param <K> The type of the keys. - * @param <V> The type of the values. + * @param <K> The type of keys in the map + * @param <V> The type of values in the map */ public interface DataMap<K, V> extends AutoCloseable { /** - * Returns the number of values stored in the data map. + * Returns the number of key-value mappings in this map. * - * @return the number of values + * @return the number of key-value mappings */ long size(); /** - * Returns the value associated with the specified key or null if the key is not present. + * Returns the value associated with the specified key, or null if no mapping exists. * * @param key the key - * @return the value + * @return the value associated with the key, or null if no mapping exists */ V get(Object key); /** - * Returns the values associated with the specified keys or null if the key is not present. + * Returns the values associated with the specified keys, or null for keys with no mapping. * * @param keys the keys - * @return the values + * @return the values associated with the keys */ default Iterable<V> getAll(Iterable<K> keys) { List<V> values = new ArrayList<>(); @@ -61,105 +61,105 @@ public interface DataMap<K, V> extends AutoCloseable { } /** - * Associates the specified value with the specified key in the data map. + * Associates the specified value with the specified key in this map. * * @param key the key * @param value the value - * @return the previous value associated with the key, or null if there was no mapping for the key + * @return the previous value associated with the key, or null if there was no mapping */ V put(K key, V value); /** - * Associates the specified values with the specified keys in the data map. + * Adds all entries from the specified iterable to this map. * - * @param entries the entries + * @param entries the entries to add */ default void putAll(Iterable<Entry<K, V>> entries) { entries.forEach(entry -> put(entry.getKey(), entry.getValue())); } /** - * Returns true if the data map contains a mapping for the specified key. + * Returns true if this map contains a mapping for the specified key. * - * @param key the key - * @return true if the data map contains a mapping for the key + * @param key the key to check + * @return true if this map contains a mapping for the key */ boolean containsKey(Object key); /** - * Returns true if the data map contains a mapping for the specified value. + * Returns true if this map maps one or more keys to the specified value. * - * @param value the value - * @return true if the data map contains a mapping for the value + * @param value the value to check + * @return true if this map maps one or more keys to the value */ boolean containsValue(V value); /** - * Clears the data map. + * Removes all mappings from this map. */ void clear(); /** - * Returns true if the data map contains no elements. + * Returns true if this map contains no mappings. * - * @return true if the data map contains no elements + * @return true if this map contains no mappings */ default boolean isEmpty() { return size() == 0; } /** - * Returns an iterator over the keys of the data map. + * Returns an iterator over the keys in this map. * - * @return an iterator + * @return an iterator over the keys */ Iterator<K> keyIterator(); /** - * Returns an iterable over the keys of the data map. + * Returns an iterable over the keys in this map. * - * @return an iterable + * @return an iterable over the keys */ default Iterable<K> keys() { return this::keyIterator; } /** - * Returns an iterator over the values of the data map. + * Returns an iterator over the values in this map. * - * @return an iterator + * @return an iterator over the values */ Iterator<V> valueIterator(); /** - * Returns an iterable over the values of the data map. + * Returns an iterable over the values in this map. * - * @return an iterable + * @return an iterable over the values */ default Iterable<V> values() { return this::valueIterator; } /** - * Returns an iterator over the entries of the data map. + * Returns an iterator over the entries in this map. * - * @return an iterator + * @return an iterator over the entries */ Iterator<Entry<K, V>> entryIterator(); /** - * Returns an iterable over the entries of the data map. + * Returns an iterable over the entries in this map. * - * @return an iterable + * @return an iterable over the entries */ default Iterable<Entry<K, V>> entries() { return this::entryIterator; } /** - * Performs the given action for each entry in the data map. + * Performs the given action for each entry in this map. * - * @param action the action to be performed + * @param action the action to perform on each entry */ default void forEach(BiConsumer<? super K, ? super V> action) { for (Entry<K, V> entry : entries()) { diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DirectHashDataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DirectHashDataMap.java index a4e09a0b0..2fb63e086 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DirectHashDataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/DirectHashDataMap.java @@ -27,14 +27,10 @@ import org.apache.baremaps.data.memory.Memory; import org.apache.baremaps.data.type.FixedSizeDataType; /** - * A {@link DataMap} that uses direct hashing with open addressing and linear probing. This - * implementation provides O(1) access time for both get and put operations and doesn't have any - * insertion order dependencies. + * A map that uses direct hashing with open addressing and linear probing. Provides O(1) access time + * for both get and put operations with a fixed capacity. * - * <p> - * The map size is fixed at instantiation time and cannot be resized afterward. - * - * @param <V> the type of the values + * @param <V> the type of values in the map */ public class DirectHashDataMap<V> implements DataMap<Long, V> { @@ -53,7 +49,7 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { private long size; /** - * Static factory method to create a new builder. + * Creates a new builder for a DirectHashDataMap. * * @param <V> the type of values * @return a new builder @@ -63,7 +59,7 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Builder for {@link DirectHashDataMap}. + * Builder for DirectHashDataMap. * * @param <V> the type of values */ @@ -130,7 +126,7 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Builds a new {@link DirectHashDataMap}. + * Builds a new DirectHashDataMap. * * @return a new DirectHashDataMap * @throws IllegalStateException if any required parameter is missing @@ -157,7 +153,7 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Constructs a {@link DirectHashDataMap} with the specified capacity. + * Constructs a DirectHashDataMap with the specified capacity. * * @param keyType the data type for keys * @param dataType the data type for values @@ -187,7 +183,7 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Hash function for keys, using multiplicative hashing. + * Computes the hash value for a key. * * @param key the key to hash * @return the hash value @@ -203,7 +199,7 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { * Finds the slot for a key, either for retrieval or insertion. * * @param key the key to find - * @param forInsertion whether we're finding for insertion (return empty slot) or retrieval + * @param forInsertion whether we're finding for insertion or retrieval * @return the slot index or -1 if not found and not for insertion */ private long findSlot(long key, boolean forInsertion) { @@ -239,7 +235,10 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Reads a key from the key memory at the specified slot. + * Reads a key from the specified slot. + * + * @param slot the slot index + * @return the key at the slot */ private long readKey(long slot) { long position = slot * keySize; @@ -250,7 +249,10 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Stores a key in the key memory at the specified slot. + * Stores a key at the specified slot. + * + * @param slot the slot index + * @param key the key to store */ private void storeKey(long slot, long key) { long position = slot * keySize; @@ -261,7 +263,10 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Reads a value from the value memory at the specified slot. + * Reads a value from the specified slot. + * + * @param slot the slot index + * @return the value at the slot */ private V readValue(long slot) { long position = slot * valueSize; @@ -272,7 +277,10 @@ public class DirectHashDataMap<V> implements DataMap<Long, V> { } /** - * Stores a value in the value memory at the specified slot. + * Stores a value at the specified slot. + * + * @param slot the slot index + * @param value the value to store */ private void storeValue(long slot, V value) { long position = slot * valueSize; diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/FixedSizeDataList.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/FixedSizeDataList.java index eacab78c4..5c7b57478 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/FixedSizeDataList.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/FixedSizeDataList.java @@ -26,21 +26,19 @@ import org.apache.baremaps.data.memory.OffHeapMemory; import org.apache.baremaps.data.type.FixedSizeDataType; /** - * A {@link DataList} that can hold a large number of fixed size data elements. This data list is - * backed by a memory that can be either heap, off-heap, or memory mapped. + * A list that stores fixed-size elements in memory. Elements can be stored in heap memory, off-heap + * memory, or memory-mapped files. * - * @param <E> The type of the elements. + * @param <E> The type of elements in the list */ public class FixedSizeDataList<E> implements DataList<E> { private final FixedSizeDataType<E> dataType; - private final Memory<?> memory; - private AtomicLong size; /** - * Static factory method to create a new builder. + * Creates a new builder for a FixedSizeDataList. * * @param <E> the type of elements * @return a new builder @@ -50,7 +48,7 @@ public class FixedSizeDataList<E> implements DataList<E> { } /** - * Builder for {@link FixedSizeDataList}. + * Builder for FixedSizeDataList. * * @param <E> the type of elements */ @@ -81,7 +79,7 @@ public class FixedSizeDataList<E> implements DataList<E> { } /** - * Builds a new {@link FixedSizeDataList}. + * Builds a new FixedSizeDataList. * * @return a new FixedSizeDataList * @throws IllegalStateException if the data type is missing @@ -100,10 +98,11 @@ public class FixedSizeDataList<E> implements DataList<E> { } /** - * Constructs a list. + * Constructs a FixedSizeDataList. * * @param dataType the data type * @param memory the memory + * @throws DataCollectionException if the data type is too large for the memory segment size */ private FixedSizeDataList(FixedSizeDataType<E> dataType, Memory<?> memory) { if (dataType.size() > memory.segmentSize()) { @@ -114,6 +113,12 @@ public class FixedSizeDataList<E> implements DataList<E> { this.size = new AtomicLong(0); } + /** + * Writes an element at the specified index. + * + * @param index the index + * @param value the element to write + */ private void write(long index, E value) { long position = index * dataType.size(); int segmentIndex = (int) (position / memory.segmentSize()); diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataList.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataList.java index 763546e3f..1a14640f5 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataList.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataList.java @@ -22,19 +22,18 @@ package org.apache.baremaps.data.collection; import org.apache.baremaps.data.type.LongDataType; /** - * A data list that can hold a large number of variable size data elements. This data list is backed - * by an index and a buffer that can be either heap, off-heap, or memory mapped. + * A list that stores variable-size elements using an index. Elements are stored in an append-only + * log with fixed indices for fast access. * - * @param <E> The type of the elements. + * @param <E> The type of elements in the list */ public class IndexedDataList<E> implements DataList<E> { private final DataList<Long> index; - private final AppendOnlyLog<E> values; /** - * Static factory method to create a new builder. + * Creates a new builder for an IndexedDataList. * * @param <E> the type of elements * @return a new builder @@ -44,7 +43,7 @@ public class IndexedDataList<E> implements DataList<E> { } /** - * Builder for {@link IndexedDataList}. + * Builder for IndexedDataList. * * @param <E> the type of elements */ @@ -75,7 +74,7 @@ public class IndexedDataList<E> implements DataList<E> { } /** - * Builds a new {@link IndexedDataList}. + * Builds a new IndexedDataList. * * @return a new IndexedDataList * @throws IllegalStateException if values are missing @@ -96,7 +95,7 @@ public class IndexedDataList<E> implements DataList<E> { } /** - * Constructs a {@link IndexedDataList}. + * Constructs an IndexedDataList. * * @param index the index * @param values the values diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataMap.java index 25bd3d33c..949d2dd90 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/IndexedDataMap.java @@ -26,21 +26,20 @@ import java.util.Map; import java.util.Map.Entry; /** - * A {@link DataMap} that can hold a large number of variable size data elements. This data map is - * backed by an index and a buffer that can be either heap, off-heap, or memory mapped. + * A map that stores variable-size values using an index. Values are stored in an append-only log + * with indices for fast access. * - * @param <E> The type of the elements. + * @param <E> The type of values in the map */ public class IndexedDataMap<E> implements DataMap<Long, E> { private final Map<Long, Long> index; - private final AppendOnlyLog<E> values; /** - * Static factory method to create a new builder. + * Creates a new builder for an IndexedDataMap. * - * @param <E> the type of elements + * @param <E> the type of values * @return a new builder */ public static <E> Builder<E> builder() { @@ -48,9 +47,9 @@ public class IndexedDataMap<E> implements DataMap<Long, E> { } /** - * Builder for {@link IndexedDataMap}. + * Builder for IndexedDataMap. * - * @param <E> the type of elements + * @param <E> the type of values */ public static class Builder<E> { private Map<Long, Long> index; @@ -79,7 +78,7 @@ public class IndexedDataMap<E> implements DataMap<Long, E> { } /** - * Builds a new {@link IndexedDataMap}. + * Builds a new IndexedDataMap. * * @return a new IndexedDataMap * @throws IllegalStateException if values are missing @@ -98,7 +97,7 @@ public class IndexedDataMap<E> implements DataMap<Long, E> { } /** - * Constructs a {@link IndexedDataMap}. + * Constructs an IndexedDataMap. * * @param index the index * @param values the values diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataList.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataList.java index 34216e8fb..b60294e6b 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataList.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataList.java @@ -28,27 +28,22 @@ import org.apache.baremaps.data.memory.OffHeapMemory; import org.apache.baremaps.data.type.FixedSizeDataType; /** - * A {@link DataList} that can hold a large number of fixed-size memory-aligned data elements. This - * data list is backed by a memory that can be either heap, off-heap, or memory mapped. + * A list that stores fixed-size memory-aligned elements. Optimized for performance with bit-shift + * operations for memory addressing. * - * @param <E> The type of the elements. + * @param <E> The type of elements in the list */ public class MemoryAlignedDataList<E> implements DataList<E> { private final FixedSizeDataType<E> dataType; - private final Memory<?> memory; - private final int valueShift; - private final long segmentShift; - private final long segmentMask; - private AtomicLong size; /** - * Static factory method to create a new builder. + * Creates a new builder for a MemoryAlignedDataList. * * @param <E> the type of elements * @return a new builder @@ -58,7 +53,7 @@ public class MemoryAlignedDataList<E> implements DataList<E> { } /** - * Builder for {@link MemoryAlignedDataList}. + * Builder for MemoryAlignedDataList. * * @param <E> the type of elements */ @@ -89,7 +84,7 @@ public class MemoryAlignedDataList<E> implements DataList<E> { } /** - * Builds a new {@link MemoryAlignedDataList}. + * Builds a new MemoryAlignedDataList. * * @return a new MemoryAlignedDataList * @throws IllegalStateException if the data type is missing @@ -108,10 +103,12 @@ public class MemoryAlignedDataList<E> implements DataList<E> { } /** - * Constructs a {@link MemoryAlignedDataList}. + * Constructs a MemoryAlignedDataList. * * @param dataType the data type * @param memory the memory + * @throws DataCollectionException if memory and data type size requirements are not met + * @throws IllegalArgumentException if data type size is not a power of 2 */ private MemoryAlignedDataList(FixedSizeDataType<E> dataType, Memory<?> memory) { if (dataType.size() > memory.segmentSize()) { @@ -131,6 +128,12 @@ public class MemoryAlignedDataList<E> implements DataList<E> { this.size = new AtomicLong(0); } + /** + * Writes an element at the specified index. + * + * @param index the index + * @param value the element to write + */ private void write(long index, E value) { long position = index << valueShift; int segmentIndex = (int) (position >>> segmentShift); diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataMap.java index 9fdcb0ef0..1fbd9abab 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MemoryAlignedDataMap.java @@ -26,7 +26,8 @@ import org.apache.baremaps.data.memory.Memory; import org.apache.baremaps.data.type.FixedSizeDataType; /** - * A {@link DataMap} that can hold a large number of fixed-size memory-aligned data elements. + * A map that stores fixed-size memory-aligned elements with optimized memory addressing. + * Uses bit-shift operations for fast memory access. * * <p> * This code has been adapted from Planetiler (Apache license). @@ -46,9 +47,9 @@ public class MemoryAlignedDataMap<E> implements DataMap<Long, E> { private final long upperBoundary; /** - * Static factory method to create a new builder. + * Creates a new builder for a MemoryAlignedDataMap. * - * @param <E> the type of elements + * @param <E> the type of values * @return a new builder */ public static <E> Builder<E> builder() { @@ -56,9 +57,9 @@ public class MemoryAlignedDataMap<E> implements DataMap<Long, E> { } /** - * Builder for {@link MemoryAlignedDataMap}. + * Builder for MemoryAlignedDataMap. * - * @param <E> the type of elements + * @param <E> the type of values */ public static class Builder<E> { private FixedSizeDataType<E> dataType; @@ -87,7 +88,7 @@ public class MemoryAlignedDataMap<E> implements DataMap<Long, E> { } /** - * Builds a new {@link MemoryAlignedDataMap}. + * Builds a new MemoryAlignedDataMap. * * @return a new MemoryAlignedDataMap * @throws IllegalStateException if required parameters are missing @@ -105,10 +106,12 @@ public class MemoryAlignedDataMap<E> implements DataMap<Long, E> { } /** - * Constructs a {@link MemoryAlignedDataMap}. + * Constructs a MemoryAlignedDataMap. * * @param dataType the data type * @param memory the memory + * @throws DataCollectionException if memory and data type size requirements are not met + * @throws IllegalArgumentException if data type size is not a power of 2 */ private MemoryAlignedDataMap(FixedSizeDataType<E> dataType, Memory<?> memory) { if (dataType.size() > memory.segmentSize()) { @@ -129,6 +132,13 @@ public class MemoryAlignedDataMap<E> implements DataMap<Long, E> { : Long.MAX_VALUE >> (32 - segmentShift + valueShift); } + /** + * Checks if the key is within valid boundaries. + * + * @param key the key to check + * @throws NullPointerException if key is null + * @throws IndexOutOfBoundsException if key is outside valid range + */ private void checkBoundary(Long key) { Objects.requireNonNull(key, "Key couldn't be null"); if (key < 0 || key > upperBoundary) { diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicDataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicDataMap.java index a92455d1b..6d3621640 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicDataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicDataMap.java @@ -24,15 +24,11 @@ import org.apache.baremaps.data.type.PairDataType; import org.apache.baremaps.data.type.PairDataType.Pair; /** - * A {@link DataMap} that can hold a large number of variable-size data elements. The elements must - * be sorted by their key and inserted in a monotonic way. The elements cannot be removed or updated - * once inserted. + * A map that stores values in a monotonically increasing key order. Optimized for + * sequential insertions and binary search lookups with chunked indexing. * * <p> * This code has been adapted from Planetiler (Apache license). - * - * <p> - * Copyright (c) Planetiler. */ public class MonotonicDataMap<E> implements DataMap<Long, E> { @@ -43,7 +39,7 @@ public class MonotonicDataMap<E> implements DataMap<Long, E> { private long lastChunk = -1; /** - * Creates a builder for {@link MonotonicDataMap}. + * Creates a new builder for a MonotonicDataMap. * * @param <E> the type of values in the map * @return a new builder @@ -53,7 +49,7 @@ public class MonotonicDataMap<E> implements DataMap<Long, E> { } /** - * Builder for {@link MonotonicDataMap}. + * Builder for MonotonicDataMap. * * @param <E> the type of values in the map */ @@ -96,9 +92,10 @@ public class MonotonicDataMap<E> implements DataMap<Long, E> { } /** - * Builds a new {@link MonotonicDataMap}. + * Builds a new MonotonicDataMap. * - * @return a new map instance + * @return a new MonotonicDataMap + * @throws IllegalArgumentException if the values buffer is not provided */ public MonotonicDataMap<E> build() { if (values == null) { @@ -122,7 +119,7 @@ public class MonotonicDataMap<E> implements DataMap<Long, E> { } /** - * Constructs a {@link MonotonicDataMap}. + * Constructs a MonotonicDataMap. * * @param offsets the list of offsets * @param keys the list of keys diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicFixedSizeDataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicFixedSizeDataMap.java index cd3ccd199..a16b6f640 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicFixedSizeDataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicFixedSizeDataMap.java @@ -23,9 +23,8 @@ import java.util.Map.Entry; import org.apache.baremaps.data.type.LongDataType; /** - * A {@link DataMap} that can hold a large number of fixed-size data elements. The elements must be - * sorted by their key and inserted in a monotonic way. The elements cannot be removed or updated - * once inserted. + * A map that stores fixed-size values in monotonically increasing key order. + * Optimized for sequential insertions and fast binary search lookups. * * <p> * This code has been adapted from Planetiler (Apache license). diff --git a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicPairedDataMap.java b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicPairedDataMap.java index 8662b2df0..41fd57026 100644 --- a/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicPairedDataMap.java +++ b/baremaps-data/src/main/java/org/apache/baremaps/data/collection/MonotonicPairedDataMap.java @@ -26,9 +26,8 @@ import org.apache.baremaps.data.type.LongDataType; import org.apache.baremaps.data.type.PairDataType.Pair; /** - * A {@link DataMap} that can hold a large number of variable-size data elements. The elements must - * be sorted by their key and inserted in a monotonic way. The elements cannot be removed or updated - * once inserted. + * A map that stores values as key-value pairs in monotonically increasing key order. Optimized for + * sequential insertions and fast binary search lookups. * * <p> * This code has been adapted from Planetiler (Apache license). @@ -44,9 +43,9 @@ public class MonotonicPairedDataMap<E> implements DataMap<Long, E> { private long lastChunk = -1; /** - * Static factory method to create a new builder. + * Creates a new builder for a MonotonicPairedDataMap. * - * @param <E> the type of elements + * @param <E> the type of values * @return a new builder */ public static <E> Builder<E> builder() { @@ -54,9 +53,9 @@ public class MonotonicPairedDataMap<E> implements DataMap<Long, E> { } /** - * Builder for {@link MonotonicPairedDataMap}. + * Builder for MonotonicPairedDataMap. * - * @param <E> the type of elements + * @param <E> the type of values */ public static class Builder<E> { private DataList<Long> offsets; @@ -85,7 +84,7 @@ public class MonotonicPairedDataMap<E> implements DataMap<Long, E> { } /** - * Builds a new {@link MonotonicPairedDataMap}. + * Builds a new MonotonicPairedDataMap. * * @return a new MonotonicPairedDataMap * @throws IllegalStateException if values are missing @@ -106,7 +105,7 @@ public class MonotonicPairedDataMap<E> implements DataMap<Long, E> { } /** - * Private constructor for {@link MonotonicPairedDataMap}. + * Constructs a MonotonicPairedDataMap. * * @param offsets the list of offsets * @param values the buffer of values
