Improving the symmetry of converter methods in Eclipse Collections

Donald Raab
Feb 14 · 4 min read

Consistency, clarity, and convenience of APIs driven by symmetry

Image for post
Image for post
A window to San Francisco Bay

A dedication to API Symmetry

We have driven the evolution of the APIs in Eclipse Collections by responding to and meeting the needs of real use cases encountered in applications in Financial Services and other industries served by developers working in the open source community. We use symmetry to guide the design and implementation of Eclipse Collections. Our collective experience has shown us that symmetry is a good guide to improving the design of our APIs.

Mutable Converter Methods

We have had primarily mutable converter methods in Eclipse Collections since 1.0 of the product.

Image for post
Image for post
Mostly mutable converter methods on RichIterable (toString is the one immutable exception)

In addition to the mutable converter methods, we have a converter method named toImmutable which can be used to convert any mutable collection type to its immutable counterpart.

Let’s look at the following example from the Deck of Cards Kata:

private ImmutableList<Card> cards;
private ImmutableListMultimap<Suit, Card> cardsBySuit;
public EclipseCollectionsDeckOfCardsAsList()
{
this.cards = Card.lazyCards().toList().toImmutable();
this.cardsBySuit = this.cards.groupBy(Card::suit);
}

In this example, we need to create an ImmutableList<Card> from a LazyIterable<Card>, which is the cartesian product of Rank and Suit. We first call Card.lazyCards which returns a LazyIterable<Card>. Then we call toList which returns a MutableList<Card> and finally we call toImmutable which returns an ImmutableList<Card>.

For a long time, I have found this two step process of converting from one type to an immutable version of another type in Eclipse Collections a minor but continual annoyance. I’ve also had to explain to developers who use Eclipse Collections that there is no equivalent methods name toImmutableList, toImmutableSet, toImmutableBag, etc.

That will now change in Eclipse Collections 11.0. We will now be able to write the following code.

public EclipseCollectionsDeckOfCardsAsImmutableList()
{
this.cards = Card.lazyCards().toImmutableList();
this.cardsBySuit = this.cards.groupBy(Card::suit);
}

In Eclipse Collections 11.0, we will have toImmutableList, toImmutableSet and toImmutableBag on RichIterable. This is only the beginning of the journey to better symmetry.

Visualizing the Symmetry of Converter Methods

Here is what the Eclipse Collections converter method API will look like in the future.

Image for post
Image for post
Future Symmetry of the Converter Method APIs

So far I have added toImmutableList, toImmutableSet and toImmutableBag to the RichIterable interface. The picture above shows us a clear path that we have to follow on the toImmutable side to improve the symmetry of the converter method APIs.

Walking the Walk

I like to say that symmetry is like gravity. When I see missing or dissimilar patterns, I feel the weight of symmetry. It is work that has yet to be done.

This was a quote from my first Medium blog titled Symmetric Sympathy. While it may not be practical to have perfect symmetry in an API as rich and complete as Eclipse Collections, we can continue to improve when we see a lack of clarity, consistency and convenience. This is walking the walk. It is important to meet the needs and expectations of the Eclipse Collections user community. I have seen developers try to call toImmutableList and toImmutableSet on types in Eclipse Collections and find it confusing that there is no equivalent of the to(Mutable) methods for Immutable types. Now their expectations will be met by the APIs they have been looking for.

Stay tuned, the symmetry is continually improving.

Help Wanted

If you’d like to help us on this journey of improvement, please join our open source community of contributors. The following is a great blog from a developer who decided to walk the walk and make his first open-source contributions to Eclipse Collections.

This blog is a great chronicle of one developer’s journey to becoming an open-source contributor. It may be an inspiration and reference to other developers as they look to begin or continue their own journeys.

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.

Other Java Articles you may like

Javarevisited

Medium’s largest Java publication, followed by 9300+ programmers. Follow to join our community.

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.

Javarevisited

A humble place to learn Java and Programming better.

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.

Javarevisited

A humble place to learn Java and Programming better.

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