Visualizing Eclipse Collections

Donald Raab
Jun 16, 2018 · 5 min read

A visual overview of the APIs, 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 APIs share 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.

RichIterable API

API by Example

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

  1. Filtering (Partitioning)
  2. Transforming (Collect / FlatCollect)
  3. Short-circuiting
  4. Counting
  5. Filter / Map / Reduce
  6. 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 an 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.

PrimitiveIterable Interface Hierarchy

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 beginning 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.

A collection of useful static utility classes

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 provide the Eclipse Collections APIs to JDK types.

Adapters for 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 Multimaps. These will be covered in a separate blog. Multimap is one of the types today, along with ParallelIterable, that does not extend RichIterable directly.

Links

  1. Eclipse Collections Reference Guide
  2. Eclipse Collections Katas
  3. API Design of Eclipse Collections
  4. Refactoring to Eclipse Collections
  5. UnifiedMap, UnifiedSet and Bag Explained

Eclipse Collections is open for contributions. If you like the library, you can let us know by starring it on GitHub.

Oracle Developers

Aggregation of articles from Oracle engineers, Groundbreaker Ambassadors, Oracle ACEs, and Java Champions on all things Oracle technology. The views expressed are those of the authors and not necessarily of Oracle.

Donald Raab

Written by

Java Champion. Creator of the Eclipse Collections OSS Java library (http://www.eclipse.org/collections/). Inspired by Smalltalk. Opinions are my own.

Oracle Developers

Aggregation of articles from Oracle engineers, Groundbreaker Ambassadors, Oracle ACEs, and Java Champions on all things Oracle technology. The views expressed are those of the authors and not necessarily of Oracle.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store