The Eclipse Collections Project
Clone or download
Eclipse Collections Bot
Latest commit c7713d1 Sep 19, 2018
Permalink
Failed to load latest commit information.
.idea IntelliJ code style settings to line-wrap long ternary statements. Sep 12, 2018
.mvn Add .mvn/maven.config with options --show-version and --errors. Jul 27, 2018
.settings Update Eclipse project files. Mar 22, 2016
acceptance-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
artwork Add Eclipse Collections logo. Aug 20, 2017
docs Sets links to live 9.2 version May 25, 2018
eclipse-collections-api Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
eclipse-collections-code-generator-maven-plugin Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
eclipse-collections-code-generator Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
eclipse-collections-forkjoin Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
eclipse-collections-testutils Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
eclipse-collections Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
jcstress-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
jmh-scala-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
jmh-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
junit-trait-runner Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
missing-dependency Sync IntelliJ project files for TeamCity. Aug 3, 2018
p2-feature Upgrade version of p2 feature to 10.0.0, added necessary dependencies… Sep 1, 2018
p2-repository Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
performance-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
scala-unit-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
serialization-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
site Minor enhancements for German site. Jun 12, 2018
test-coverage Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
unit-tests-java8 Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
unit-tests Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
.gitattributes Initial import. Dec 9, 2015
.gitignore Sync IntelliJ project files for TeamCity. Aug 3, 2018
.project Update Eclipse project files. Mar 22, 2016
.travis-command-ea-builds.sh Enable Java 12-EA build. Sep 1, 2018
.travis.yml Add Javadoc build. Sep 17, 2018
CONTRIBUTING.md Update Contributor License information with latest ECA. Sep 14, 2016
LICENSE-EDL-1.0.txt Initial import. Dec 9, 2015
LICENSE-EPL-1.0.txt Initial import. Dec 9, 2015
README.md Sets links to live 9.2 version May 25, 2018
RELEASE_NOTE_DRAFT.md Prepare for 10.0.0 release May 20, 2018
about.html Add about.html and license files for documentation within the release… Dec 24, 2015
checkstyle-configuration.xml Turn on additional CheckStyle rules and fix violations. Sep 12, 2018
checkstyle-suppressions.xml Fix broken CheckStyle build and static analysis violations. Jul 13, 2018
deploy.properties Initial import. Dec 9, 2015
eclipse-collections-parent.iml Sync IntelliJ project files for TeamCity. Aug 3, 2018
findbugs-exclude.xml Implement countBy and countBy with target as default methods on RichI… Jun 24, 2017
java.header Remove executable bit from files that are not executable Nov 17, 2016
pom-template Fix GitHub url in pom files. Dec 10, 2015
pom.xml Update version number to 10.0.0-SNAPSHOT. Sep 19, 2018
version.properties Remove executable bit from files that are not executable Nov 17, 2016

README.md

logo

Eclipse Collections is a collections framework for Java. It has optimized List, Set and Map implementations with a rich and fluent API. The library provides additional data structures not found in the JDK like Bags, Multimaps and BiMaps. The framework also provides primitive versions of Lists, Sets, Bags, Stacks and Maps with a rich and fluent API. There is support for both Mutable and Immutable versions of all containers in the library. The iteration protocol was inspired by the Smalltalk collection framework, and the collections are compatible with the Java Collection Framework types.

Eclipse Collections has been presented at various conferences and meetups including JavaOne, Java Day Tokyo, EclipseCon NA & Europe, GOTO Chicago, ECOOP (Curry On) and QCon New York.

The framework is actively being developed, with a growing number of contributors, at the Eclipse Foundation. The current roadmap for the framework is available here.

Learn Eclipse Collections

The Eclipse Collections Reference Guide is a great way to get an overview of the extensive features available in the framework.

Check out the Eclipse Collections Kata, a fun way to help you learn idiomatic Eclipse Collections usage. A kata is an exercise in martial arts. A code kata is an exercise in programming which helps hone your skills through practice and repetition. This particular kata is set up as a series of unit tests which fail. Your task is to make them pass, using Eclipse Collections.

Quick Example

Eclipse Collections puts iteration methods directly on the container types. Here's several code examples that demonstrate the simple and flexible style of programming with Eclipse Collections.

First, we will define a simple class named Person to hold the first and last names of three people.

public class Person
{
    private final String firstName;
    private final String lastName;

    public Person(String firstName, String lastName)
    {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public String getFirstName()
    {
        return this.firstName;
    }

    public String getLastName()
    {
        return this.lastName;
    }
}

Now we will setup three instances of the Person class in the person1, person2 and person3 variables.

Person person1 = new Person("Sally", "Smith");
Person person2 = new Person("Ted", "Watson");
Person person3 = new Person("Mary", "Williams");

Now that the three people are instantiated, we can store them in a MutableList using the Lists factory class. Then we will collect the last names of each person to a MutableList of String. As a final step we will assert the expected value of the last names as a comma separated string should be equal to "Smith, Watson, Williams".

MutableList<Person> people = Lists.mutable.with(person1, person2, person3);
MutableList<String> lastNames = people.collect(Person::getLastName);
Assert.assertEquals("Smith, Watson, Williams", lastNames.makeString());

The method reference in the example above can also be replaced with a lambda:

MutableList<String> lastNames = people.collect(person -> person.getLastName());

Eclipse Collections has support for both Mutable and Immutable collections, and the return types of methods are covariant. While the collect method on a MutableList returned a MutableList, the collect method on an ImmutableList will return an ImmutableList. Here we use the same Lists factory to create an ImmutableList.

ImmutableList<Person> people = Lists.immutable.with(person1, person2, person3);
ImmutableList<String> lastNames = people.collect(Person::getLastName);
Assert.assertEquals("Smith, Watson, Williams", lastNames.makeString());

Eclipse Collections has a lazy API as well, which is available by calling the method asLazy(). The method collect will now return a LazyIterable. The LazyIterable that is returned does not evaluate anything until the call to a terminal method is made. In this case, the call to makeString() will force the LazyIterable to collect the last names.

ImmutableList<Person> people = Lists.immutable.with(person1, person2, person3);
LazyIterable<String> lastNames = people.asLazy().collect(Person::getLastName);
Assert.assertEquals("Smith, Watson, Williams", lastNames.makeString());

The MutableCollections in Eclipse Collections also have the Stream API available in Java, since they extend their corresponding JDK types. In this case, a MutableList extends java.util.List. We use the stream() and map() methods to return a Stream of String. Then we call the terminal method collect on the Stream with the Collectors.joining() as a parameter to convert the MutableList of Person to their comma separated last names.

MutableList<Person> people = Lists.mutable.with(person1, person2, person3);
Stream<String> lastNames = people.stream().map(Person::getLastName);
Assert.assertEquals("Smith, Watson, Williams", lastNames.collect(Collectors.joining(", "));

Eclipse Collections 8.0 also introduced a new set of Collectors in the class Collectors2. The Collectors2.makeString() is equivalent to Collectors2.joining(", "), but does not require the object in the Stream to be a String.

MutableList<Person> people = Lists.mutable.with(person1, person2, person3);
Stream<String> lastNames = people.stream().map(Person::getLastName);
Assert.assertEquals("Smith, Watson, Williams", lastNames.collect(Collectors2.makeString());

There are also a set of Adapter classes which can be used to add the fluent Eclipse Collections protocols on top of JDK Collection types.

List<Person> people = Arrays.asList(person1, person2, person3);
MutableList<String> lastNames = ListAdapter.adapt(people).collect(Person::getLastName);
Assert.assertEquals("Smith, Watson, Williams", lastNames.makeString());

Why Eclipse Collections?

  • Improves readability and reduces duplication of iteration code (enforces DRY/OAOO principles)
  • Implements many high-level iteration patterns (select, reject, collect, inject into, etc.) on "humane" container interfaces which are extensions of the JDK interfaces
  • Provides a consistent mechanism for iterating over Collections, Arrays, Maps, and Strings
  • Provides replacements for ArrayList, HashSet, and HashMap optimized for performance and memory usage
  • Adds new containers including Bag, Interval, Multimap, BiMap, and immutable versions of all types
  • Adds primitive containers for Lists, Sets, Bags, Stacks and Maps for all primitive Java types (boolean, byte, char, short, int, float, long, double)
  • Supports Mutable, Immutable, Synchronized, Unmodifiable and MultiReader Collections
  • Supports eager evaluation with APIs directly on containers and lazy evaluation via a method called asLazy()
  • Encapsulates a lot of the structural complexity of parallel iteration in a parallel API and parallel utility classes
  • Provides adapters and optimized utility classes for iterating over JDK Collection types with a fluent and friendly API
  • Has been under active development since 2005 and is a mature library

License

Eclipse Collections is open sourced under the Eclipse Public License v1.0 and the Eclipse Distribution License v1.0.

How to Contribute

We welcome contributions!

We accept contributions via pull requests here in GitHub. Please see How To Contribute to get started.

Project Roadmap

https://github.com/eclipse/eclipse-collections/wiki/Roadmap

Acquiring Eclipse Collections

Maven

<dependency>
  <groupId>org.eclipse.collections</groupId>
  <artifactId>eclipse-collections-api</artifactId>
  <version>9.2.0</version>
</dependency>

<dependency>
  <groupId>org.eclipse.collections</groupId>
  <artifactId>eclipse-collections</artifactId>
  <version>9.2.0</version>
</dependency>

<dependency>
  <groupId>org.eclipse.collections</groupId>
  <artifactId>eclipse-collections-testutils</artifactId>
  <version>9.2.0</version>
  <scope>test</scope>
</dependency>

<dependency>
  <groupId>org.eclipse.collections</groupId>
  <artifactId>eclipse-collections-forkjoin</artifactId>
  <version>9.2.0</version>
</dependency>

Gradle

compile 'org.eclipse.collections:eclipse-collections-api:9.2.0'
compile 'org.eclipse.collections:eclipse-collections:9.2.0'
testCompile 'org.eclipse.collections:eclipse-collections-testutils:9.2.0'
compile 'org.eclipse.collections:eclipse-collections-forkjoin:9.2.0'

Ivy

<dependency org="org.eclipse.collections" name="eclipse-collections-api" rev="9.2.0" />
<dependency org="org.eclipse.collections" name="eclipse-collections" rev="9.2.0" />
<dependency org="org.eclipse.collections" name="eclipse-collections-testutils" rev="9.2.0" />
<dependency org="org.eclipse.collections" name="eclipse-collections-forkjoin" rev="9.2.0"/>

OSGi Bundle

Eclipse software repository location: http://download.eclipse.org/collections/9.2.0/repository

Additional information