#705 Add specialised interfaces for MultiReader List Set and Bag

Signed-off-by: canthonyl <cheung.yi.lung@gmail.com>

eclipse-collections-api/src/main/java/org/eclipse/collections/api/bag/MultiReaderBag.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2019 Goldman Sachs and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * and Eclipse Distribution License v. 1.0 which accompany this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+
+package org.eclipse.collections.api.bag;
+
+import org.eclipse.collections.api.block.procedure.Procedure;
+
+/**
+ * A MultiReaderBag provides thread-safe iteration for a bag through methods {@code withReadLockAndDelegate()} and {@code withWriteLockAndDelegate()}.
+ *
+ * @since 10.0.
+ */
+public interface MultiReaderBag<T>
+        extends MutableBag<T>
+{
+    void withReadLockAndDelegate(Procedure<? super MutableBag<T>> procedure);
+
+    void withWriteLockAndDelegate(Procedure<? super MutableBag<T>> procedure);
+}

eclipse-collections-api/src/main/java/org/eclipse/collections/api/factory/bag/MultiReaderBagFactory.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2019 Goldman Sachs and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * and Eclipse Distribution License v. 1.0 which accompany this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+
+package org.eclipse.collections.api.factory.bag;
+
+import java.util.stream.Stream;
+
+import org.eclipse.collections.api.bag.MultiReaderBag;
+
+/**
+ * A factory which creates instances of type {@link MultiReaderBag}.
+ *
+ * @since 10.0.
+ */
+public interface MultiReaderBagFactory
+{
+    <T> MultiReaderBag<T> empty();
+
+    /**
+     * Same as {@link #empty()}.
+     */
+    default <T> MultiReaderBag<T> of()
+    {
+        return this.empty();
+    }
+
+    /**
+     * Same as {@link #empty()}.
+     */
+    default <T> MultiReaderBag<T> with()
+    {
+        return this.empty();
+    }
+
+    /**
+     * Same as {@link #with(Object[])}.
+     */
+    default <T> MultiReaderBag<T> of(T... elements)
+    {
+        return this.with(elements);
+    }
+
+    <T> MultiReaderBag<T> with(T... elements);
+
+    /**
+     * Same as {@link #withAll(Iterable)}.
+     */
+    default <T> MultiReaderBag<T> ofAll(Iterable<? extends T> items)
+    {
+        return this.withAll(items);
+    }
+
+    <T> MultiReaderBag<T> withAll(Iterable<? extends T> items);
+
+    <T> MultiReaderBag<T> fromStream(Stream<? extends T> stream);
+}

eclipse-collections-api/src/main/java/org/eclipse/collections/api/factory/list/MultiReaderListFactory.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2019 Goldman Sachs and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * and Eclipse Distribution License v. 1.0 which accompany this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+
+package org.eclipse.collections.api.factory.list;
+
+import java.util.stream.Stream;
+
+import org.eclipse.collections.api.block.function.Function0;
+import org.eclipse.collections.api.list.MultiReaderList;
+
+/**
+ * A factory which creates instances of type {@link MultiReaderList}.
+ *
+ * @since 10.0.
+ */
+public interface MultiReaderListFactory
+{
+    <T> MultiReaderList<T> empty();
+
+    /**
+     * Same as {@link #empty()}.
+     */
+    default <T> MultiReaderList<T> of()
+    {
+        return this.empty();
+    }
+
+    /**
+     * Same as {@link #empty()}.
+     */
+    default <T> MultiReaderList<T> with()
+    {
+        return this.empty();
+    }
+
+    /**
+     * Same as {@link #with(Object[])}.
+     */
+    default <T> MultiReaderList<T> of(T... items)
+    {
+        return this.with(items);
+    }
+
+    <T> MultiReaderList<T> with(T... items);
+
+    /**
+     * Same as {@link #empty()}. but takes in initial capacity.
+     */
+    default <T> MultiReaderList<T> ofInitialCapacity(int capacity)
+    {
+        return this.withInitialCapacity(capacity);
+    }
+
+    /**
+     * Same as {@link #empty()}. but takes in initial capacity.
+     */
+    <T> MultiReaderList<T> withInitialCapacity(int capacity);
+
+    /**
+     * Same as {@link #withAll(Iterable)}.
+     */
+    default <T> MultiReaderList<T> ofAll(Iterable<? extends T> iterable)
+    {
+        return this.withAll(iterable);
+    }
+
+    <T> MultiReaderList<T> withAll(Iterable<? extends T> iterable);
+
+    <T> MultiReaderList<T> fromStream(Stream<? extends T> stream);
+
+    <T> MultiReaderList<T> withNValues(int size, Function0<? extends T> factory);
+}

eclipse-collections-api/src/main/java/org/eclipse/collections/api/factory/set/MultiReaderSetFactory.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2019 Goldman Sachs and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * and Eclipse Distribution License v. 1.0 which accompany this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+
+package org.eclipse.collections.api.factory.set;
+
+import java.util.stream.Stream;
+
+import org.eclipse.collections.api.set.MultiReaderSet;
+
+/**
+ * A factory which creates instances of type {@link MultiReaderSet}.
+ *
+ * @since 10.0.
+ */
+public interface MultiReaderSetFactory
+{
+    <T> MultiReaderSet<T> empty();
+
+    /**
+     * Same as {@link #empty()}.
+     */
+    default <T> MultiReaderSet<T> of()
+    {
+        return this.empty();
+    }
+
+    /**
+     * Same as {@link #empty()}.
+     */
+    default <T> MultiReaderSet<T> with()
+    {
+        return this.empty();
+    }
+
+    /**
+     * Same as {@link #with(Object[])}.
+     */
+    default <T> MultiReaderSet<T> of(T... items)
+    {
+        return this.with(items);
+    }
+
+    <T> MultiReaderSet<T> with(T... items);
+
+    /**
+     * Same as {@link #empty()}. but takes in initial capacity.
+     */
+    default <T> MultiReaderSet<T> ofInitialCapacity(int capacity)
+    {
+        return this.withInitialCapacity(capacity);
+    }
+
+    /**
+     * Same as {@link #empty()}. but takes in initial capacity.
+     */
+    <T> MultiReaderSet<T> withInitialCapacity(int capacity);
+
+    /**
+     * Same as {@link #withAll(Iterable)}.
+     */
+    default <T> MultiReaderSet<T> ofAll(Iterable<? extends T> items)
+    {
+        return this.withAll(items);
+    }
+
+    <T> MultiReaderSet<T> withAll(Iterable<? extends T> items);
+
+    <T> MultiReaderSet<T> fromStream(Stream<? extends T> stream);
+}

eclipse-collections-api/src/main/java/org/eclipse/collections/api/list/MultiReaderList.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2019 Goldman Sachs and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * and Eclipse Distribution License v. 1.0 which accompany this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+
+package org.eclipse.collections.api.list;
+
+import org.eclipse.collections.api.block.procedure.Procedure;
+
+/**
+ * A MultiReaderList provides thread-safe iteration for a list through methods {@code withReadLockAndDelegate()} and {@code withWriteLockAndDelegate()}.
+ *
+ * @since 10.0.
+ */
+public interface MultiReaderList<T>
+        extends MutableList<T>
+{
+    void withReadLockAndDelegate(Procedure<? super MutableList<T>> procedure);
+
+    void withWriteLockAndDelegate(Procedure<? super MutableList<T>> procedure);
+}

eclipse-collections-api/src/main/java/org/eclipse/collections/api/set/MultiReaderSet.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2019 Goldman Sachs and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * and Eclipse Distribution License v. 1.0 which accompany this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
+ * and the Eclipse Distribution License is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+
+package org.eclipse.collections.api.set;
+
+import org.eclipse.collections.api.block.procedure.Procedure;
+
+/**
+ * A MultiReaderSet provides thread-safe iteration for a set through methods {@code withReadLockAndDelegate()} and {@code withWriteLockAndDelegate()}.
+ *
+ * @since 10.0.
+ */
+public interface MultiReaderSet<T>
+        extends MutableSet<T>
+{
+    void withReadLockAndDelegate(Procedure<? super MutableSet<T>> procedure);
+
+    void withWriteLockAndDelegate(Procedure<? super MutableSet<T>> procedure);
+}

eclipse-collections/src/main/java/org/eclipse/collections/impl/bag/mutable/MultiReaderHashBag.java

@@ -22,6 +22,7 @@
 import org.eclipse.collections.api.LazyIterable;
 import org.eclipse.collections.api.RichIterable;
 import org.eclipse.collections.api.bag.ImmutableBag;
+import org.eclipse.collections.api.bag.MultiReaderBag;
 import org.eclipse.collections.api.bag.MutableBag;
 import org.eclipse.collections.api.bag.primitive.MutableBooleanBag;
 import org.eclipse.collections.api.bag.primitive.MutableByteBag;
@@ -80,7 +81,7 @@
  */
 public final class MultiReaderHashBag<T>
         extends AbstractMultiReaderMutableCollection<T>
-        implements Externalizable, MutableBag<T>
+        implements Externalizable, MultiReaderBag<T>
 {
     private static final long serialVersionUID = 1L;
 
@@ -144,7 +145,7 @@ UntouchableMutableBag<T> asWriteUntouchable()
         return new UntouchableMutableBag<>(this.delegate);
     }
 
-    public void withReadLockAndDelegate(Procedure<MutableBag<T>> procedure)
+    public void withReadLockAndDelegate(Procedure<? super MutableBag<T>> procedure)
     {
         try (LockWrapper wrapper = this.lockWrapper.acquireReadLock())
         {
@@ -154,7 +155,7 @@ public void withReadLockAndDelegate(Procedure<MutableBag<T>> procedure)
         }
     }
 
-    public void withWriteLockAndDelegate(Procedure<MutableBag<T>> procedure)
+    public void withWriteLockAndDelegate(Procedure<? super MutableBag<T>> procedure)
     {
         try (LockWrapper wrapper = this.lockWrapper.acquireWriteLock())
         {

eclipse-collections/src/main/java/org/eclipse/collections/impl/bag/mutable/MultiReaderMutableBagFactory.java

@@ -13,33 +13,33 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-import org.eclipse.collections.api.bag.MutableBag;
-import org.eclipse.collections.api.factory.bag.MutableBagFactory;
+import org.eclipse.collections.api.bag.MultiReaderBag;
+import org.eclipse.collections.api.factory.bag.MultiReaderBagFactory;
 
-public enum MultiReaderMutableBagFactory implements MutableBagFactory
+public enum MultiReaderMutableBagFactory implements MultiReaderBagFactory
 {
     INSTANCE;
 
     @Override
-    public <T> MutableBag<T> empty()
+    public <T> MultiReaderBag<T> empty()
     {
         return MultiReaderHashBag.newBag();
     }
 
     @Override
-    public <T> MutableBag<T> with(T... items)
+    public <T> MultiReaderBag<T> with(T... items)
     {
         return MultiReaderHashBag.newBagWith(items);
     }
 
     @Override
-    public <T> MutableBag<T> withAll(Iterable<? extends T> iterable)
+    public <T> MultiReaderBag<T> withAll(Iterable<? extends T> iterable)
     {
         return MultiReaderHashBag.newBag((Iterable<T>) iterable);
     }
 
     @Override
-    public <T> MutableBag<T> fromStream(Stream<? extends T> stream)
+    public <T> MultiReaderBag<T> fromStream(Stream<? extends T> stream)
     {
         return stream.collect(Collectors.toCollection(MultiReaderHashBag::newBag));
     }

eclipse-collections/src/main/java/org/eclipse/collections/impl/factory/Bags.java

@@ -11,6 +11,7 @@
 package org.eclipse.collections.impl.factory;
 
 import org.eclipse.collections.api.factory.bag.ImmutableBagFactory;
+import org.eclipse.collections.api.factory.bag.MultiReaderBagFactory;
 import org.eclipse.collections.api.factory.bag.MutableBagFactory;
 import org.eclipse.collections.impl.bag.immutable.ImmutableBagFactoryImpl;
 import org.eclipse.collections.impl.bag.mutable.MultiReaderMutableBagFactory;
@@ -41,7 +42,7 @@ public final class Bags
 {
     public static final ImmutableBagFactory immutable = ImmutableBagFactoryImpl.INSTANCE;
     public static final MutableBagFactory mutable = MutableBagFactoryImpl.INSTANCE;
-    public static final MutableBagFactory multiReader = MultiReaderMutableBagFactory.INSTANCE;
+    public static final MultiReaderBagFactory multiReader = MultiReaderMutableBagFactory.INSTANCE;
 
     private Bags()
     {