Repository: incubator-htrace Updated Branches: refs/heads/master 51dbeb835 -> b190d9ac4
HTRACE-232. Make htrace4-core work with the new Javadoc lint standards in jdk8 (cmccabe) Project: http://git-wip-us.apache.org/repos/asf/incubator-htrace/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-htrace/commit/b190d9ac Tree: http://git-wip-us.apache.org/repos/asf/incubator-htrace/tree/b190d9ac Diff: http://git-wip-us.apache.org/repos/asf/incubator-htrace/diff/b190d9ac Branch: refs/heads/master Commit: b190d9ac409e7f0f5bb36f63052f98053ab669cf Parents: 51dbeb8 Author: Colin P. Mccabe <[email protected]> Authored: Tue Apr 12 15:33:34 2016 -0700 Committer: Colin P. Mccabe <[email protected]> Committed: Wed Apr 13 11:52:50 2016 -0700 ---------------------------------------------------------------------- .../java/org/apache/htrace/core/Sampler.java | 12 ++-- .../main/java/org/apache/htrace/core/Span.java | 67 +++++++++++++------- .../org/apache/htrace/core/SpanReceiver.java | 15 +++-- .../java/org/apache/htrace/core/TraceScope.java | 4 ++ .../java/org/apache/htrace/core/Tracer.java | 31 +++++++-- .../java/org/apache/htrace/core/TracerId.java | 24 +++---- .../java/org/apache/htrace/core/TracerPool.java | 8 +++ htrace-flume/pom.xml | 3 + htrace-hbase/pom.xml | 3 + htrace-htraced/pom.xml | 3 + htrace-zipkin/pom.xml | 3 + pom.xml | 3 - 12 files changed, 124 insertions(+), 52 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/Sampler.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/Sampler.java b/htrace-core4/src/main/java/org/apache/htrace/core/Sampler.java index af0165c..7ae2bcf 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/Sampler.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/Sampler.java @@ -22,11 +22,10 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; /** - * Extremely simple callback to determine the frequency that an action should be - * performed. - * <p/> - * For example, the next() function may look like this: - * <p/> + * Extremely simple callback to determine the frequency that an action should + * be performed. + * + * <p>For example, the next() function may look like this:</p> * <pre> * <code> * public boolean next() { @@ -34,7 +33,8 @@ import org.apache.commons.logging.LogFactory; * } * </code> * </pre> - * This would trace 50% of all gets, 75% of all puts and would not trace any other requests. + * <p>This would trace 50% of all gets, 75% of all puts and would not trace any + * other requests.</p> */ public abstract class Sampler { /** http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/Span.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/Span.java b/htrace-core4/src/main/java/org/apache/htrace/core/Span.java index 33908db..4399259 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/Span.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/Span.java @@ -29,10 +29,10 @@ import com.fasterxml.jackson.databind.annotation.JsonSerialize; /** * Base interface for gathering and reporting statistics about a block of * execution. - * <p/> - * Spans should form a directed acyclic graph structure. It should be possible - * to keep following the parents of a span until you arrive at a span with no - * parents.<p/> + * + * <p>Spans should form a directed acyclic graph structure. It should be + * possible to keep following the parents of a span until you arrive at a + * span with no parents.</p> */ @JsonSerialize(using = Span.SpanSerializer.class) public interface Span { @@ -42,44 +42,53 @@ public interface Span { void stop(); /** - * Get the start time, in milliseconds + * Get the span start time. + * + * @return The start time, in approximate milliseconds since the epoch. */ long getStartTimeMillis(); /** - * Get the stop time, in milliseconds + * Get the span stop time. + * + * @return The stop time, in approximate milliseconds since the epoch. */ long getStopTimeMillis(); /** * Return the total amount of time elapsed since start was called, if running, * or difference between stop and start + * + * @return The elapsed time in milliseconds. */ long getAccumulatedMillis(); /** * Has the span been started and not yet stopped? + * + * @return True if the span is still running (has no stop time). */ boolean isRunning(); /** - * Return a textual description of this span.<p/> + * Return a textual description of this span. * - * Will never be null. + * @return The description of this span. Will never be null. */ String getDescription(); /** - * A pseudo-unique (random) number assigned to this span instance.<p/> + * A pseudo-unique (random) number assigned to this span instance. * - * The spanId is immutable and cannot be changed. It is safe to access this - * from multiple threads. + * @return The spanID. This object is immutable and is safe to access + * from multiple threads. */ SpanId getSpanId(); /** * Create a child span of this span with the given description * @deprecated Since 4.0.0. Use {@link MilliSpan.Builder} + * @return A new child span. */ @Deprecated Span child(String description); @@ -88,57 +97,71 @@ public interface Span { String toString(); /** - * Returns the parent IDs of the span.<p/> + * Returns the parent IDs of the span. * - * The array will be empty if there are no parents. + * @return The array of parents, or an empty array if there are no parents. */ SpanId[] getParents(); /** - * Set the parents of this span.<p/> + * Set the parents of this span. * - * Any existing parents will be cleared by this call. + * <p>Any existing parents will be cleared by this call.</p> + * + * @param parents The parents to set. */ void setParents(SpanId[] parents); /** * Add a data annotation associated with this span + * + * @param key The key to set. + * @param value The value to set. */ void addKVAnnotation(String key, String value); /** * Add a timeline annotation associated with this span + * + * @param msg The annotation to set. It will be associated with + * the current time. */ void addTimelineAnnotation(String msg); /** - * Get data associated with this span (read only)<p/> + * Get the key-value annotations associated with this span. * - * Will never be null. + * @return The annotation map in read-only form. + * Will never be null. */ Map<String, String> getKVAnnotations(); /** - * Get any timeline annotations (read only)<p/> + * Get the timeline annotation list. * - * Will never be null. + * @return The annotation list in read-only form. + * Will never be null. */ List<TimelineAnnotation> getTimelineAnnotations(); /** - * Return a unique id for the process from which this Span originated.<p/> + * Return a unique id for the process from which this Span originated. * - * Will never be null. + * @return The tracer id. Will never be null. */ String getTracerId(); /** - * Set the process id of a span. + * Set the tracer id of a span. + * + * @param s The tracer ID to set. */ void setTracerId(String s); /** * Serialize to Json + * + * @return A JSON string with the span data. */ String toJson(); http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/SpanReceiver.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/SpanReceiver.java b/htrace-core4/src/main/java/org/apache/htrace/core/SpanReceiver.java index 026685e..a45ea09 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/SpanReceiver.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/SpanReceiver.java @@ -24,9 +24,10 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; /** - * 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> + * 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 + * * <pre> * <code>public SpanReceiverImpl(HTraceConfiguration)</code> * </pre> @@ -68,6 +69,8 @@ public abstract class SpanReceiver implements Closeable { /** * Configure whether we should log errors during build(). + * + * @param logErrors Whether we should log errors during build(). * @return This instance */ public Builder logErrors(boolean logErrors) { @@ -147,7 +150,9 @@ public abstract class SpanReceiver implements Closeable { private static final AtomicLong HIGHEST_SPAN_RECEIVER_ID = new AtomicLong(0); /** - * Get an ID uniquely identifying this SpanReceiver. + * Get the ID for this SpanReceiver. + * + * @return The unique ID identifying this SpanReceiver. */ public final long getId() { return id; @@ -159,6 +164,8 @@ public abstract class SpanReceiver implements Closeable { /** * Called when a Span is stopped and can now be stored. + * + * @param span The span to store with this SpanReceiver. */ public abstract void receiveSpan(Span span); } http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/TraceScope.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/TraceScope.java b/htrace-core4/src/main/java/org/apache/htrace/core/TraceScope.java index 05a053e..33a0b0b 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/TraceScope.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/TraceScope.java @@ -53,6 +53,8 @@ public class TraceScope implements Closeable { /** * Returns the span which this scope is managing. + * + * @return The span. */ public Span getSpan() { return span; @@ -60,6 +62,8 @@ public class TraceScope implements Closeable { /** * Returns the span ID which this scope is managing. + * + * @return The span ID. */ public SpanId getSpanId() { return span.getSpanId(); http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java b/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java index 29fd14e..9a5b04e 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java @@ -33,8 +33,6 @@ import org.apache.commons.logging.LogFactory; * Use a Tracer instance inside a 'process' to collect and distribute its trace Spans. * Example processes are an HDFS DataNode or an HBase RegionServer. A Tracer instance is your * one-stop shop for all things tracing. - * - * <p> */ public class Tracer implements Closeable { private static final Log LOG = LogFactory.getLog(Tracer.class); @@ -61,8 +59,8 @@ public class Tracer implements Closeable { } /** - * @param name - * @return This + * @param name The name of the Tracer to create. + * @return this * @deprecated Since 4.0.0. Use Constructor that takes a <code>name</code> argument instead. */ @Deprecated @@ -71,11 +69,19 @@ public class Tracer implements Closeable { return this; } + /** + * @param conf The configuration to set. + * @return this + */ public Builder conf(HTraceConfiguration conf) { this.conf = conf; return this; } + /** + * @param tracerPool The pool to set. + * @return this + */ public Builder tracerPool(TracerPool tracerPool) { this.tracerPool = tracerPool; return this; @@ -150,6 +156,9 @@ public class Tracer implements Closeable { return cleanedClassNames; } + /** + * @return The new Tracer object. + */ public Tracer build() { if (name == null) { throw new RuntimeException("You must specify a name for this Tracer."); @@ -414,6 +423,8 @@ public class Tracer implements Closeable { /** * Return a null trace scope. + * + * @return The null trace scope. */ public TraceScope newNullScope() { ThreadContext context = threadContext.get(); @@ -424,6 +435,10 @@ public class Tracer implements Closeable { /** * Wrap the callable in a TraceCallable, if tracing. * + * @param <V> The subclass of callable. + * @param callable The callable to wrap. + * @param description A description of the callable, or null if there + * is no description. * @return The callable provided, wrapped if tracing, 'callable' if not. */ public <V> Callable<V> wrap(Callable<V> callable, String description) { @@ -437,6 +452,9 @@ public class Tracer implements Closeable { /** * Wrap the runnable in a TraceRunnable, if tracing * + * @param runnable The runnable to wrap. + * @param description A description of the runnable, or null if there is + * no description. * @return The runnable provided, wrapped if tracing, 'runnable' if not. */ public Runnable wrap(Runnable runnable, String description) { @@ -500,6 +518,8 @@ public class Tracer implements Closeable { * * Note that if the current Samplers change, those changes will not be * reflected in this array. In other words, this array may be stale. + * + * @return The current samplers. */ public Sampler[] getSamplers() { return curSamplers; @@ -534,9 +554,10 @@ public class Tracer implements Closeable { } /** - * Remove a SpanReceiver. + * Remove a Sampler. * * @param sampler The sampler to remove. + * @return True only if the sampler was removed. */ public synchronized boolean removeSampler(Sampler sampler) { if (tracerPool == null) { http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/TracerId.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/TracerId.java b/htrace-core4/src/main/java/org/apache/htrace/core/TracerId.java index da482fe..d52b464 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/TracerId.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/TracerId.java @@ -31,22 +31,22 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; /** - * The HTrace tracer ID.<p/> + * <p>The HTrace tracer ID.</p> * - * HTrace tracer IDs are created from format strings. + * <p>HTrace tracer IDs are created from format strings. * Format strings contain variables which the TracerId class will - * replace with the correct values at runtime.<p/> + * replace with the correct values at runtime.</p> * * <ul> * <li>%{tname}: the tracer name supplied when creating the Tracer.</li> * <li>%{pname}: the process name obtained from the JVM.</li> * <li>%{ip}: will be replaced with an ip address.</li> * <li>%{pid}: the numerical process ID from the operating system.</li> - * </ul><p/> + * </ul> * - * For example, the string "%{pname}/%{ip}" will be replaced with something + * <p>For example, the string "%{pname}/%{ip}" will be replaced with something * like: DataNode/192.168.0.1, assuming that the process' name is DataNode - * and its IP address is 192.168.0.1.<p/> + * and its IP address is 192.168.0.1.</p> * * ID strings can contain backslashes as escapes. * For example, "\a" will map to "a". "\%{ip}" will map to the literal @@ -162,7 +162,7 @@ public final class TracerId { } /** - * Get the best IP address that represents this node.<p/> + * <p>Get the best IP address that represents this node.</p> * * This is complicated since nodes can have multiple network interfaces, * and each network interface can have multiple IP addresses. What we're @@ -207,7 +207,7 @@ public final class TracerId { } /** - * Get the process id from the operating system.<p/> + * <p>Get the process id from the operating system.</p> * * Unfortunately, there is no simple method to get the process id in Java. * The approach we take here is to use the shell method (see @@ -226,8 +226,8 @@ public final class TracerId { } /** - * Get the process ID by executing a shell and printing the PPID (parent - * process ID).<p/> + * <p>Get the process ID by executing a shell and printing the PPID (parent + * process ID).</p> * * This method of getting the process ID doesn't depend on any undocumented * features of the virtual machine, and should work on almost any UNIX @@ -271,8 +271,8 @@ public final class TracerId { } /** - * Get the process ID by looking at the name of the managed bean for the - * runtime system of the Java virtual machine.<p/> + * <p>Get the process ID by looking at the name of the managed bean for the + * runtime system of the Java virtual machine.</p> * * Although this is undocumented, in the Oracle JVM this name is of the form * [OS_PROCESS_ID]@[HOSTNAME]. http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-core4/src/main/java/org/apache/htrace/core/TracerPool.java ---------------------------------------------------------------------- diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/TracerPool.java b/htrace-core4/src/main/java/org/apache/htrace/core/TracerPool.java index 26acc64..a183ace 100644 --- a/htrace-core4/src/main/java/org/apache/htrace/core/TracerPool.java +++ b/htrace-core4/src/main/java/org/apache/htrace/core/TracerPool.java @@ -83,6 +83,8 @@ public class TracerPool { /** * Get the global tracer pool. + * + * @return The tracer pool. */ public static TracerPool getGlobalTracerPool() { return GLOBAL; @@ -97,6 +99,8 @@ public class TracerPool { /** * Return the name of this TracerPool. + * + * @return The name. */ public String getName() { return name; @@ -107,6 +111,8 @@ public class TracerPool { * * Note that if the current span receivers change, those changes will not be * reflected in this array. In other words, this array may be stale. + * + * @return An array of the current span receivers. */ public SpanReceiver[] getReceivers() { return curReceivers; @@ -251,6 +257,8 @@ public class TracerPool { * * Note that if the current Tracers change, those changes will not be * reflected in this array. In other words, this array may be stale. + * + * @return The current array of tracers. */ public synchronized Tracer[] getTracers() { return curTracers.toArray(new Tracer[curTracers.size()]); http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-flume/pom.xml ---------------------------------------------------------------------- diff --git a/htrace-flume/pom.xml b/htrace-flume/pom.xml index c9e1834..0e79d5a 100644 --- a/htrace-flume/pom.xml +++ b/htrace-flume/pom.xml @@ -47,6 +47,9 @@ language governing permissions and limitations under the License. --> </plugin> <plugin> <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <additionalparam>-Xdoclint:none</additionalparam> + </configuration> </plugin> <plugin> <artifactId>maven-compiler-plugin</artifactId> http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-hbase/pom.xml ---------------------------------------------------------------------- diff --git a/htrace-hbase/pom.xml b/htrace-hbase/pom.xml index 549f651..f021dd0 100644 --- a/htrace-hbase/pom.xml +++ b/htrace-hbase/pom.xml @@ -102,6 +102,9 @@ language governing permissions and limitations under the License. --> </plugin> <plugin> <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <additionalparam>-Xdoclint:none</additionalparam> + </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-htraced/pom.xml ---------------------------------------------------------------------- diff --git a/htrace-htraced/pom.xml b/htrace-htraced/pom.xml index b67af6d..1724953 100644 --- a/htrace-htraced/pom.xml +++ b/htrace-htraced/pom.xml @@ -39,6 +39,9 @@ language governing permissions and limitations under the License. --> </plugin> <plugin> <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <additionalparam>-Xdoclint:none</additionalparam> + </configuration> </plugin> <plugin> <artifactId>maven-compiler-plugin</artifactId> http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/htrace-zipkin/pom.xml ---------------------------------------------------------------------- diff --git a/htrace-zipkin/pom.xml b/htrace-zipkin/pom.xml index 44424ff..f9ceeb5 100644 --- a/htrace-zipkin/pom.xml +++ b/htrace-zipkin/pom.xml @@ -48,6 +48,9 @@ language governing permissions and limitations under the License. --> </plugin> <plugin> <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <additionalparam>-Xdoclint:none</additionalparam> + </configuration> </plugin> <plugin> <artifactId>maven-compiler-plugin</artifactId> http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/b190d9ac/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index aaa8930..786a56f 100644 --- a/pom.xml +++ b/pom.xml @@ -365,9 +365,6 @@ language governing permissions and limitations under the License. --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> - <configuration> - <additionalparam>-Xdoclint:none</additionalparam> - </configuration> </plugin> </plugins> </build>
