eclipse / eclipse-collections Goto Github PK

Eclipse Collections is a collections framework for Java with optimized data structures and a rich, functional and fluent API.

Home Page: http://www.eclipse.org/collections

Java 96.36% Scala 1.03% HTML 2.61%

java eclipse-collections java-collections collections data-structures functional object-oriented immutable-collections primitive-collections

eclipse-collections's Introduction

English | Deutsch | Ελληνικά | Español | 中文 | Français | 日本語 | Norsk (bokmål) | Português-Brasil | Русский | हिंदी | Srpski (latinica)

Eclipse Collections is a comprehensive collections library for Java. The library enables productivity and performance by delivering an expressive and efficient set of APIs and types. The iteration protocol was inspired by the Smalltalk collection framework, and the collections are compatible with the Java Collection Framework types.

Eclipse Collections is compatible with Java 8+. Eclipse Collections is a part of the OpenJDK Quality Outreach program, and it is validated for different versions of the OpenJDK.

Why Eclipse Collections?

Productivity
- Supports eager, lazy, serial and parallel iteration patterns
- Rich, functional, and fluent APIs with eager methods available directly on collection types
- Provides List, Set, Bag, Stack, Map, Multimap, BiMap, Interval object container types
- Readable, Mutable, and Immutable interfaces for each collection type with covariant return types
  - Blog: Rich, Lazy, Mutable, Immutable interfaces in Eclipse collections
- Mutable and Immutable Collection Factories
  - Blog series: As a matter of Factory
- Adapters and Utility classes for JCF Types
  - Blog: Iterate over any Iterable in Java
Performance
- Memory Efficient Containers
  - Blog: UnifiedMap: How it works?
  - Blog: UnifiedSet - The Memory Saver
- Optimized Eager, Lazy and Parallel APIs
  - Blog: The unparalleled design of Eclipse Collections
- Primitive Collections for all primitive types
  - Provides List, Set, Bag, Stack, Map, Interval primitive container types
Maturity
- Eclipse Collections has been actively developed and used in financial services applications since 2004
- Eclipse Collections existed for a decade before concise lambda expressions were added in Java 8
  - Blog: My ten-year quest for concise lambda expressions in Java

Learn Eclipse Collections

Blog Series: Getting Started with Eclipse Collections
Blog Series: The missing Java data structures no one ever told you about
Blog: Java has Streams. Do we need third-party collections?
Some Quick Code Examples
Eclipse Collections Katas, a fun way to help you learn idiomatic Eclipse Collections usage.
- Start Here - Pet Kata
- Continue Here - Company Kata
Eclipse Collections Reference Guide and Javadoc
Serializing Eclipse Collections with Jackson
Articles and Blogs
Some OSS projects that use Eclipse Collections
- Neo4J, FINOS Legend, Reladomo, Liftwizard, Exchange Core, Dataframe EC, MapDB, Code Browser, Obevo, BNY Mellon Code Katas, Eclipse Nebula NatTable, Eclipse VIATRA, Jackson Datatypes Collections
- If you work on an open source project that uses Eclipse Collections, let us know!

Eclipse Collections and JDK Compatibility Matrix

EC	JDK 5 - 7	JDK 8	JDK 9 - 10	JDK 11 - 14	JDK 15 - 21
7.x.x	✓	✓
8.x.x		✓
9.x.x		✓	✓	✓
10.x.x		✓	✓	✓
10.4.0		✓	✓	✓	✓
11.x.x		✓	✓	✓	✓
12.x.x				✓	✓

Note: Eclipse Collections 12.x will be compatible with Java 11+. EC 12.0 has not been released as GA yet, but there are a few milestone releases available to test with.

Acquiring Eclipse Collections

Maven

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

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

Gradle

implementation 'org.eclipse.collections:eclipse-collections-api:11.1.0'
implementation 'org.eclipse.collections:eclipse-collections:11.1.0'

OSGi Bundle

Eclipse software repository location: https://download.eclipse.org/collections/11.1.0/repository

How to Contribute

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

Additional information

Project Website: https://eclipse.dev/collections
Eclipse PMI: https://projects.eclipse.org/projects/technology.collections
StackOverflow: https://stackoverflow.com/questions/tagged/eclipse-collections
Mailing lists: https://dev.eclipse.org/mailman/listinfo/collections-dev
Forum: https://www.eclipse.org/forums/index.php?t=thread&frm_id=329
Working with GitHub: https://github.com/eclipse/eclipse-collections/wiki/Working-with-GitHub

eclipse-collections's People

Contributors

Stargazers

Watchers

Forkers

motlin itohro donraab kristeno top-projects nikhilnanivadekar pkdevboxy sachin-handiekar superhindupur jajodr marschall adampb sindsiwe anand-s-s g-votte opengl-8080 chakra-coder guoci luckybaquet cybernetics jackhammer2k mauricenaftalin sztupac ponder-lab alainlompo orekyuu koone szulijun liuzhengyang carlosraphael richardscottgs netnow gs-rezaem fengbaicanhe dmrenton jxqlovejava playbar kxl2005 misanyrock hausea godin cds-shuai runc horbe iuliandumitru jankotek yb2 epsstan benzonico kthoms pascalschumacher lzhuor gaubhav mokah suhasark prashantunhale semtle cinquin nathanmerrill alexeisele pliakas makeyang lightguard aibaars nolequen bergmanngabor kumarkishan shailendra333 ujhelyiz theanuradha gs-vmzakharov jackie-h marko-bekhta paddymahoney fuktat josecarloscanova patekel theloneking shahamer ghacupha lukeeau daniel-dos sobo2620 parikn thepile zhonjo andyglick mlsharrock edgetb henohenotsuyoshi danielnanuk isopov yoshi1579 gaurav4j-xx diffblue-benchmarks jonatadev jawaha itohiro73 zhouyonglong genman

eclipse-collections's Issues

Implement synchronized BiMaps.

The API MutableBiMap<K, V>.asSynchronized() already exists, but the implementation in AbstractMutableBiMap is unsupported.

Implement synchronized wrappers that use ReadWriteLock.

I had issue opened in my project.

Current synchronized collections could be improved by using ReadWriteLock instead of synchronized keyword. This would improve concurrency; multiple parallel readers with single exclusive writer.

I would be happy to provide a patch. Only change is to replace synchronized with:

lock.writeLock().lock()
try{
   //collection tasks
}finally{
  lock.writeLock.unlock()
}

There might be performance regression in some rare cases. JIT can optimize away synchronization if collection is used exclusively by single thread. But I think that is very rare case, if user explicitly asks for thread safe collection.

Optimize addAllIterable in AbstractMutableBagIterable.

The implementation should check if the Iterable to add is a Bag, and then iterate with forEachWithOccurrences and use addOccurrences.

Implement a Tally function

It would be great if there was a Tally function (on RichIterable).

In essense, Tally() would turn your RichIterable into a ObjectIntMap, where the integer is the number of times each T appears in the iterable.

In addition, a TallyBy() that would allow you to tally by the results of a function.

OrderedIterable::max/min/first to return Optional instead of throwing exception

Would be possible for:
OrderedIterable::max, min, getFirst, getLast etc. to return Optional instead of throwing runtime exception? That would provide more concise programming experience.

Fix addAll() method in CompositeFastList to return false on isEmpty() case.

The method currently returns true if the incoming collection isEmpty() when it should return false, as the contract for addAll says true should only be returned if the target collection has been changed.

Optimize org.eclipse.collections.impl.set.sorted.immutable.ImmutableTreeSet#newSet to not create a new TreeSortedSet

The below constructor creates a new SortedSet which is unnecessary as the delegating constructor calls a makes a toArray() call.

public static <T> ImmutableSortedSet<T> newSet(SortedSet<T> set)
{
    return new ImmutableTreeSet<>(TreeSortedSet.newSet(set));
}

private ImmutableTreeSet(SortedSet<T> sortedSet)
{
    this.delegate = (T[]) sortedSet.toArray();
    this.comparator = sortedSet.comparator();
}

Better handle hash collisions

With large hash collisions hashed eclipse-collections seem to perform a lot worse than the stock Oracle JDK hashed collections. Initial superficial analysis seems to suggest that with large hash collisions eclipse-collections also scale a lot worse than the stock Oracle JDK collections.
Generally large hash collisions are a symptom of bad #hashCode implementations is user code. However sometimes an attacker can craft input that results in large hash collisions. An example is when an attacker is able to supply strings that end up as keys in hashed collections and he can chose the input such that all keys have the same hash code. This is generally the case for any key-value based input, examples include XML element or attribute names, XML namespace prefixes, names of JSON object properties, HTTP header names and query parameters of any kind. If an attacker is able to create large enough hash collisions he may be able to degrade application performance enough to create a DoS attack.

String#hashCode() is quite susceptible to hash collisions. There are 2048 strings of length 2 that have the same hash code (see below). Strings have the property that if a.hashCode() == b.hashCode() then (a + b).hashCode() == (b + a).hashCode(). This means out of these 2048 strings one can generate 4194304 strings of length 4 with the same hash code.

To mitigate this changes where introduced to java.util.HashMap (the implementation of String#hashCode() is specified in the Javadoc and Oracle does not want to change it). As a stop gap measure java.util.HashMap used MurmurHash 3 with a random seed to hash strings by calling sun.misc.Hashing.stringHash32 instead of calling String#hashCode() with an instanceof check in HashMap.hash(Object). This changce seems to have been rolled back in recent Java 8 versions. The second change was to overflow to a red-black tree instead of a (linked) list when there are too many hash collisions for a slot. This would probably be the most appropriate change for eclipse-collections as well.

This is all based on Schadcode - Schadenfreude for Hash Functions.

Sample code for producing collisions an be found in marschall/hashcollisions.

The following are results for JMH benchmarks with 2048 elements all having the same hash code.
As you can see often eclipse-collections is more than a factor 10 slower than the stock Oracle JDK collections.
However if it's a scalability difference then more elements would produce a larger difference.

Jcf = Java Colllections Framework (stock Oracle JDK collections) JDK 1.8u74

Benchmark                                          Mode  Cnt       Score     Error   Units
AddCollisionBenchmark.addAllEclipse               thrpt  100     121.100 ±   0.471   ops/s
AddCollisionBenchmark.addAllJcf                   thrpt  100    2793.015 ±  14.038   ops/s
AddCollisionBenchmark.addEclipse                  thrpt  100      74.085 ±   0.320   ops/s
AddCollisionBenchmark.addJcf                      thrpt  100    2889.612 ±  24.448   ops/s
ContainsCollisionBenchmark.containsFirstEclipse   thrpt  100  162662.160 ± 620.752  ops/ms
ContainsCollisionBenchmark.containsFirstJcf       thrpt  100   13453.828 ±  97.863  ops/ms
ContainsCollisionBenchmark.containsLastEclipse    thrpt  100     134.515 ±   0.611  ops/ms
ContainsCollisionBenchmark.containsLastJcf        thrpt  100    5684.152 ±  21.751  ops/ms

Implement MutableMultimap.putAllPairs(Iterable<Pair<K, V>> keyValuePair).

Currently MutableMultimap has these two bulk operations:
putAllPairs(Pair<K, V>... pairs)
putAll(K key, Iterable<? extends V> values)

it does not have putAllPairs(Iterable<Pair<K, V>> keyValuePairs)

the implementation would be straightforward which is the current workaround:

Iterate.forEach(keyValuePairs, each -> multimap.add(each));

eclipse-collections and related projects don't export all packages in their manifest.mf

Currently eclipse-collections, eclipse-collections-api, etc only export their base package and not all of them like it should to work in an OSGi environment.

I believe this is a problem on all recent versions.

Edited out potential solution that wouldn't work.

Implement RichIterable.toMultimap().

Pull request 37 was to implement Iterate.toMultimap(), however the method should be added on RichIterable itself.

Change MutableBagIterable.addOccurrences(T item, int occurrences) to return the updated number of occurrences instead of void.

The current signature in MutableBagIterable is

void addOccurrences(T item, int occurrences);

It should return int, the updated number of occurrences. It should also have clear Javadoc

Optimize org.eclipse.collections.impl.list.immutable.ImmutableListFactoryImpl#withAll to not create redundant array copy.

The call this.of((T[]) Iterate.toArray(items)) eventually creates an extra array copy before calling the constructor org.eclipse.collections.impl.list.immutable.ImmutableArrayList#newListWith.
Similar observation for org.eclipse.collections.impl.list.immutable.ImmutableListFactoryImpl#withList.

Implement unmodifiable Multimaps.

Implement unmodifiable Multimap wrappers like UnmodifiableMutableListMultimap, UnmodifiableMutableSetMultimap, etc.

Implement MutableMultimap<K, V> asUnmodifiable(); in MutableMultimap<K, V> and covariant overrides like MutableListMultimap<K, V> asUnmodifiable(); in MutableListMultimap.

All interfaces that extend MutableMultimap should have an override, including

MutableBagIterableMultimap
MutableBagMultimap
MutableListMultimap
MutableSetIterableMultimap
MutableSetMultimap
MutableSortedBagMultimap
MutableSortedSetMultimap

The overall design and inheritance hierarchy of unmodifiable MutableMultimaps should be similar to the unmodifiable MutableCollection hierarchy.

Creating an Eclipse Plugin/Feature for Eclipse Collections and consuming it fails

I have tried to compile a P2 Repository for Eclipse Collections for my personal use today, using the p2-maven-plugin, with the following POM.

<build>
    <plugins>
        <plugin>
            <groupId>org.reficio</groupId>
            <artifactId>p2-maven-plugin</artifactId>
            <version>1.1.1</version>
            <executions>
                <execution>
                    <id>default-cli</id>
                    <configuration>
                        <artifacts>
                            <!-- specify your depencies here -->
                            <!-- groupId:artifactId:version -->
                            <artifact>
                                <id>org.eclipse.collections:eclipse-collections-api:8.0.0</id>
                                <transitive>true</transitive>
                            </artifact>
                            <artifact>
                                <id>org.eclipse.collections:eclipse-collections:8.0.0</id>
                                <transitive>true</transitive>
                            </artifact>
                        </artifacts>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
<pluginRepositories>
    <pluginRepository>
        <id>reficio</id>
        <url>http://repo.reficio.org/maven/</url>
    </pluginRepository>
</pluginRepositories>

The site builds fine, but when I try to consume the feature, I get the following error (in the Target Platform editor).

Problems occurred while resolving the target contents
 > Cannot complete the install because one or more required items could not be found.
  > Missing requirement: Eclipse Collections Main Library 8.0.0 
     (org.eclipse.collections.eclipse-collections 8.0.0) requires 
     'package org.eclipse.collections.api.bag 0.0.0' but it could not be found
   > Software being installed: Eclipse Collections Main Library 8.0.0 
      (or.eclipse.collections.eclipse-collections 8.0.0)

This makes it impossible to use EC via P2. I've tried with older versions (7.1.0) but get the same error.

Interestingly enough, it does work with GS Collections 7.0.0.

Please let me know should you need more information or if I can be of any help at all.

Implement Verify.assertNotInstanceOf().

Implement two new methods that assert that the actualObject is not an instance of the expectedClassType.

Verify already implements two similar assertions.

public static void assertInstanceOf(Class<?> expectedClassType, Object actualObject)

public static void assertInstanceOf(String objectName, Class<?> expectedClassType, Object actualObject)

Change primitive-primitive/object-primitive functional interfaces to extend the corresponding JDK functional interfades.

The changes would look similar to this commit.

The scope of this issue would be below:
primitiveToPrimitiveFunction.stg (extends JDK primitive to primitive Function such as IntToLongFunction etc.)
objectPrimitiveProcedure.stg (extends JDK object-primitive Consumer such as ObjIntConsumer etc.)
primitiveObjectFunction.stg (extends JDK primitive-object Function such as IntFunction etc.)

Implement Iterate.zipWith(Iterable<T1>, Iterable<T2>, Function2<T1, T2>).

I propose introducing a new zipWith (or similarly named) method in the class Iterate that would accept two iterables of type T and TT, respectively, and a function whose input is the current element of both iterables and output can be of a third type, TTT.

This would allow you to zip two iterables with the added benefit of the option of running some computation on each iteration and outputting to a collection of any type that tickles your fancy.

Thoughts?

Optimize constructors of ImmutableTreeSet which take an array as input.

These two constructors can be optimized:

org.eclipse.collections.impl.set.sorted.immutable.ImmutableTreeSet#newSetWith(T...)
org.eclipse.collections.impl.set.sorted.immutable.ImmutableTreeSet#newSetWith(java.util.Comparator<? super T>, T...)

In order to create the ImmutableTreeSet, it is not necessary to create a new TreeSortedSet. The input array can be cloned, sorted, compared and assigned to the delegate.

Make constructors on Unmodifiable and Synchronized collections public

I have my own implementations of LongLongMap and LongObjectMap collections. Constructors on UnmodifiableLongLongMap and SynchronizedLongLongMap are package protected. My implementations can not instantiate those wrappers.

Is it possible to make constructor on Unmodifiable* amd Synchronized* classes public?

improve speed of chunk() of List implementations

We've noticed that the chunk() implementation of FastList (actually AbstractMutableCollection) iterates over the whole list and creates a new list containing chunked lists. We're using Guavas Lists.partition() method (which uses sublists instead) on top of FastList to get performance speed up.
Classes implementing List like FastList should implement chunk() by using sublists.

Here our benchmark:

public class FastListBenchmark {
    @State(Scope.Thread)
    public static class MyState {
        FastList<Integer> list;

        @Setup(Level.Trial)
        public void doSetup() {
            list = new FastList<>();
            for (int i = 0; i < 10000000; i++) {
                list.add(i);
            }
        }
    }

    @Benchmark
    @BenchmarkMode(Mode.All)
    public void parallelIterationViaChunk(MyState myState) throws ExecutionException, InterruptedException {
        RichIterable<RichIterable<Integer>> partitionedValues = myState.list
                .chunk(myState.list.size() / (Executor.NUMBEROFTHREADS * 8));
        iterate(partitionedValues);
    }

    @Benchmark
    @BenchmarkMode(Mode.All)
    public void parallelIterationViaPartition(MyState myState) throws ExecutionException, InterruptedException {
        List<List<Integer>> partitionedValues = Lists
                .partition(myState.list, myState.list.size() / (Executor.NUMBEROFTHREADS * 8));
        iterate(partitionedValues);
    }

    private void iterate(Iterable<? extends Iterable<?>> partitionedValues)
            throws ExecutionException, InterruptedException {
        Collection<Runnable> jobs = new ArrayList<>();
        for (Iterable<?> values : partitionedValues) {
            jobs.add(() -> {
                for (Object value : values) {
                    foobar();
                }
            });
        }
        new Executor().execute(jobs);
    }
}

public class Executor {

    public static final int NUMBEROFTHREADS = Runtime.getRuntime().availableProcessors();

    public final ExecutorService executor = Executors.newFixedThreadPool(NUMBEROFTHREADS);

    public void execute(Collection<Runnable> jobs) throws ExecutionException, InterruptedException {
        for (Runnable job : jobs) {
            executor.execute(job);
        }
        executor.shutdown(); // !!! not shutdownNow
        executor.awaitTermination(1, TimeUnit.HOURS);
    }
}

Benchmark Mode Cnt Score Error Units
FastListBenchmark.parallelIterationViaChunk thrpt 200 13.286 ± 0.042 ops/s
FastListBenchmark.parallelIterationViaPartition thrpt 200 74.269 ± 0.445 ops/s
FastListBenchmark.parallelIterationViaChunk avgt 200 0.075 ± 0.001 s/op
FastListBenchmark.parallelIterationViaPartition avgt 200 0.013 ± 0.001 s/op
FastListBenchmark.parallelIterationViaChunk sample 2689 0.077 ± 0.001 s/op
FastListBenchmark.parallelIterationViaPartition sample 14114 0.014 ± 0.001 s/op
FastListBenchmark.parallelIterationViaChunk ss 10 1.668 ± 0.043 s/op
FastListBenchmark.parallelIterationViaPartition ss 10 1.472 ± 0.056 s/op

Implement RichIterable.getOnly().

The implementation should be similar to IterableIterate.getOnly() but be available on the interface RichIterable. If the iterable has exactly one item, return it. Otherwise, throw IllegalArgumentException with a short explanation.

Idea project files in git repo?

I noticed git repo contains .idea folder and it is not excluded in .gitignore.

First commit included dozen of *.iml files from subprojects. It was a bit annoying to filter them out.

is there some good purpose to include project files in git repo? In general it is considered a bad practice, Idea usually imports maven projects just fine.
could we update .gitignore to exclude subproject files?

Sign Releases

Please sign your release jar files.

See: https://wiki.eclipse.org/JAR_Signing

Implement OrderedIterable.getFirstOptional() and OrderedIterable.getLastOptional() .

Implement getFirst and getLast methods that returns Optional on OrderedIterable. The method signatures would look like below.

Optional<T> getFirstOptional()
Optional<T> getLastOptional()

Implement asLazy() on Multimap.

Currently, iteration patterns on Multimap are eager. Multimap interface should have asLazy() method which will delegate to a LazyMultimap similar to how asLazy() on RichIterable delegates to LazyIterable.

Implement flatCollect on primitive iterable types.

The signature should be similar to collect, but return an Iterable. This is how the signature should apprear in primitiveIterable.stg

RichIterable flatCollect(ToObjectFunction<? extends Iterable> function);

Implement minOptional, maxOptional, minByOptional and maxByOptional on RichIterable.

Implement min/max methods that returns Optional on RichIterable. The method signatures would look like below.

Optional<T> minOptional(Comparator<? super T> comparator)
Optional<T> maxOptional(Comparator<? super T> comparator)
Optional<T> minOptional()
Optional<T> maxOptional()
<V extends Comparable<? super V>> Optional<T> minByOptional(Function<? super T, ? extends V> function)
<V extends Comparable<? super V>> Optional<T> maxByOptional(Function<? super T, ? extends V> function)

EMPTY_VALUE should be settable for Map

When using classes such as ObjectDoubleHashMap we should be able to set the EMPTY_VALUE upon construction. In our situation, Zero is a perfectly valid double value and does not properly differentiate between a valid or invalid key without explictly checking containsKey. Which is expensive!

We would like to be able to set this to NaN which was supported by Trove collections.

Implement RichIterable.getOnlyOptional().

Implement getOnly method that returns Optional on RichIterable. The method signature would look like below.

Optional<T> getOnlyOptional()

Implement LazyIterable.takeWhile(Predicate) and LazyIterable.dropWhile(Predicate).

A LazyIterable may not have a meaningful order, if it was created from MutableSet.asLazy() for example, so it doesn't implementOrderedIterable. But it may have a meaningful order too.

LazyIterable already implements some equivalent methods from OrderedIterable that short circuit, like take() and drop(). It should also implement takeWhile() and dropWhile() with the following signatures.

LazyIterable<T> takeWhile(Predicate<? super T> predicate);
LazyIterable<T> dropWhile(Predicate<? super T> predicate);

Implement RichIterable.reduceBy().

The existing method RichIterable.aggregateBy(Function, Function0, Function2) is conceptually a groupBy() followed by injectInto() on each group of values. This method would be a groupBy followed by reduce() on each group of values. Multiple variants are possible, but the first signature ought to be:

<K, T> MapIterable<K, T> reduceBy(
    Function<? super T, ? extends K> groupBy,
    Function2<? super T, ? super T, ? extends T> reduceFunction);

Immutable primitive collections

The official website says

//Mutable and immutable Lists, Sets, Bags, Stacks and Maps are available for all 8 primitive types

However I could not find any example of immutable primitive collections. Where are they?

Create immutable primitive collection wrappers which cache the hashcode.

For immutable primitive collections, it makes sense to cache the hash code once it is calculated. Currently, it is recalculated everytime.

A similar strategy to the one in java.lang.String#hashCode can be used.

Implement Bags that use hashing strategies.

UnifiedSet has a variant called UnifiedSetWithHashingStrategy that uses a HashingStrategy instead of using equals() and hashCode().

Similarly, HashBag should have a a variant that uses a HashingStrategy.

Change primitive functional interfaces to extend the corresponding JDK functional interfaces.

The changes would look similar to this commit.

The scope of this issue would be below:
primitiveFunction.stg (extends JDK primitive ToXxxFunction)
primitiveFunction0.stg (extends JDK primitive XxxSupplier)
primitiveProcedure.stg (extends JDK primitive XxxConsumer)

java 8 convergence: provide efficient implementation of Java 8 default methods

JDK8 default methods on Collections such as forEach, putIfAbsent etc. should be mapped to their equivalent but more efficient implementations.

Implement RichIterable.groupByAndCollect().

Refer to discussion on pull request 37 for more information. Also, please use the most up-to-date name decided.

Implement unmodifiable BiMaps.

The API MutableBiMap<K, V>.asUnmodifiable() already exists, but the implementation in AbstractMutableBiMap is unsupported.

Implement synchronized Multimaps.

Implement synchronized Multimap wrappers like SynchronizedMutableListMultimap, SynchronizedMutableSetMultimap, etc.

Implement MutableMultimap<K, V> asSynchronized(); in MutableMultimap<K, V> and covariant overrides like MutableListMultimap<K, V> asSynchronized(); in MutableListMultimap.

All interfaces that extend MutableMultimap should have an override, including

MutableBagIterableMultimap
MutableBagMultimap
MutableListMultimap
MutableSetIterableMultimap
MutableSetMultimap
MutableSortedBagMultimap
MutableSortedSetMultimap

The overall design and inheritance hierarchy of synchronized MutableMultimaps should be similar to the synchronized MutableCollection hierarchy.

Code generation fails with NPE on Windows & OSX

On OSX, I tried building at tags 7.1.0-javadoc-fix, 7.1.0, and on commit 8.0.0-26-gb40e3bb on master. On Windows I only tried commit 8.0.0-26-gb40e3bb.

Regardless I always get a variation of the output below, with the build failing on the "Eclipse Collections Main Library" step.

Searching for "antlr st4 internal error: java.lang.NullPointerException" yields a similar issue whose root cause was a file naming conflict on case-insensitive file systems.

Here's the output:

[INFO] --- eclipse-collections-code-generator-maven-plugin:7.1.0:generate (default) @ eclipse-collections ---
[DEBUG] Configuring mojo org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate from plugin realm ClassRealm[plugin>org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0, parent: sun.misc.Launcher$AppClassLoader@6d6f6e28]
[DEBUG] Configuring mojo 'org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate' with basic configurator -->
[DEBUG]   (f) project = MavenProject: org.eclipse.collections:eclipse-collections:7.1.0 @ /Users/will/targetstream/git/eclipse-collections/eclipse-collections/pom.xml
[DEBUG]   (f) templateDirectory = impl
[DEBUG] -- end configuration --
[INFO] Generating sources to eclipse-collections
[ERROR] String template run time error while processing [file:/Users/will/targetstream/git/eclipse-collections/eclipse-collections-code-generator/target/eclipse-collections-code-generator-7.1.0.jar!/impl/block/factory/primitivePredicates.stg]: context [/class /body] 29:5 internal error: java.lang.NullPointerException
    at org.stringtemplate.v4.STGroup.getEmbeddedInstanceOf(STGroup.java:177)
    at org.stringtemplate.v4.Interpreter._exec(Interpreter.java:235)
    at org.stringtemplate.v4.Interpreter.exec(Interpreter.java:145)
    at org.stringtemplate.v4.Interpreter.writeObject(Interpreter.java:742)
    at org.stringtemplate.v4.Interpreter.writeObjectNoOptions(Interpreter.java:674)
    at org.stringtemplate.v4.Interpreter._exec(Interpreter.java:285)
    at org.stringtemplate.v4.Interpreter.exec(Interpreter.java:145)
    at org.stringtemplate.v4.ST.write(ST.java:427)
    at org.stringtemplate.v4.ST.render(ST.java:497)
    at org.stringtemplate.v4.ST.render(ST.java:491)
    at org.stringtemplate.v4.ST.render(ST.java:487)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator.executeTemplate(EclipseCollectionsCodeGenerator.java:162)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator.generateFiles(EclipseCollectionsCodeGenerator.java:112)
    at org.eclipse.collections.codegenerator.maven.GenerateMojo.execute(GenerateMojo.java:78)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:132)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:208)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:116)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:80)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build(SingleThreadedBuilder.java:51)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:120)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:355)
    at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:155)
    at org.apache.maven.cli.MavenCli.execute(MavenCli.java:584)
    at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:216)
    at org.apache.maven.cli.MavenCli.main(MavenCli.java:160)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:289)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:229)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:415)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:356)

[ERROR] String template run time error while processing [file:/Users/will/targetstream/git/eclipse-collections/eclipse-collections-code-generator/target/eclipse-collections-code-generator-7.1.0.jar!/impl/block/factory/primitivePredicates.stg]: context [/class] 1:0 internal error: java.lang.RuntimeException
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator$LoggingErrorListener.logError(EclipseCollectionsCodeGenerator.java:228)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator$LoggingErrorListener.runTimeError(EclipseCollectionsCodeGenerator.java:238)
    at org.stringtemplate.v4.misc.ErrorManager.runTimeError(ErrorManager.java:133)
    at org.stringtemplate.v4.Interpreter.exec(Interpreter.java:152)
    at org.stringtemplate.v4.Interpreter.writeObject(Interpreter.java:742)
    at org.stringtemplate.v4.Interpreter.writeObjectNoOptions(Interpreter.java:674)
    at org.stringtemplate.v4.Interpreter._exec(Interpreter.java:285)
    at org.stringtemplate.v4.Interpreter.exec(Interpreter.java:145)
    at org.stringtemplate.v4.ST.write(ST.java:427)
    at org.stringtemplate.v4.ST.render(ST.java:497)
    at org.stringtemplate.v4.ST.render(ST.java:491)
    at org.stringtemplate.v4.ST.render(ST.java:487)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator.executeTemplate(EclipseCollectionsCodeGenerator.java:162)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator.generateFiles(EclipseCollectionsCodeGenerator.java:112)
    at org.eclipse.collections.codegenerator.maven.GenerateMojo.execute(GenerateMojo.java:78)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:132)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:208)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:116)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:80)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build(SingleThreadedBuilder.java:51)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:120)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:355)
    at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:155)
    at org.apache.maven.cli.MavenCli.execute(MavenCli.java:584)
    at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:216)
    at org.apache.maven.cli.MavenCli.main(MavenCli.java:160)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:289)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:229)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:415)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:356)

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] Eclipse Collections Parent Project ................. SUCCESS [  0.609 s]
[INFO] Eclipse Collections Code Generator ................. SUCCESS [  3.070 s]
[INFO] Eclipse Collections Code Generator Ant Task ........ SUCCESS [  0.857 s]
[INFO] Eclipse Collections Code Generator Maven Plugin .... SUCCESS [  1.672 s]
[INFO] Eclipse Collections API ............................ SUCCESS [ 10.200 s]
[INFO] Eclipse Collections Main Library ................... FAILURE [  0.389 s]
[INFO] Eclipse Collections Test Utilities ................. SKIPPED
[INFO] Eclipse Collections Fork Join Utilities ............ SKIPPED
[INFO] Eclipse Collections Unit Test Suite ................ SKIPPED
[INFO] Eclipse Collections Scala Unit Test Suite .......... SKIPPED
[INFO] Eclipse Collections Serialization Test Suite ....... SKIPPED
[INFO] Eclipse Collections JMH Scala Test Suite ........... SKIPPED
[INFO] Eclipse Collections JMH Test Suite ................. SKIPPED
[INFO] Eclipse Collections Test Trait JUnit Runner ........ SKIPPED
[INFO] Eclipse Collections Java 8 Unit Test Suite ......... SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 17.743 s
[INFO] Finished at: 2016-10-25T07:10:44-05:00
[INFO] Final Memory: 27M/517M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate (default) on project eclipse-collections: Execution default of goal org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate failed. RuntimeException -> [Help 1]
org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate (default) on project eclipse-collections: Execution default of goal org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate failed.
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:224)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:116)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:80)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build(SingleThreadedBuilder.java:51)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:120)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:355)
    at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:155)
    at org.apache.maven.cli.MavenCli.execute(MavenCli.java:584)
    at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:216)
    at org.apache.maven.cli.MavenCli.main(MavenCli.java:160)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:497)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:289)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:229)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:415)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:356)
Caused by: org.apache.maven.plugin.PluginExecutionException: Execution default of goal org.eclipse.collections:eclipse-collections-code-generator-maven-plugin:7.1.0:generate failed.
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:143)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:208)
    ... 19 more
Caused by: java.lang.RuntimeException
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator$LoggingErrorListener.logError(EclipseCollectionsCodeGenerator.java:228)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator$LoggingErrorListener.runTimeError(EclipseCollectionsCodeGenerator.java:238)
    at org.stringtemplate.v4.misc.ErrorManager.runTimeError(ErrorManager.java:133)
    at org.stringtemplate.v4.Interpreter.exec(Interpreter.java:152)
    at org.stringtemplate.v4.ST.write(ST.java:427)
    at org.stringtemplate.v4.ST.render(ST.java:497)
    at org.stringtemplate.v4.ST.render(ST.java:491)
    at org.stringtemplate.v4.ST.render(ST.java:487)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator.executeTemplate(EclipseCollectionsCodeGenerator.java:162)
    at org.eclipse.collections.codegenerator.EclipseCollectionsCodeGenerator.generateFiles(EclipseCollectionsCodeGenerator.java:112)
    at org.eclipse.collections.codegenerator.maven.GenerateMojo.execute(GenerateMojo.java:78)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:132)
    ... 20 more

The immutablePrimitiveList.stg could benefit from a collect overload

The use case I am missing is being able to collect from an ImmutableDoubleList to the same type. Unfortunately, the API is currently limited to collect-ing to an ImmutableList<V>.

For example, what I would like to do is:

void method(ImmutableDoubleList data)
{
    // Do some manipulation to each double in the list, returning a double.
    ImmutableDoubleList modified = data.collect(d -> d * d / 2 + 4);
    // ...
}

But the type of modified is forced to:

ImmutableList<Double> modified = data.collect(d -> d * d / 2 + 4);

One workaround is to add a call to .collectDouble(d -> d), like so:

ImmutableDoubleList modified = data.collect(d -> d * d / 2 + 4).collectDouble(d -> d);

However, I think this could be more eloquently handled with an overloaded method added to immutablePrimitiveList.stg as:

Immutable<name>List collect(<name>To<name>Function function);

This overload could also be applied to other primitive collection types as well.

Implement keySet() on Multimap.

Multimap has keyBag() however, it is an O(n) operation which loops through the elements and creates a new Bag. Since a Multimap is defined as a Map of key and value Collection, there should be a method keySet() similar to what is present on a Map.

The keySet() implementation will go on AbstractMutableMultimap and AbstractImmutableMultimap.

On AbstractMutableMultimap, the implementation will be:

public Set<K> keySet()
{
  return this.map.keySet();
}

On AbstractImmutableMultimap, the implementation will be:

public Set<K> keySet()
{
  return this.map.castToMap().keySet();
}

Note:

This cannot be added on AbstractMultimap as the getMap() method on it returns a MapIterable and does not have a keySet() method as yet.
Current workaround is keysView() which is a lazy view of the unique keys.

Eclipse issues with MANIFEST.MF

Eclipse is able to pick up the eclipse-collections-api jar as a plug-in. However, the eclipse-collections jar is not recognized as such.

Also, for both jars, the exported packages list only contains the top level package. This causes Eclipse to recognize the classes in all subpackages as non-api, resulting in warnings when used.

Could this be an issue with the way that the MANIFEST.MF files in the jars are build?

Deprecate or hide collection factory constructors.

Clarify that classes like collection factory classes are not meant to be instantiated more than once. The current API allows you to get an empty immutable list like this.

ImmutableList<Object> list1 = new ImmutableListFactoryImpl().empty();

The better way to get an empty immutable list is like this.

ImmutableList<Object> list2 = Lists.immutable.empty();

Both examples return the singleton instance of the empty immutable list. In other words, list1 and list2 are the same instance. The second example creates no garbage, making the first example seem especially wasteful. Lists.immutable is intended to hold the only instance of ImmutableListFactoryImpl in the JVM.

For all collection factory classes, change them to implement the singleton pattern, or clarify that they aren't meant to be instantiated by deprecating their constructors and adding Javadoc links to the classes like Lists that should be used instead.

If this is handled through deprecation, it can be done in a minor release. Changing the collection factories to implement the singleton pattern would be a compatibility breaking change.

Remove JMH Tests from JavaDoc output.

JMH Tests and their generated output are currently being included in the JavaDoc and should be excluded.

Implement spliterator, stream, parallelStream and castToCollection on ImmutableCollection

These methods should be added as default methods on ImmutableCollection, and then overridden as necessary on interfaces like ImmutableList and implemented in abstract classes and subclasses as necessary.

This feature can only be done in a major version release, since adding the default methods to ImmutableCollection for spliterator, stream and parallelStream would be ambiguous for implementations since they also have to extend Collection, List or Set.

Implement RichIterable.groupByEachAndCollect().

Refer to discussion on pull request 37 for more information. Also, please use the most up-to-date name decided.

No way to collect into an ImmutableMultimap

As it stands, I only see two ways to construct an ImmutableMultimap:

Multimaps.immutable.of, which allows you to insert at maximum 3 items.
MutableMultimap.toImmutable(), which means you have to iterate through a collection, add it to a temporary mutable, then call toImmutable() on it.

While option 2 works, I'd love it if there was someway to create a multimap from existing immutable collections. Signatures would likely be similar to .flatCollect().

EDIT: I realized that option 1 also allows an iterative-based solution by calling .newWith(), but that's effectively the same as option 2.

Implement ReversibleIterable.reverseForEachWithIndex().

It's the variant of reverseForEach() with index.