htrace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cmcc...@apache.org
Subject incubator-htrace git commit: HTRACE-232. Make htrace4-core work with the new Javadoc lint standards in jdk8 (cmccabe)
Date Wed, 13 Apr 2016 18:53:12 GMT
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 <cmccabe@apache.org>
Authored: Tue Apr 12 15:33:34 2016 -0700
Committer: Colin P. Mccabe <cmccabe@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>


Mime
View raw message