You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@htrace.apache.org by cm...@apache.org on 2016/04/13 20:53:12 UTC
incubator-htrace git commit: HTRACE-232. Make htrace4-core work with
the new Javadoc lint standards in jdk8 (cmccabe)
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 <cm...@apache.org>
Authored: Tue Apr 12 15:33:34 2016 -0700
Committer: Colin P. Mccabe <cm...@apache.org>
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>