Add ObjectThreader for multithreading using pipelines

The ObjectThreader divides incoming objects and passes them to receivers,
each internally plumbed with an ObjectPipeDecoupler.
Thus, a multithreaded object pipeline is created.
The receivers are to be added like every Tee receiver.

- change methods of DefaultTee to not be final
- add test

The ObjectThreader makes use of the DefaultTee and overrides two methods, so
they musn't be final.

See hbz/lobid-resources#967.

Author: dr0i

metafacture-flowcontrol/src/main/java/org/metafacture/flowcontrol/ObjectThreader.java

@@ -0,0 +1,70 @@
+/* Copyright 2019 hbz, Pascal Christoph. 
+ * 
+ * Licensed under the Apache License, Version 2.0 the "License";
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.metafacture.flowcontrol;
+
+import org.metafacture.framework.FluxCommand;
+import org.metafacture.framework.ObjectPipe;
+import org.metafacture.framework.ObjectReceiver;
+import org.metafacture.framework.Tee;
+import org.metafacture.framework.annotations.Description;
+import org.metafacture.framework.annotations.In;
+import org.metafacture.framework.annotations.Out;
+import org.metafacture.framework.helpers.DefaultTee;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Divides incoming objects and distributes them to added receivers. These
+ * receivers are coupled with an
+ * {@link org.metafacture.flowcontrol.ObjectPipeDecoupler}, so each added
+ * receiver runs in its own thread.
+ * 
+ * @param <T> Object type
+ *
+ * @author Pascal Christoph(dr0i)
+ * 
+ */
+@In(Object.class)
+@Out(Object.class)
+@Description("incoming objects are distributed to the added receivers, running in their own threads")
+@FluxCommand("threader")
+public class ObjectThreader<T> extends DefaultTee<ObjectReceiver<T>> implements ObjectPipe<T, ObjectReceiver<T>> {
+
+    private static final Logger LOG = LoggerFactory.getLogger(ObjectThreader.class);
+    private int objectNumber = 0;
+
+    @Override
+    public void process(final T obj) {
+        getReceivers().get(objectNumber).process(obj);
+        if (objectNumber == getReceivers().size() - 1)
+            objectNumber = 0;
+        else
+            objectNumber++;
+    }
+
+    @Override
+    public <R extends ObjectReceiver<T>> R setReceiver(final R receiver) {
+        return super.setReceiver(new ObjectPipeDecoupler<T>().setReceiver(receiver));
+    }
+
+    @Override
+    public Tee<ObjectReceiver<T>> addReceiver(final ObjectReceiver<T> receiver) {
+        LOG.info("Adding thread " + (getReceivers().size() + 1));
+        ObjectPipeDecoupler<T> opd = new ObjectPipeDecoupler<>();
+        opd.setReceiver(receiver);
+        return super.addReceiver(opd);
+    }
+}

metafacture-flowcontrol/src/test/java/org/metafacture/flowcontrol/ObjectThreaderTest.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2019 hbz
+ *
+ * Licensed under the Apache License, Version 2.0 the "License";
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.metafacture.flowcontrol;
+
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.atMost;
+import static org.mockito.Mockito.atLeast;
+
+import org.junit.Before;
+import org.junit.Test;
+import org.metafacture.flowcontrol.ObjectThreader;
+import org.metafacture.framework.ObjectReceiver;
+
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+/**
+ * Tests for class {@link ObjectThreader} (which itself uses
+ * {@link org.metafacture.flowcontrol.ObjectPipeDecoupler} to thread receivers).
+ *
+ * @author Pascal Christoph(dr0i)
+ *
+ */
+public final class ObjectThreaderTest {
+
+	@Mock
+	private ObjectReceiver<String> receiverThread1;
+	@Mock
+	private ObjectReceiver<String> receiverThread2;
+
+	private final ObjectThreader<String> objectThreader = new ObjectThreader<>();
+	private static final int ACTIVE_THREADS_AT_BEGINNING = Thread.getAllStackTraces().keySet().size();
+
+	@Before
+	public void setup() {
+		MockitoAnnotations.initMocks(this);
+		objectThreader//
+				.addReceiver(receiverThread1)//
+				.addReceiver(receiverThread2);
+	}
+
+	@Test
+	public void shouldSplitAllObjectsToAllThreadedDownStreamReceivers() throws InterruptedException {
+		objectThreader.process("a");
+		objectThreader.process("b");
+		objectThreader.process("a");
+		objectThreader.process("c");
+		// check if two more threads were indeed created
+		assert (Thread.getAllStackTraces().keySet().size() - ACTIVE_THREADS_AT_BEGINNING == 2);
+		objectThreader.closeStream();
+		// verify thread 1
+		verify(receiverThread1, atLeast(2)).process("a");
+		verify(receiverThread1, atMost(0)).process("b");
+		verify(receiverThread1, atMost(0)).process("c");
+		// verify thread 2
+		verify(receiverThread2, atMost(0)).process("a");
+		verify(receiverThread2, atLeast(1)).process("b");
+		verify(receiverThread2, atLeast(1)).process("c");
+	}
+
+}

metafacture-framework/src/main/java/org/metafacture/framework/helpers/DefaultTee.java

@@ -35,7 +35,7 @@ public class DefaultTee<T extends Receiver> implements Tee<T> {
     private final List<T> receivers = new ArrayList<T>();
 
     @Override
-    public final <R extends T> R setReceiver(final R receiver) {
+    public <R extends T> R setReceiver(final R receiver) {
         receivers.clear();
         receivers.add(receiver);
         onChangeReceivers();
@@ -52,7 +52,7 @@ public final <R extends T> R setReceivers(final R receiver, final T lateralRecei
     }
 
     @Override
-    public final Tee<T> addReceiver(final T receiver) {
+    public Tee<T> addReceiver(final T receiver) {
         receivers.add(receiver);
         onChangeReceivers();
         return this;