Immutable Collections in Java using Sealed Types

Donald Raab
Oct 14 · 5 min read

How to define contractual, structural, and verifiable immutable Java collections.

Image for post
Image for post
Designing Immutable Collection using Sealed Types in JDK 15

Introducing Sealed Types

JDK 15 was released on September 15, 2020. JEP 360 Sealed Types was included as a preview feature in this release. Sealed Types is part of Project Amber. Sealed classes or interfaces can be used to restrict the interfaces or classes that are allowed to extend them. This is accomplished by using the sealed, non-sealed, and permits modifiers.

What is contractual immutability?

An interface or class is contractually immutable if the available public methods do not allow an instance to be mutated after it is constructed. A contractually immutable collection should not expose methods like add, addAll, remove, removeAll, clear and a mutable Iterator . These methods are available on the Collection, List and Set types in Java. Immutable collections that implement these interfaces are not contractually immutable.

What is structural immutability?

An object is structurally immutable if all of its data members are private, final, and cannot be modified after the object is constructed. String is a great example of a class in Java that is structurally immutable. Once a String is constructed, it cannot be changed. Immutable objects like String sometimes have mutable counterparts like StringBuilder.

What is verifiable immutability?

A class or interface is verifiably immutable if all of the implementations are contractually and structurally immutable, and are restricted to a specific set of classes that can be verified. This is a capability that can now be more easily achieved via Sealed Types in JDK 15. With Sealed Types a developer can restrict the implementations of interfaces and classes to a specified set of types.

A Perfect Use Case for Sealed Types in Java

Immutable collection implementations for Java are available in the Java Collections Framework (since JDK 9), Google Guava and Eclipse Collections. None of the immutable collection alternatives provide the combination of structural, contractual and verifiable immutability today.

There are structurally immutable collections available in the Java Collection Framework via List.of(), Set.of(), Map.of(). The JDK immutable collections are not contractually immutable, because they implement the mutable List, Set, Map interfaces.

Guava has collection types that are structurally immutable, but not contractually immutable. The immutable collections in Guava implement the mutable JDK interfaces — List, Set, Map. Guava restricts the implementations of the immutable collection types by using abstract classes with package private constructors, which require all implementations to be in the same package. This restriction is a novel design approach and a key component of verifiable immutability, but is still lacking contractual immutability.

Eclipse Collections has collection types that are both contractually and structurally immutable. Unfortunately, there is no way in Java 8 to restrict the implementations of interfaces like ImmutableCollection, ImmutableList, ImmutableSet so that verifiable immutability can be provided. It is possible to implement the ImmutableCollection interface and its subtypes outside of Eclipse Collections because they are public interfaces. Theoretically, a “bad actor” may implement the ImmutableCollection interface and pass a mutable implementation to a method call expecting an ImmutableCollection. In practice, it is doubtful that this would be an issue, but the potential does exist.

The Sealed Types preview in JDK 15 gives developers the capability to finally provide the trifecta of contractual, structural and verifiable immutability in a collections framework. Using the Sealed Types preview feature, we can restrict the implementations of an ImmutableCollection interface using the sealed and permits modifiers.

Image for post
Image for post

Similarly, we can restrict the implementations of ImmutableList.

Image for post
Image for post

The ImmutableEmptyList implementation of ImmutableList is then declared as final.

Image for post
Image for post

Experimenting with Sealed Types in JDK 15 has been interesting and encouraging. I wish this feature was available a decade ago when we first defined the ImmutableCollection hierarchy in Eclipse Collections. I’ve been able to extend the design ideas that we implemented in Eclipse Collections years ago with a feature that provides a more restrictive modeling capability.

The source code for an experimental implementation of a collections framework can be found in the Deck of Cards Kata repo. The Deck of Cards Kata can be taken to become familiar with multiple collections frameworks including the latest versions of the Java Collections + Streams framework, Apache Commons Collections, Google Guava and Eclipse Collections.

The custom collections framework interfaces and implementations can be browsed online here. The following class diagram shows the interfaces in the framework, including the immutable collection interfaces that leverage Sealed Types.

Image for post
Image for post
A Custom Collections framework in the Deck of Cards Kata

The experimental collections framework in the kata has been evolving to use Project Amber features as they become available as preview features in the JDK. The kata was upgraded to JDK 15 the day it was released. The framework now uses the following features from Project Amber:

In addition, default methods and static interface methods are used extensively to build the rich interfaces in the framework.

A vision for the future of Java Collections

The custom collection framework was initially developed to explore and demonstrate what it would be like to have eager methods directly on mutable collection interfaces using API names similar to Java Streams.

The intent was to use the latest features available in the most current releases of Java where they were proved useful. The latest evolution shows what is possible by leveraging Sealed Types to implement immutable collection types. I’m quite encouraged by the results of the feature so far. I hope that this use case can be used and discussed as an example of the practical applicability of the Sealed Types feature.

The following blogs explain the evolution of the custom collections framework design over the past six months.

I hope you found this blog useful. Check out the source code and give the Deck of Cards kata and other code katas included in the repo a try.

Enjoy!

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.

Javarevisited

Medium’s largest Java publication, followed by 7300+ 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