Visualizing Eclipse Collections

Published in

Oracle Developers

5 min readJun 16, 2018

A visual overview of the API, Interfaces, Factories, Static Utility and Adapters in Eclipse Collections using mind maps.

A picture is worth a thousand words

I’m not sure how many words a mind map is worth, but they are useful for information chunking. Eclipse Collections is a very feature rich library. The mind maps help organize and group concepts and they help convey a sense of the symmetry in Eclipse Collections.

Symmetric Sympathy

A High-level view of the Eclipse Collections Library

RichIterable API

The RichIterable API is the set of common methods shared between all of the container classes in Eclipse Collections. Some methods have overloaded forms which take additional parameters. In the picture below I have grouped the unique set of methods by the kind of functionality they provide.

API by Example

Below are links to several blogs covering various methods available on RichIterable.

Filtering (Partitioning)
Transforming (Collect / FlatCollect)
Short-circuiting
Counting
Filter / Map / Reduce
Eclipse Collections API compared to Stream API

RichIterable Interface Hiearchy

RichIterable is the base type for most container types in Eclipse Collections. Even object valued Map types extend RichIterable in Eclipse Collections. A Map of type K (key) and V (value), will be an extension of RichIterable of V (value). This provides a rich set of behaviors to Map types for their values. You can still iterate over keys, and keys and values together, and there are separate methods for this purpose.

RichIterable Interface Hierarchy — Green Star=Mutable, Red Circle=Immutable

PrimitiveIterable Interface Hierarchy

Eclipse Collections provides container support for all eight Java primitives. There is a base interface with common behavior named PrimitiveIterable.

The following diagram shows the IntIterable branch from the diagram above. There are seven other similar branches.

IntIterable Interface Hierarchy — Green Star=Mutable, Red Circle=Immutable

The interface hierarchy for each primitive type is pretty much the same as IntIterable.

Factories

If you want to create a collection in Eclipse Collections, you have a few options available. One option is to use a constructor or static factory method on the concrete mutable type that you want to create. This requires you to know the name of the concrete mutable types (e.g. FastList, UnifiedSet or UnifiedMap). This option does not exist for immutable types however. The most convenient, consistent and symmetric option if you are going to create both mutable and immutable containers is to use one of the factory classes provided. A factory class follows the pattern of using the type name plus an s, to make it plural. So if you want a mutable or immutable List, you would use the Lists class, and then specify whether you want the mutable or immutable factory for that class.

Factory Classes available in Eclipse Collections for Object Containers

There are separate factory classes for primitive containers. Prefix the primitive type in front of the container type to find the right primitive factory class.

Mutable Factory Examples

MutableList<T> list = Lists.mutable.empty();
MutableSet<T> set = Sets.mutable.empty();
MutableSortedSet<T> sortedSet = SortedSets.mutable.empty();
MutableMap<K, V> map = Maps.mutable.empty();
MutableSortedMap<K, V> sortedMap = SortedMaps.mutable.empty();
MutableStack<T> stack = Stacks.mutable.empty();
MutableBag<T> bag = Bags.mutable.empty();
MutableSortedBag<T> sortedBag = SortedBags.mutable.empty();
MutableBiMap<K, V> biMap = BiMaps.mutable.empty();

Immutable Factory Examples

ImmutableList<T> list = Lists.immutable.empty();
ImmutableSet<T> set = Sets.immutable.empty();
ImmutableSortedSet<T> sortedSet = SortedSets.immutable.empty();
ImmutableMap<K, V> map = Maps.immutable.empty();
ImmutableSortedMap<K, V> sortedMap = SortedMaps.immutable.empty();
ImmutableStack<T> stack = Stacks.immutable.empty();
ImmutableBag<T> bag = Bags.immutable.empty();
ImmutableSortedBag<T> sortedBag = SortedBags.immutable.empty();
ImmutableBiMap<K, V> biMap = BiMaps.immutable.empty();

Static Utility Classes

In the early days of Eclipse Collections development, everything was accomplished through static utility classes. We added our own interface types later on. Over time Eclipse Collections has accumulated quite a few static utility classes that serve various purposes. Static utility classes are useful when you want to use Eclipse Collections APIs with types that extend the JDK Collection interfaces like Iterable, Collection, List, RandomAccess and Map.

Static Utility Examples

Assert.assertTrue(
        Iterate.anySatisfy(
                Collections.singleton("1"),
                "1"::equals));Assert.assertTrue(
        ListIterate.anySatisfy(
                Collections.singletonList("1"),
                Predicates.equal("1")));Assert.assertTrue(
        MapIterate.anySatisfy(
                Collections.singletonMap(1, "1"),
                Predicates.notEqual("2")));String[] strings = {"1", "2", "3"};
Assert.assertTrue(
        ArrayIterate.anySatisfy(strings, "1"::equals));
Assert.assertTrue(
        ArrayIterate.contains(strings, "1"));

Adapters

There are adapters that extend the Eclipse Collections API to JDK types.

Creating an adapter

MutableList<String> list = 
        Lists.adapt(new ArrayList<>());
MutableSet<String> set = 
        Sets.adapt(new HashSet<>());
MutableMap<String, String> map = 
        Maps.adapt(new HashMap<>());
MutableList<String> array = 
        ArrayAdapter.adapt("1", "2", "3");
CharAdapter chars = 
        Strings.asChars("Hello Chars!");
CodePointAdapter codePoints = 
        Strings.asCodePoints("Hello CodePoints!");
LazyIterable<String> lazy = 
        LazyIterate.adapt(new CopyOnWriteArrayList<>());

Additional Types

There are more types in Eclipse Collections like Multimap. Multimap will be covered in a separate blog. Multimap is one of the types today, along with ParallelIterable, that does not extend RichIterable directly.

Links

I am a Project Lead and Committer for the Eclipse Collections OSS project at the Eclipse Foundation. Eclipse Collections is open for contributions. If you like the library, you can let us know by starring it on GitHub.