Kolektoj — Yet Another Java Collections Framework

“Kolektoj” is the Esperanto word for “collections”.

The aim of this project is to provide a clean Java collections framework.

Design Principles
Collection Properties
Overview
Comparison with the Java Platform Collections Framework
- JDK 21 Interfaces
- JDK 21 Classes
Getting Started
Projects Using Kolektoj

Design Principles

Collections come in different forms with different properties, and it should be possible for a developer to pick exactly the set of properties he needs for his software to do the job.
Collection properties that don't have an influence on the API should be treated as attributes. This minimizes the number of interfaces in the framework.
Methods should be declared at the hierarchy level where they start to make sense, and never higher than that.
Behavioural specializations are not part of this framework. Examples of behavioural specializations are queues and stacks.
Properties not specified by the developer may exhibit some default behaviour, but there is no requirement that the behaviour governed by an unspecified property is consistent within an implementation, or even within an instance of an implementation within its lifetime.

Collection Properties

The following collection properties have been identified:

Order: whether the elements in the collection have an order or not.
Uniqueness: whether the collection can contain the same element more than once or not.
Null: whether null is allowed as an element of the collection or not.
Modifiability: whether the content of the collection can be modified or not, and if it can be modified, whether it's thread-safe or not.

Overview

The table below shows the various implementations of the interfaces using different backing mechanisms.

Interface	Array	Hash	Linked List	Sorted Tree
Collection	ArrayCollection	HashCollection	LinkedListCollection	—¹
ModifiableCollection	ModifiableArrayCollection	ModifiableHashCollection	ModifiableLinkedListCollection	—¹
OrderedCollection	OrderedArrayCollection	—²	OrderedLinkedListCollection	—¹
ModifiableOrderedCollection	ModifiableOrderedArrayCollection	—²	ModifiableOrderedLinkedListCollection	—²
SortedCollection	SortedArrayCollection	—²		SortedTreeCollection
ModifiableSortedCollection	ModifiableSortedArrayCollection	—²		ModifiableSortedTreeCollection
Map		HashMap		—¹
UpdatableMap		UpdatableHashMap		—¹
ModifiableMap		ModifiableHashMap		—¹
SortedMap	SortedArrayMap	—²		SortedTreeMap
UpdatableSortedMap	UpdatableSortedArrayMap	—²		UpdatableSortedTreeMap
ModifiableSortedMap	ModifiableSortedArrayMap	—²		ModifiableSortedTreeMap

¹ The implementation of this interface using a sorted tree would automatically provide sorting functionality.

² The nature of this backing mechanism fundamentally conflicts with the functionality of this interface.

Comparison with the Java Platform Collections Framework

The comparison below is based on the Java Platform Collections Framework Overview for JDK 21.

JDK 21 Interfaces

The Java Platform Collections Framework contains the following interfaces in JDK 21:

java.util.Collection<E>
java.util.Deque
java.util.List<E>
java.util.Map<E>
java.util.NavigableMap
java.util.NavigableSet
java.util.Queue
java.util.Set<E>
java.util.SortedMap
java.util.SortedSet
java.util.concurrent.BlockingDeque
java.util.concurrent.BlockingQueue
java.util.concurrent.ConcurrentMap
java.util.concurrent.ConcurrentNavigableMap
java.util.concurrent.TransferQueue

java.util.Collection<E>

The table below shows how the methods defined on the java.util.Collection<E> interface map to Kolektoj methods.

JDK 21 Method	Kolektoj Class	Kolektoj Method
boolean add(E e)	ModifiableCollection<E>	boolean add(E element)
boolean addAll(Collection<? extends E> c)	ModifiableCollection<E>	boolean addAll(Collection<? extends E> collection)
void clear()	ModifiableCollection<E>	void clear()
boolean contains(Object o)	Collection<E>	boolean contains(E element)
boolean containsAll(Collection<?> c)	Collection<E>	boolean containsAll(Collection<?> c)
boolean isEmpty()	Collection<E>	default boolean isEmpty()
Iterator<E> iterator()	Collection<E>	Iterator<E> iterator()
default Stream<E> parallelStream()
boolean remove(Object o)	ModifiableCollection<E>	boolean remove(E element)
boolean removeAll(Collection<?> c)	ModifiableCollection<E>	boolean removeAll(Collection<? extends E> collection)
default boolean removeIf(Predicate<? super E> filter)	ModifiableCollection<E>	boolean removeIf(Predicate<? super E> predicate)
boolean retainAll(Collection<?> c)	ModifiableCollection<E>	boolean retainAll(Collection<? extends E> collection)
int size()	Collection<E>	int size()
default Spliterator<E> spliterator()	Collection<E>	Spliterator<E> spliterator()
default Stream<E> stream()	Collection<E>	default Stream<E> stream()
Object[] toArray()	Collection<E>	Object[] toArray()
default <T> T[] toArray(IntFunction<T[]> generator)
<T> T[] toArray(T[] a)	Collection<E>	E[] toArray(E[] array)

java.util.List<E>

The table below shows how the methods defined on the java.util.List<E> interface map to Kolektoj methods.

JDK 21 Method	Kolektoj Class	Kolektoj Method
boolean add(int index, E element)	ModifiableOrderedCollection<E>	boolean addAt(int index, E element)
boolean addAll(int index, Collection<? extends E> c)	ModifiableOrderedCollection<E>	boolean addAllAt(int index, Collection<? extends E> collection)
default void addFirst(E e)
default void addLast(E e)
static <E> List<E> copyOf(Collection<? extends E> coll)
E get(int index)	OrderedCollection<E>	E getAt(int index)
default E getFirst()
default E getLast()
int indexOf(Object o)
int lastIndexOf(Object o)
ListIterator<E> listIterator()
ListIterator<E> listIterator(int index)
static <E> List<E> of(…)
E remove(int index)	ModifiableOrderedCollection<E>	E removeAt(int index)
default E removeFirst()
default E removeLast()
default void replaceAll(UnaryOperator<E> operator)
default List reversed()
E set(int index, E element)
default void sort(Comparator<? super E> c)
List<E> subList(int fromIndex, int toIndex)

java.util.Set<E>

The java.util.Set<E> interface extends the java.util.Collection<E> interface directly, but does not add any new methods to it.

java.util.Map<E>

The table below shows how the methods defined on the java.util.Map<E> interface map to Kolektoj methods.

JDK 21 Method	Kolektoj Class	Kolektoj Method
void clear()	ModifiableMap<E>	void clear()
default V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
default V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
default V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
boolean containsKey(Object key)	Map<E>	boolean containsKey(K key)
boolean containsValue(Object value)	Map<E>	boolean containsValue(V value)
static <K,V> Map<K,V> copyOf(Map<? extends K,? extends V> map)
static <K,V> Map.Entry<K,V> entry(K k, V v)
Set<Map.Entry<K,V>> entrySet()	Map<E>	extends Collection<Entry<K, V>>
boolean equals(Object o)
default void forEach(BiConsumer<? super K,? super V> action)
V get(Object key)	Map<E>	V get(K key)
default V getOrDefault(Object key, V defaultValue)	Map<E>	default V get(K key, V defaultValue)
int hashCode()
boolean isEmpty()	Collection<E>	default boolean isEmpty()
Set<K> keySet()	Map<E>	Collection getKeys()
default V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
static <K,V> Map<K,V> of(…)
static <K,V> Map<K,V> ofEntries(Map.Entry<? extends K,? extends V>... entries)
V put(K key, V value)	ModifiableMap<E>	default V put(K key, V value)
void putAll(Map<? extends K,? extends V> m)	ModifiableMap<E>	default void putAll(Map<? extends K, ? extends V> map)
default V putIfAbsent(K key, V value)
V remove(Object key)	ModifiableMap<E>	V remove(K key)
default boolean remove(Object key, Object value)
default V replace(K key, V value)	ModifiableMap<E>	V update(K key, V value)
default boolean replace(K key, V oldValue, V newValue)
default void replaceAll(BiFunction<? super K,? super V,? extends V> function)
int size()	Collection<E>	int size()
Collection<V> values()	Map<E>	Collection getValues()

JDK 21 Classes

The Java Platform Collections Framework contains the following classes in JDK 21:

AbstractCollection
AbstractList
AbstractMap
AbstractSequentialList
AbstractSet
ArrayBlockingQueue
ArrayDeque
ArrayList
BlockingDeque
BlockingQueue
ConcurrentHashMap
ConcurrentMap
ConcurrentNavigableMap
ConcurrentSkipListMap
ConcurrentSkipListSet
CopyOnWriteArrayList
CopyOnWriteArraySet
DelayQueue
HashMap
HashSet
LinkedBlockingDeque
LinkedBlockingQueue
LinkedHashMap
LinkedHashSet
LinkedList
LinkedTransferQueue
PriorityBlockingQueue
SynchronousQueue
TransferQueue
TreeMap
TreeSet

Getting Started

First of all, you need to obtain a copy of the source code, complile it and install it locally. Run the following commands to do this:

git clone git@github.com:filipvanlaenen/kolektoj.git
cd kolektoj
mvn clean install

Note: If requested by enough people, this library can be deployed to a central Maven repository (Issue #1).

If everything works well, you'll be able to use the Kolektoj library in another Java project by adding the following dependency in the project's POM file:

  <dependency>
    <groupId>net.filipvanlaenen</groupId>
    <artifactId>kolektoj</artifactId>
    <version>1.0-SNAPSHOT</version>
  </dependency>

Be sure to update to the appropriate version number.

Projects Using Kolektoj

The following projects use Kolektoj:

filipvanlaenen / kolektoj

readme