From 7fff8d6d02309184fc395c92501596d89b2c63fa Mon Sep 17 00:00:00 2001
From: Nelson Tavares de Sousa <stu103017@mail.uni-kiel.de>
Date: Thu, 16 Oct 2014 14:14:54 +0200
Subject: [PATCH] Added Javadoc to PipeFactoryRegistry and IPipeFactory
---
.../teetime/framework/pipe/IPipeFactory.java | 33 +++++++++++++-
.../framework/pipe/PipeFactoryRegistry.java | 44 ++++++++++++++-----
2 files changed, 63 insertions(+), 14 deletions(-)
diff --git a/src/main/java/teetime/framework/pipe/IPipeFactory.java b/src/main/java/teetime/framework/pipe/IPipeFactory.java
index 8ff43cae..8ed2378b 100644
--- a/src/main/java/teetime/framework/pipe/IPipeFactory.java
+++ b/src/main/java/teetime/framework/pipe/IPipeFactory.java
@@ -7,24 +7,53 @@ import teetime.framework.pipe.PipeFactoryRegistry.ThreadCommunication;
public interface IPipeFactory {
+ /**
+ * @deprecated Use {@link #create(OutputPort, InputPort)} or {@link #create(OutputPort, InputPort, int)} instead
+ *
+ * @param capacity
+ * Number of elements the pipe can carry
+ * @return instance of the created pipe
+ */
@Deprecated
IPipe create(int capacity);
/**
- * with the default capacity
+ * Connects two stages with a pipe of default capacity.
*
* @param sourcePort
+ * OutputPort of the stage, which produces data.
* @param targetPort
- * @return
+ * Input port of the receiving stage.
+ * @return The connecting pipe.
*/
<T> IPipe create(OutputPort<? extends T> sourcePort, InputPort<T> targetPort);
+ /**
+ * Connects two stages with a pipe.
+ *
+ * @param sourcePort
+ * OutputPort of the stage, which produces data.
+ * @param targetPort
+ * Input port of the receiving stage.
+ * @param capacity
+ * Number of elements the pipe can carry.
+ * @return The connecting pipe.
+ */
<T> IPipe create(OutputPort<? extends T> sourcePort, InputPort<T> targetPort, int capacity);
+ /**
+ * @return Type of ThreadCommunication, which is used by the created pipes.
+ */
ThreadCommunication getThreadCommunication();
+ /**
+ * @return Ordering type, which is used by the created pipes.
+ */
PipeOrdering getOrdering();
+ /**
+ * @return Wether or not the created pipes are growable
+ */
boolean isGrowable();
}
diff --git a/src/main/java/teetime/framework/pipe/PipeFactoryRegistry.java b/src/main/java/teetime/framework/pipe/PipeFactoryRegistry.java
index 2817b034..0ade0035 100644
--- a/src/main/java/teetime/framework/pipe/PipeFactoryRegistry.java
+++ b/src/main/java/teetime/framework/pipe/PipeFactoryRegistry.java
@@ -8,14 +8,27 @@ import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * Provides PipeFactories, which are used to connect stages.
+ * The instance of this singleton class is saved in <code>PipeFactoryRegistry.INSTANCE</code>.
+ * <p>
+ * To get a PipeFactory instance, call {@link #getPipeFactory(ThreadCommunication, PipeOrdering, boolean)}.
+ *
+ */
public class PipeFactoryRegistry {
private static final Logger LOGGER = LoggerFactory.getLogger(PipeFactoryRegistry.class);
+ /**
+ * Communication type between two connected stages
+ */
public enum ThreadCommunication {
INTER, INTRA
}
+ /**
+ * Specifies the ordering behavior of the pipe
+ */
public enum PipeOrdering {
/**
* FIFO
@@ -43,6 +56,16 @@ public class PipeFactoryRegistry {
}
}
+ /**
+ * @deprecated Use {@link IPipeFactory#create(OutputPort, InputPort, int)} instead,
+ * after obtaining a PipeFactory with {@link #getPipeFactory(ThreadCommunication, PipeOrdering, boolean)}.
+ *
+ * @param tc
+ * @param ordering
+ * @param growable
+ * @param capacity
+ * @return
+ */
@Deprecated
public IPipe create(final ThreadCommunication tc, final PipeOrdering ordering, final boolean growable, final int capacity) {
IPipeFactory pipeFactory = getPipeFactory(tc, ordering, growable);
@@ -50,16 +73,16 @@ public class PipeFactoryRegistry {
}
/**
- * Returns a PipeFactory Instance
+ * Returns a PipeFactory Instance.
*
* @param tc
- * Communication type between two connected stages
+ * Communication type between two connected stages. These are defined in PipeFactoryRegistry.ThreadCommunication
* @param ordering
- * Specifies the ordering behavior of the pipe
+ * Specifies the ordering behavior of the pipe. See PipeFactoryRegistry.PipeOrdering
* @param growable
- * Whether the queue size is fixed or not
+ * Whether the queue size is fixed or not.
* @return
- * A PipeFactory, which provides suitable pipes
+ * A PipeFactory, which provides suitable pipes.
*/
public IPipeFactory getPipeFactory(final ThreadCommunication tc, final PipeOrdering ordering, final boolean growable) {
String key = this.buildKey(tc, ordering, growable);
@@ -71,8 +94,12 @@ public class PipeFactoryRegistry {
}
/**
+ * Registers a new PipeFactory to the registry.<br />
+ * The new PipeFactory will be automatically selected by the Registry, if it is the most suitable Factory
+ * corresponding to the requirements.
*
* @param pipeFactory
+ * A PipeFactory which will be added to the registry
*/
public void register(final IPipeFactory pipeFactory) {
String key = this.buildKey(pipeFactory.getThreadCommunication(), pipeFactory.getOrdering(), pipeFactory.isGrowable());
@@ -80,13 +107,6 @@ public class PipeFactoryRegistry {
LOGGER.info("Registered pipe factory: " + pipeFactory.getClass().getCanonicalName());
}
- /**
- *
- * @param tc
- * @param ordering
- * @param growable
- * @return
- */
private String buildKey(final ThreadCommunication tc, final PipeOrdering ordering, final boolean growable) {
return tc.toString() + ordering.toString() + growable;
}
--
GitLab