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 <[email protected]> Authored: Fri Jan 9 10:42:44 2015 -0800 Committer: Nick Dimiduk <[email protected]> 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> {
