You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@htrace.apache.org by nd...@apache.org on 2015/01/10 00:46:39 UTC
incubator-htrace git commit: HTRACE-63 Add/Improve javadocs around
user-facing APIs
Repository: incubator-htrace
Updated Branches:
refs/heads/master 10ecbbd96 -> 36e1b0060
HTRACE-63 Add/Improve javadocs around user-facing APIs
Project: http://git-wip-us.apache.org/repos/asf/incubator-htrace/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-htrace/commit/36e1b006
Tree: http://git-wip-us.apache.org/repos/asf/incubator-htrace/tree/36e1b006
Diff: http://git-wip-us.apache.org/repos/asf/incubator-htrace/diff/36e1b006
Branch: refs/heads/master
Commit: 36e1b0060a1c4547ce63321212625e69a2c62da1
Parents: 10ecbbd
Author: Nick Dimiduk <nd...@gmail.com>
Authored: Fri Jan 9 10:42:44 2015 -0800
Committer: Nick Dimiduk <nd...@gmail.com>
Committed: Fri Jan 9 15:42:46 2015 -0800
----------------------------------------------------------------------
.../main/java/org/apache/htrace/Sampler.java | 23 +++++++++++---------
.../java/org/apache/htrace/SamplerBuilder.java | 14 ++++++++++--
.../java/org/apache/htrace/SpanReceiver.java | 13 +++++++----
.../org/apache/htrace/SpanReceiverBuilder.java | 17 +++++++++++----
.../org/apache/htrace/impl/AlwaysSampler.java | 3 +++
.../org/apache/htrace/impl/CountSampler.java | 5 +++--
.../org/apache/htrace/impl/NeverSampler.java | 3 +++
.../apache/htrace/impl/ProbabilitySampler.java | 6 ++++-
.../htrace/impl/TrueIfTracingSampler.java | 2 +-
9 files changed, 62 insertions(+), 24 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/Sampler.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/Sampler.java b/htrace-core/src/main/java/org/apache/htrace/Sampler.java
index 9f81e14..45d8872 100644
--- a/htrace-core/src/main/java/org/apache/htrace/Sampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/Sampler.java
@@ -31,17 +31,20 @@ import org.apache.htrace.impl.NeverSampler;
* <p/>
* For the example above, the next(T info) function may look like this
* <p/>
- * public boolean next(T info){
- * if (info == null) {
- * return false;
- * } else if (info.getName().equals("get")) {
- * return Math.random() > 0.5;
- * } else if (info.getName().equals("put")) {
- * return Math.random() > 0.25;
- * } else {
- * return false;
- * }
+ * <pre>
+ * <code>public boolean next(T info) {
+ * if (info == null) {
+ * return false;
+ * } else if (info.getName().equals("get")) {
+ * return Math.random() > 0.5;
+ * } else if (info.getName().equals("put")) {
+ * return Math.random() > 0.25;
+ * } else {
+ * return false;
+ * }
* }
+ * </code>
+ * </pre>
* This would trace 50% of all gets, 75% of all puts and would not trace any other requests.
*/
public interface Sampler<T> {
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java b/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
index 614a190..5d90e48 100644
--- a/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
+++ b/htrace-core/src/main/java/org/apache/htrace/SamplerBuilder.java
@@ -22,8 +22,18 @@ import org.apache.commons.logging.LogFactory;
import org.apache.htrace.impl.AlwaysSampler;
import org.apache.htrace.impl.NeverSampler;
+/**
+ * A {@link Sampler} builder. It reads a {@link Sampler} class name from the provided
+ * configuration using the {@link #SAMPLER_CONF_KEY} key. Unqualified class names
+ * are interpreted as members of the {@code org.apache.htrace.impl} package. The {@link #build()}
+ * method constructs an instance of that class, initialized with the same configuration.
+ */
public class SamplerBuilder {
- private final static String SAMPLER_CONF_KEY = "sampler";
+
+ // TODO: should follow the same API as SpanReceiverBuilder
+
+ public final static String SAMPLER_CONF_KEY = "sampler";
+ private final static String DEFAULT_PACKAGE = "org.apache.htrace.impl";
private final static ClassLoader classLoader =
SamplerBuilder.class.getClassLoader();
private final HTraceConfiguration conf;
@@ -39,7 +49,7 @@ public class SamplerBuilder {
return NeverSampler.INSTANCE;
}
if (!str.contains(".")) {
- str = "org.apache.htrace.impl." + str;
+ str = DEFAULT_PACKAGE + "." + str;
}
Class cls = null;
try {
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java b/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
index 22e8426..7ae157b 100644
--- a/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
+++ b/htrace-core/src/main/java/org/apache/htrace/SpanReceiver.java
@@ -21,14 +21,19 @@ import java.io.Closeable;
/**
- * The collector within a process that is the destination of Spans when a trace
- * is running.
+ * The collector within a process that is the destination of Spans when a trace is running.
+ * {@code SpanReceiver} implementations are expected to provide a constructor with the signature
+ * <p>
+ * <pre>
+ * <code>public SpanReceiverImpl(HTraceConfiguration)</code>
+ * </pre>
+ * The helper class {@link org.apache.htrace.SpanReceiverBuilder} provides convenient factory
+ * methods for creating {@code SpanReceiver} instances from configuration.
+ * @see org.apache.htrace.SpanReceiverBuilder
*/
public interface SpanReceiver extends Closeable {
/**
* Called when a Span is stopped and can now be stored.
- *
- * @param span
*/
public void receiveSpan(Span span);
}
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java b/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
index 45d2872..cf6b050 100644
--- a/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
+++ b/htrace-core/src/main/java/org/apache/htrace/SpanReceiverBuilder.java
@@ -21,13 +21,16 @@ import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
- * A {@link SpanReceiver} builder. It defaults finding class of span receiver to build in
- * the passed in configuration using the {@link #SPAN_RECEIVER_CONF_KEY} key.
+ * A {@link SpanReceiver} builder. It reads a {@link SpanReceiver} class name from the provided
+ * configuration using the {@link #SPAN_RECEIVER_CONF_KEY} key. Unqualified class names
+ * are interpreted as members of the {@code org.apache.htrace.impl} package. The {@link #build()}
+ * method constructs an instance of that class, initialized with the same configuration.
*/
public class SpanReceiverBuilder {
static final Log LOG = LogFactory.getLog(SpanReceiverBuilder.class);
public final static String SPAN_RECEIVER_CONF_KEY = "span.receiver";
+ private final static String DEFAULT_PACKAGE = "org.apache.htrace.impl";
private final static ClassLoader classLoader =
SpanReceiverBuilder.class.getClassLoader();
private final HTraceConfiguration conf;
@@ -40,7 +43,8 @@ public class SpanReceiverBuilder {
}
/**
- * Set this builder back to defaults.
+ * Set this builder back to defaults. Any previous calls to {@link #spanReceiverClass(String)}
+ * are overridden by the value provided by configuration.
* @return This instance
*/
public SpanReceiverBuilder reset() {
@@ -49,6 +53,10 @@ public class SpanReceiverBuilder {
return this;
}
+ /**
+ * Override the {@code SpanReceiver} class name provided in configuration with a new value.
+ * @return This instance
+ */
public SpanReceiverBuilder spanReceiverClass(final String spanReceiverClass) {
this.spanReceiverClass = spanReceiverClass;
return this;
@@ -56,6 +64,7 @@ public class SpanReceiverBuilder {
/**
* Configure whether we should log errors during build().
+ * @return This instance
*/
public SpanReceiverBuilder logErrors(boolean logErrors) {
this.logErrors = logErrors;
@@ -83,7 +92,7 @@ public class SpanReceiverBuilder {
}
String str = spanReceiverClass;
if (!str.contains(".")) {
- str = "org.apache.htrace.impl." + str;
+ str = DEFAULT_PACKAGE + "." + str;
}
Class cls = null;
try {
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
index 69e3aff..7e0bf3b 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/AlwaysSampler.java
@@ -19,6 +19,9 @@ package org.apache.htrace.impl;
import org.apache.htrace.HTraceConfiguration;
import org.apache.htrace.Sampler;
+/**
+ * A Sampler that always returns true.
+ */
public final class AlwaysSampler implements Sampler<Object> {
public static final AlwaysSampler INSTANCE = new AlwaysSampler(null);
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
index 03b444b..fe98916 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/CountSampler.java
@@ -22,10 +22,11 @@ import org.apache.htrace.Sampler;
import java.util.Random;
/**
- * Sampler that returns true every N calls.
+ * Sampler that returns true every N calls. Specify the frequency interval by configuring a
+ * {@code long} value for {@link #SAMPLER_FREQUENCY_CONF_KEY}.
*/
public class CountSampler implements Sampler<Object> {
- private final static String SAMPLER_FREQUENCY_CONF_KEY = "sampler.frequency";
+ public final static String SAMPLER_FREQUENCY_CONF_KEY = "sampler.frequency";
final static Random random = new Random();
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
index 3ab192d..c633da7 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/NeverSampler.java
@@ -19,6 +19,9 @@ package org.apache.htrace.impl;
import org.apache.htrace.HTraceConfiguration;
import org.apache.htrace.Sampler;
+/**
+ * A Sampler that never returns true.
+ */
public final class NeverSampler implements Sampler<Object> {
public static final NeverSampler INSTANCE = new NeverSampler(null);
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
index c53d914..035a845 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/ProbabilitySampler.java
@@ -21,10 +21,14 @@ import org.apache.htrace.Sampler;
import java.util.Random;
+/**
+ * Sampler that returns true a certain percentage of the time. Specify the frequency interval by
+ * configuring a {@code double} value for {@link #SAMPLER_FRACTION_CONF_KEY}.
+ */
public class ProbabilitySampler implements Sampler<Object> {
public final double threshold;
private Random random = new Random();
- private final static String SAMPLER_FRACTION_CONF_KEY = "sampler.fraction";
+ public final static String SAMPLER_FRACTION_CONF_KEY = "sampler.fraction";
public ProbabilitySampler(HTraceConfiguration conf) {
this.threshold = Double.parseDouble(conf.get(SAMPLER_FRACTION_CONF_KEY));
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/36e1b006/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
----------------------------------------------------------------------
diff --git a/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java b/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
index 7be7fc9..433a325 100644
--- a/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
+++ b/htrace-core/src/main/java/org/apache/htrace/impl/TrueIfTracingSampler.java
@@ -21,7 +21,7 @@ import org.apache.htrace.Sampler;
import org.apache.htrace.Trace;
/**
- * A Sampler that returns true if and only if tracing is on the current thread.
+ * A Sampler that returns true if and only if tracing is enabled for the current thread.
*/
public class TrueIfTracingSampler implements Sampler<Object> {