Visualizing Eclipse Collections after Twenty Years of Development

It’s hard to see the forest when you keep walking among the trees.

This is how I visualize Eclipse Collections at a high level

This year is the 20th year that I have been working on Eclipse Collections. To kick off the official 20th anniversary celebration in a technical blog, I wanted to create a fresh visualization of Eclipse Collections features to get new developers acquainted with this amazing library.

In a code base with many packages, many types, and over one million lines of code (including test code), it can be easy to get lost browsing while looking through files. There is an organized package structure to Eclipse Collections, but if you are new to the library, it may not be obvious where to get started. I’m leaving this mind map here, with some useful links to help folks find the things they might be looking for.

This blog may be the “Just getting started” guide some folks are looking for as they begin their journey of discovery. Eclipse Collections contains everything I ever wanted in a collections library for Java. I hope Eclipse Collections will be the same for many of you. My intention in writing this blog is for it to be a good reference for using the library in your development adventures. I plan to refer to it myself on my own continuing adventures over the next 5… 10… 15… maybe 20 years.

Good luck and enjoy your journey!

Interfaces

If you want to find the interfaces, you need to look at the eclipse-collections-api module. In this module you will find most of the parent interfaces, like RichIterable, PrimitiveIterable, and ParallelIterable. Multimap and PartitionIterable are located in two different packages. Eclipse Collections had a design goal of cleanly separating interface from implementation. We want developers to refer only to interfaces whenever possible. This module contains primarily interfaces. The one exception to this are collection factory classes, which are loaded with implementations dynamically.

In order to understand the symmetry of the triad of interfaces, which include an Iterable, Mutable, and Immutable version for each type (e.g. ListIterable, MutableList, ImmutableList), I recommend reading the following blog.

Rich, Lazy, Mutable, and Immutable Interfaces in Eclipse Collections

There is only one LazyIterable interface. LazyIterable is not a parent interface, as it extends RichIterable. LazyIterable substitutes co-variant overrides for any methods that should be lazy and return a LazyIterable. Any collection type, whether iterable, mutable or immutable can create a lazy view of itself by calling asLazy(), which will return a LazyIterable.

Data Structures

The data structures for Eclipse Collections are split between interfaces and implementation. The interfaces are located at the module and links I shared above. The implementations are located in the eclipse-collections module. The types you are probably most interested are the implementations of List, Set, Map, and Bag. The Mutable implementations of these types in Eclipse Collections are named FastList, UnifiedSet, UnifiedMap and HashBag. Most of the time you will never see these names in code, assuming you are using the interfaces MutableList, MutableSet, MutableMap, and MutableBag and create the collections using the Lists, Sets, Maps, and Bags factories.

Container Types

There are Object and primitive containers in Eclipse Collections. For Map types, there are Object/Object, primitive/primitive, Object/primitive, and primitive/Object combinations. There are also some thread-safe container types in Eclipse Collections including both concurrent and MultiReader containers.

The best way to learn about the specialized Data Structures and Container Types in Eclipse Collections is to check out the following blog series.

Blog Series: The missing Java data structures no one ever told you about

Algorithms

Eclipse Collections supports eager and lazy behaviors, as well as serial and parallel evaluation. The best way to understand the difference between eager and lazy behaviors is to read the following blog. You can also learn how the library evolved support from eager, to fused, to lazy over time.

From Eager to Fused to Lazy

The above blog only covers serial examples. If you would like to read more about the parallel capabilities in Eclipse Collections, the following blog is a great place to start.

The unparalleled design of Eclipse Collections

Java is missing a feature that I remember fondly from my days as a Smalltalk developer. The missing feature is a code organization tool known as Method Categories. Method categories allow you to group methods together in a class. The following are the categories I would use in Eclipse Collections types if a method categorization feature was available in Java.

✅ Enumerating
✅ Filtering
✅ Transforming
✅ Finding
✅ Testing
✅ Grouping
✅ Aggregating
✅ Converting
✅ Math

The following blog covers some of the features in the categories above. There are over 100 methods on the RichIterable parent interface, and even more in subtypes. Most of the methods fit in one of these categories.

Getting Started with Eclipse Collections — Part 4

Factories

Eclipse Collections includes factories for Mutable, Immutable, MultiReader and other more specialized types. The factory classes in Eclipse Collections are named by taking a type name (e.g., List) and pluralizing it (e.g. Lists). The following blogs will teach you everything you ever wanted to know about the collection factories in Eclipse Collections.

As a matter of Factory — Part 1 (Mutable)

As a matter of Factory — Part 2 (Immutable)

As a matter of Factory — Part 3 (Method Chaining)

Twenty Years! Woo hoo!

In 2004, I didn’t think I would ever contribute anything to open source. I certainly didn’t think I would create something that would be open sourced from Goldman Sachs and used and contributed to by so many developers and projects. Here I am in 2024, celebrating 20 years of using and working on this amazing library. Crazy!

I think all that is left is to tell you how to download the library in your own projects. Of course, there is a blog for that.

Getting Started with Eclipse Collections — Part 1

Thank you for reading this blog, and for spending your valuable time learning some things about Eclipse Collections. I hope the library will be as useful and inspiring to you as it has been to me. If you find it useful and would like to contribute, we always welcome new contributors. If you don’t have a code contribution, but would like to advocate for and help others discover cool features in the library, then write a blog or an article. I keep a running list of articles about Eclipse Collections updated on the GitHub wiki linked below.

Articles

Enjoy!

I am the creator of and committer for the Eclipse Collections OSS project, which is managed at the Eclipse Foundation. Eclipse Collections is open for contributions.