Merge branch 'stable-2.13'

* stable-2.13:
  Metrics: Add missing Javadoc
  Lifecycle{Manager,Module}: Add missing Javadoc
  EventDispatcher: Add missing description on @throws javadoc
  {ExtendedHttp,Http,Rpc}AuditEvent: Add missing @param javadoc tags
  Fix formatting of links in Changes Submitted Together documentation
  Fix usage of OutgoingEmailValidator to make sure TLD override works
  Fix references to Guava classes from extension API Javadoc
  GarbageCollectorListener: Replace direct link to external class
  Prepare to render JGit references as links in api documentation
  Allow to provide URLs for docs of external classes
  Write each Lucene index using a dedicated background thread
  Do not allow index futures to be cancelled

Change-Id: I9bc732562efa903ff201be86d9fb8ac2226ed8e5

Documentation/rest-api-changes.txt

@@ -1237,13 +1237,13 @@ message is contained in the response body.
 ----
 
 [[submitted-together]]
-=== Changes submitted together
+=== Changes Submitted Together
 --
 'GET /changes/link:#change-id[\{change-id\}]/submitted_together?o=NON_VISIBLE_CHANGES'
 --
 
 Computes list of all changes which are submitted when
-link:#submit-change[\{submit\}] is called for this change,
+link:#submit-change[Submit] is called for this change,
 including the current change itself.
 
 The list consists of:
@@ -1270,10 +1270,10 @@ changes that are not visible to the caller that are part of the set of
 changes to be merged.
 
 The listed changes use the same format as in
-link:#list-changes[\{listing changes\}] with the options
-link:#labels[\{LABELS\}], link:#detailed-labels[\{DETAILED_LABELS\}],
-link:#current-revision[\{CURRENT_REVISION\}],
-link:#current-commit[\{CURRENT_COMMIT\}] set.
+link:#list-changes[Query Changes] with the
+link:#labels[`LABELS`], link:#detailed-labels[`DETAILED_LABELS`],
+link:#current-revision[`CURRENT_REVISION`], and
+link:#current-commit[`CURRENT_COMMIT`] options set.
 
 .Response
 ----
@@ -1723,7 +1723,7 @@ the `patch_set` field set, and no `author`.
 ----
 
 [[check-change]]
-=== Check change
+=== Check Change
 --
 'GET /changes/link:#change-id[\{change-id\}]/check'
 --
@@ -1773,7 +1773,7 @@ missing from the result. At least `id`, `project`, `branch`, and
 ----
 
 [[fix-change]]
-=== Fix change
+=== Fix Change
 --
 'POST /changes/link:#change-id[\{change-id\}]/check'
 --

gerrit-extension-api/BUCK

@@ -1,3 +1,6 @@
+include_defs('//lib/JGIT_VERSION')
+include_defs('//lib/GUAVA_VERSION')
+
 SRC = 'src/main/java/com/google/gerrit/extensions/'
 SRCS = glob([SRC + '**/*.java'])
 
@@ -82,4 +85,5 @@ java_doc(
     '//gerrit-common:annotations',
   ],
   visibility = ['PUBLIC'],
+  external_docs = [JGIT_DOC_URL, GUAVA_DOC_URL],
 )

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/events/GarbageCollectorListener.java

@@ -27,7 +27,7 @@ public interface GarbageCollectorListener {
     /**
      * @return Properties describing the result of the garbage collection
      *         performed by JGit.
-     * @see <a href="http://download.eclipse.org/jgit/site/3.7.0.201502260915-r/apidocs/org/eclipse/jgit/api/GarbageCollectCommand.html#call%28%29">GarbageCollectCommand</a>
+     * @see org.eclipse.jgit.api.GarbageCollectCommand#call()
      */
     Properties getStatistics();
   }

gerrit-server/src/main/java/com/google/gerrit/audit/ExtendedHttpAuditEvent.java

@@ -38,6 +38,8 @@ public class ExtendedHttpAuditEvent extends HttpAuditEvent {
    * @param httpRequest the HttpServletRequest
    * @param when time-stamp of when the event started
    * @param params parameters of the event
+   * @param input input
+   * @param status HTTP status
    * @param result result of the event
    * @param resource REST resource data
    * @param view view rendering object

gerrit-server/src/main/java/com/google/gerrit/audit/HttpAuditEvent.java

@@ -29,6 +29,9 @@ public class HttpAuditEvent extends AuditEvent {
    * @param what object of the event
    * @param when time-stamp of when the event started
    * @param params parameters of the event
+   * @param httpMethod HTTP method
+   * @param input input
+   * @param status HTTP status
    * @param result result of the event
    */
   public HttpAuditEvent(String sessionId, CurrentUser who, String what, long when,

gerrit-server/src/main/java/com/google/gerrit/audit/RpcAuditEvent.java

@@ -26,6 +26,9 @@ public class RpcAuditEvent extends HttpAuditEvent {
    * @param what object of the event
    * @param when time-stamp of when the event started
    * @param params parameters of the event
+   * @param httpMethod HTTP method
+   * @param input input
+   * @param status HTTP status
    * @param result result of the event
    */
   public RpcAuditEvent(String sessionId, CurrentUser who, String what,

gerrit-server/src/main/java/com/google/gerrit/common/EventDispatcher.java

@@ -31,10 +31,9 @@ public interface EventDispatcher {
    *
    * @param change The change that the event is related to
    * @param event The event to post
-   * @throws OrmException
+   * @throws OrmException on failure to post the event due to DB error
    */
-  void postEvent(Change change, ChangeEvent event)
-      throws OrmException;
+  void postEvent(Change change, ChangeEvent event) throws OrmException;
 
   /**
    * Post a stream event that is related to a branch
@@ -60,6 +59,7 @@ public interface EventDispatcher {
    * for those use cases.
    *
    * @param event The event to post.
+   * @throws OrmException on failure to post the event due to DB error
    */
   void postEvent(Event event) throws OrmException;
 }

gerrit-server/src/main/java/com/google/gerrit/lifecycle/LifecycleManager.java

@@ -36,22 +36,34 @@ public class LifecycleManager {
   /** Index of the last listener to start successfully; -1 when not started. */
   private int startedIndex = -1;
 
-  /** Add a handle that must be cleared during stop. */
+  /** Add a handle that must be cleared during stop.
+   *
+   * @param handle the handle to add.
+   **/
   public void add(RegistrationHandle handle) {
     handles.add(handle);
   }
 
-  /** Add a single listener. */
+  /** Add a single listener.
+   *
+   * @param listener the listener to add.
+   **/
   public void add(LifecycleListener listener) {
     listeners.add(Providers.of(listener));
   }
 
-  /** Add a single listener. */
+  /** Add a single listener.
+   *
+   * @param listener the listener to add.
+   **/
   public void add(Provider<LifecycleListener> listener) {
     listeners.add(listener);
   }
 
-  /** Add all {@link LifecycleListener}s registered in the Injector. */
+  /** Add all {@link LifecycleListener}s registered in the Injector.
+   *
+   * @param injector the injector to add.
+   **/
   public void add(Injector injector) {
     Preconditions.checkState(startedIndex < 0, "Already started");
     for (Binding<LifecycleListener> binding : get(injector)) {
@@ -59,7 +71,10 @@ public class LifecycleManager {
     }
   }
 
-  /** Add all {@link LifecycleListener}s registered in the Injectors. */
+  /** Add all {@link LifecycleListener}s registered in the Injectors.
+   *
+   * @param injectors the injectors to add.
+   **/
   public void add(Injector... injectors) {
     for (Injector i : injectors) {
       add(i);

gerrit-server/src/main/java/com/google/gerrit/lifecycle/LifecycleModule.java

@@ -11,7 +11,7 @@ import java.lang.annotation.Annotation;
 /** Module to support registering a unique LifecyleListener. */
 public abstract class LifecycleModule extends FactoryModule {
   /**
-   * Create a unique listener binding.
+   * @return a unique listener binding.
    * <p>
    * To create a listener binding use:
    *

gerrit-server/src/main/java/com/google/gerrit/metrics/CallbackMetric1.java

@@ -29,7 +29,11 @@ public abstract class CallbackMetric1<F1, V> implements CallbackMetric<V> {
    */
   public abstract void set(F1 field1, V value);
 
-  /** Ensure a zeroed metric is created for the field value. */
+  /**
+   * Ensure a zeroed metric is created for the field value.
+   *
+   * @param field1 bucket to create.
+   */
   public abstract void forceCreate(F1 field1);
 
   /** Prune any submetrics that were not assigned during this trigger. */

gerrit-server/src/main/java/com/google/gerrit/metrics/Counter1.java

@@ -29,7 +29,11 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * @param <F1> type of the field.
  */
 public abstract class Counter1<F1> implements RegistrationHandle {
-  /** Increment the counter by one event. */
+  /**
+   * Increment the counter by one event.
+   *
+   * @param field1 bucket to increment.
+   */
   public void increment(F1 field1) {
     incrementBy(field1, 1);
   }

gerrit-server/src/main/java/com/google/gerrit/metrics/Counter2.java

@@ -30,7 +30,12 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * @param <F2> type of the field.
  */
 public abstract class Counter2<F1, F2> implements RegistrationHandle {
-  /** Increment the counter by one event. */
+  /**
+   * Increment the counter by one event.
+   *
+   * @param field1 bucket to increment.
+   * @param field2 bucket to increment.
+   */
   public void increment(F1 field1, F2 field2) {
     incrementBy(field1, field2, 1);
   }

gerrit-server/src/main/java/com/google/gerrit/metrics/Counter3.java

@@ -31,7 +31,13 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * @param <F3> type of the field.
  */
 public abstract class Counter3<F1, F2, F3> implements RegistrationHandle {
-  /** Increment the counter by one event. */
+  /**
+   * Increment the counter by one event.
+   *
+   * @param field1 bucket to increment.
+   * @param field2 bucket to increment.
+   * @param field3 bucket to increment.
+   */
   public void increment(F1 field1, F2 field2, F3 field3) {
     incrementBy(field1, field2, field3, 1);
   }

gerrit-server/src/main/java/com/google/gerrit/metrics/Description.java

@@ -71,7 +71,11 @@ public class Description {
     annotations.put(DESCRIPTION, helpText);
   }
 
-  /** Unit used to describe the value, e.g. "requests", "seconds", etc. */
+  /** Set unit used to describe the value.
+   *
+   * @param unitName name of the unit, e.g. "requests", "seconds", etc.
+   * @return this
+   */
   public Description setUnit(String unitName) {
     annotations.put(UNIT, unitName);
     return this;
@@ -81,6 +85,8 @@ public class Description {
    * Mark the value as constant for the life of this process. Typically used for
    * software versions, command line arguments, etc. that cannot change without
    * a process restart.
+   *
+   * @return this
    */
   public Description setConstant() {
     annotations.put(CONSTANT, TRUE_VALUE);
@@ -91,6 +97,8 @@ public class Description {
    * Indicates the metric may be usefully interpreted as a count over short
    * periods of time, such as request arrival rate. May only be applied to a
    * {@link Counter0}.
+   *
+   * @return this
    */
   public Description setRate() {
     annotations.put(RATE, TRUE_VALUE);
@@ -100,6 +108,8 @@ public class Description {
   /**
    * Instantaneously sampled value that may increase or decrease at a later
    * time. Memory allocated or open network connections are examples of gauges.
+   *
+   * @return this
    */
   public Description setGauge() {
     annotations.put(GAUGE, TRUE_VALUE);
@@ -110,39 +120,46 @@ public class Description {
    * Indicates the metric accumulates over the lifespan of the process. A
    * {@link Counter0} like total requests handled accumulates over the process
    * and should be {@code setCumulative()}.
+   *
+   * @return this
    */
   public Description setCumulative() {
     annotations.put(CUMULATIVE, TRUE_VALUE);
     return this;
   }
 
-  /** Configure how fields are ordered into submetric names. */
+  /**
+   * Configure how fields are ordered into submetric names.
+   *
+   * @param ordering field ordering
+   * @return this
+   */
   public Description setFieldOrdering(FieldOrdering ordering) {
     annotations.put(FIELD_ORDERING, ordering.name());
     return this;
   }
 
-  /** True if the metric value never changes after startup. */
+  /** @return true if the metric value never changes after startup. */
   public boolean isConstant() {
     return TRUE_VALUE.equals(annotations.get(CONSTANT));
   }
 
-  /** True if the metric may be interpreted as a rate over time. */
+  /** @return true if the metric may be interpreted as a rate over time. */
   public boolean isRate() {
     return TRUE_VALUE.equals(annotations.get(RATE));
   }
 
-  /** True if the metric is an instantaneous sample. */
+  /** @return true if the metric is an instantaneous sample. */
   public boolean isGauge() {
     return TRUE_VALUE.equals(annotations.get(GAUGE));
   }
 
-  /** True if the metric accumulates over the lifespan of the process. */
+  /** @return true if the metric accumulates over the lifespan of the process. */
   public boolean isCumulative() {
     return TRUE_VALUE.equals(annotations.get(CUMULATIVE));
   }
 
-  /** Get the suggested field ordering. */
+  /** @return the suggested field ordering. */
   public FieldOrdering getFieldOrdering() {
     String o = annotations.get(FIELD_ORDERING);
     return o != null ? FieldOrdering.valueOf(o) : FieldOrdering.AT_END;
@@ -176,7 +193,7 @@ public class Description {
     return u;
   }
 
-  /** Immutable copy of all annotations (configurable properties). */
+  /** @return immutable copy of all annotations (configurable properties). */
   public ImmutableMap<String, String> getAnnotations() {
     return ImmutableMap.copyOf(annotations);
   }

gerrit-server/src/main/java/com/google/gerrit/metrics/Field.java

@@ -19,25 +19,53 @@ import static com.google.common.base.Preconditions.checkArgument;
 import com.google.common.base.Function;
 import com.google.common.base.Functions;
 
-/** Describes a bucketing field used by a metric. */
+/**
+ * Describes a bucketing field used by a metric.
+ *
+ * @param <T> type of field
+ */
 public class Field<T> {
-  /** Break down metrics by boolean true/false. */
+  /**
+   * Break down metrics by boolean true/false.
+   *
+   * @param name field name
+   * @return boolean field
+   */
   public static Field<Boolean> ofBoolean(String name) {
     return ofBoolean(name, null);
   }
 
-  /** Break down metrics by boolean true/false. */
+  /**
+   * Break down metrics by boolean true/false.
+   *
+   * @param name field name
+   * @param description field description
+   * @return boolean field
+   */
   public static Field<Boolean> ofBoolean(String name, String description) {
     return new Field<>(name, Boolean.class, description);
   }
 
-  /** Break down metrics by cases of an enum. */
+  /**
+   * Break down metrics by cases of an enum.
+   *
+   * @param enumType type of enum
+   * @param name field name
+   * @return enum field
+   */
   public static <E extends Enum<E>> Field<E> ofEnum(Class<E> enumType,
       String name) {
     return ofEnum(enumType, name, null);
   }
 
-  /** Break down metrics by cases of an enum. */
+  /**
+   * Break down metrics by cases of an enum.
+   *
+   * @param enumType type of enum
+   * @param name field name
+   * @param description field description
+   * @return enum field
+   */
   public static <E extends Enum<E>> Field<E> ofEnum(Class<E> enumType,
       String name, String description) {
     return new Field<>(name, enumType, description);
@@ -48,6 +76,9 @@ public class Field<T> {
    * <p>
    * Each unique string will allocate a new submetric. <b>Do not use user
    * content as a field value</b> as field values are never reclaimed.
+   *
+   * @param name field name
+   * @return string field
    */
   public static Field<String> ofString(String name) {
     return ofString(name, null);
@@ -58,6 +89,10 @@ public class Field<T> {
    * <p>
    * Each unique string will allocate a new submetric. <b>Do not use user
    * content as a field value</b> as field values are never reclaimed.
+   *
+   * @param name field name
+   * @param description field description
+   * @return string field
    */
   public static Field<String> ofString(String name, String description) {
     return new Field<>(name, String.class, description);
@@ -68,6 +103,9 @@ public class Field<T> {
    * <p>
    * Each unique integer will allocate a new submetric. <b>Do not use user
    * content as a field value</b> as field values are never reclaimed.
+   *
+   * @param name field name
+   * @return integer field
    */
   public static Field<Integer> ofInteger(String name) {
     return ofInteger(name, null);
@@ -78,6 +116,10 @@ public class Field<T> {
    * <p>
    * Each unique integer will allocate a new submetric. <b>Do not use user
    * content as a field value</b> as field values are never reclaimed.
+   *
+   * @param name field name
+   * @param description field description
+   * @return integer field
    */
   public static Field<Integer> ofInteger(String name, String description) {
     return new Field<>(name, Integer.class, description);
@@ -96,17 +138,17 @@ public class Field<T> {
     this.description = description;
   }
 
-  /** Name of this field within the metric. */
+  /** @return name of this field within the metric. */
   public String getName() {
     return name;
   }
 
-  /** Type of value used within the field. */
+  /** @return type of value used within the field. */
   public Class<T> getType() {
     return keyType;
   }
 
-  /** Description text for the field explaining its range of values. */
+  /** @return description text for the field explaining its range of values. */
   public String getDescription() {
     return description;
   }

gerrit-server/src/main/java/com/google/gerrit/metrics/Histogram0.java

@@ -22,6 +22,10 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * Suitable uses are "response size in bytes", etc.
  */
 public abstract class Histogram0 implements RegistrationHandle {
-  /** Record a sample of a specified amount. */
+  /**
+   * Record a sample of a specified amount.
+   *
+   * @param value to record
+   */
   public abstract void record(long value);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/Histogram1.java

@@ -24,6 +24,11 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * @param <F1> type of the field.
  */
 public abstract class Histogram1<F1> implements RegistrationHandle {
-  /** Record a sample of a specified amount. */
+  /**
+   * Record a sample of a specified amount.
+   *
+   * @param field1 bucket to record sample
+   * @param value value to record
+   */
   public abstract void record(F1 field1, long value);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/Histogram2.java

@@ -25,6 +25,12 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * @param <F2> type of the field.
  */
 public abstract class Histogram2<F1, F2> implements RegistrationHandle {
-  /** Record a sample of a specified amount. */
+  /**
+   * Record a sample of a specified amount.
+   *
+   * @param field1 bucket to record sample
+   * @param field2 bucket to record sample
+   * @param value value to record
+   */
   public abstract void record(F1 field1, F2 field2, long value);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/Histogram3.java

@@ -26,6 +26,13 @@ import com.google.gerrit.extensions.registration.RegistrationHandle;
  * @param <F3> type of the field.
  */
 public abstract class Histogram3<F1, F2, F3> implements RegistrationHandle {
-  /** Record a sample of a specified amount. */
+  /**
+   * Record a sample of a specified amount.
+   *
+   * @param field1 bucket to record sample
+   * @param field2 bucket to record sample
+   * @param field3 bucket to record sample
+   * @param value value to record
+   */
   public abstract void record(F1 field1, F2 field2, F3 field3, long value);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/MetricMaker.java

@@ -22,7 +22,13 @@ import java.util.Set;
 
 /** Factory to create metrics for monitoring. */
 public abstract class MetricMaker {
-  /** Metric whose value increments during the life of the process. */
+  /**
+   * Metric whose value increments during the life of the process.
+   *
+   * @param name field name
+   * @param desc field description
+   * @return counter
+   */
   public abstract Counter0 newCounter(String name, Description desc);
   public abstract <F1> Counter1<F1> newCounter(
       String name, Description desc,
@@ -34,7 +40,13 @@ public abstract class MetricMaker {
       String name, Description desc,
       Field<F1> field1, Field<F2> field2, Field<F3> field3);
 
-  /** Metric recording time spent on an operation. */
+  /**
+   * Metric recording time spent on an operation.
+   *
+   * @param name field name
+   * @param desc field description
+   * @return timer
+   */
   public abstract Timer0 newTimer(String name, Description desc);
   public abstract <F1> Timer1<F1> newTimer(
       String name, Description desc,
@@ -46,7 +58,13 @@ public abstract class MetricMaker {
       String name, Description desc,
       Field<F1> field1, Field<F2> field2, Field<F3> field3);
 
-  /** Metric recording statistical distribution of values. */
+  /**
+   * Metric recording statistical distribution of values.
+   *
+   * @param name field name
+   * @param desc field description
+   * @return histogram
+   */
   public abstract Histogram0 newHistogram(String name, Description desc);
   public abstract <F1> Histogram1<F1> newHistogram(
       String name, Description desc,
@@ -110,14 +128,27 @@ public abstract class MetricMaker {
     });
   }
 
-  /** Instantaneous reading of a single value. */
+  /**
+   *  Instantaneous reading of a single value.
+   *
+   * @param name field name
+   * @param valueClass field type
+   * @param desc field description
+   * @return callback
+   */
   public abstract <V> CallbackMetric0<V> newCallbackMetric(
       String name, Class<V> valueClass, Description desc);
   public abstract <F1, V> CallbackMetric1<F1, V> newCallbackMetric(
       String name, Class<V> valueClass, Description desc,
       Field<F1> field1);
 
-  /** Connect logic to populate a previously created {@link CallbackMetric}. */
+  /**
+   * Connect logic to populate a previously created {@link CallbackMetric}.
+   *
+   * @param metric1 previously created callback
+   * @param trigger trigger to connect
+   * @return registration handle
+   */
   public RegistrationHandle newTrigger(CallbackMetric<?> metric1, Runnable trigger) {
     return newTrigger(ImmutableSet.<CallbackMetric<?>>of(metric1), trigger);
   }

gerrit-server/src/main/java/com/google/gerrit/metrics/Timer0.java

@@ -44,11 +44,19 @@ public abstract class Timer0 implements RegistrationHandle {
     }
   }
 
-  /** Begin a timer for the current block, value will be recorded when closed. */
+  /**
+   * Begin a timer for the current block, value will be recorded when closed.
+   *
+   * @return timer context
+   */
   public Context start() {
     return new Context(this);
   }
 
-  /** Record a value in the distribution. */
+  /** Record a value in the distribution.
+   *
+   * @param value value to record
+   * @param unit time unit of the value
+   */
   public abstract void record(long value, TimeUnit unit);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/Timer1.java

@@ -49,11 +49,22 @@ public abstract class Timer1<F1> implements RegistrationHandle {
     }
   }
 
-  /** Begin a timer for the current block, value will be recorded when closed. */
+  /**
+   * Begin a timer for the current block, value will be recorded when closed.
+   *
+   * @param field1 bucket to record the timer
+   * @return timer context
+   */
   public Context start(F1 field1) {
     return new Context(this, field1);
   }
 
-  /** Record a value in the distribution. */
+  /**
+   * Record a value in the distribution.
+   *
+   * @param field1 bucket to record the timer
+   * @param value value to record
+   * @param unit time unit of the value
+   */
   public abstract void record(F1 field1, long value, TimeUnit unit);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/Timer2.java

@@ -52,11 +52,24 @@ public abstract class Timer2<F1, F2> implements RegistrationHandle {
     }
   }
 
-  /** Begin a timer for the current block, value will be recorded when closed. */
+  /**
+   * Begin a timer for the current block, value will be recorded when closed.
+   *
+   * @param field1 bucket to record the timer
+   * @param field2 bucket to record the timer
+   * @return timer context
+   */
   public Context start(F1 field1, F2 field2) {
     return new Context(this, field1, field2);
   }
 
-  /** Record a value in the distribution. */
+  /**
+   * Record a value in the distribution.
+   *
+   * @param field1 bucket to record the timer
+   * @param field2 bucket to record the timer
+   * @param value value to record
+   * @param unit time unit of the value
+   */
   public abstract void record(F1 field1, F2 field2, long value, TimeUnit unit);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/Timer3.java

@@ -55,12 +55,27 @@ public abstract class Timer3<F1, F2, F3> implements RegistrationHandle {
     }
   }
 
-  /** Begin a timer for the current block, value will be recorded when closed. */
+  /**
+   * Begin a timer for the current block, value will be recorded when closed.
+   *
+   * @param field1 bucket to record the timer
+   * @param field2 bucket to record the timer
+   * @param field3 bucket to record the timer
+   * @return timer context
+   */
   public Context start(F1 field1, F2 field2, F3 field3) {
     return new Context(this, field1, field2, field3);
   }
 
-  /** Record a value in the distribution. */
+  /**
+   * Record a value in the distribution.
+   *
+   * @param field1 bucket to record the timer
+   * @param field2 bucket to record the timer
+   * @param field3 bucket to record the timer
+   * @param value value to record
+   * @param unit time unit of the value
+   */
   public abstract void record(F1 field1, F2 field2, F3 field3,
       long value, TimeUnit unit);
 }

gerrit-server/src/main/java/com/google/gerrit/metrics/TimerContext.java

@@ -29,7 +29,7 @@ abstract class TimerContext implements AutoCloseable {
    */
   public abstract void record(long elapsed);
 
-  /** Get the start time in system time nanoseconds. */
+  /** @return the start time in system time nanoseconds. */
   public long getStartTime() {
     return startNanos;
   }

gerrit-server/src/main/java/com/google/gerrit/server/account/CreateAccount.java

@@ -38,6 +38,7 @@ import com.google.gerrit.server.IdentifiedUser;
 import com.google.gerrit.server.api.accounts.AccountExternalIdCreator;
 import com.google.gerrit.server.group.GroupsCollection;
 import com.google.gerrit.server.index.account.AccountIndexer;
+import com.google.gerrit.server.mail.OutgoingEmailValidator;
 import com.google.gerrit.server.ssh.SshKeyCache;
 import com.google.gwtorm.server.OrmDuplicateKeyException;
 import com.google.gwtorm.server.OrmException;
@@ -45,7 +46,6 @@ import com.google.inject.Inject;
 import com.google.inject.Provider;
 import com.google.inject.assistedinject.Assisted;
 
-import org.apache.commons.validator.routines.EmailValidator;
 import org.eclipse.jgit.errors.ConfigInvalidException;
 
 import java.io.IOException;
@@ -140,7 +140,7 @@ public class CreateAccount
         throw new UnprocessableEntityException(
             "email '" + input.email + "' already exists");
       }
-      if (!EmailValidator.getInstance().isValid(input.email)) {
+      if (!OutgoingEmailValidator.isValid(input.email)) {
         throw new BadRequestException("invalid email address");
       }
     }

gerrit-server/src/main/java/com/google/gerrit/server/account/CreateEmail.java

@@ -29,6 +29,7 @@ import com.google.gerrit.extensions.restapi.RestModifyView;
 import com.google.gerrit.server.CurrentUser;
 import com.google.gerrit.server.IdentifiedUser;
 import com.google.gerrit.server.account.GetEmails.EmailInfo;
+import com.google.gerrit.server.mail.OutgoingEmailValidator;
 import com.google.gerrit.server.config.AuthConfig;
 import com.google.gerrit.server.mail.RegisterNewEmailSender;
 import com.google.gwtorm.server.OrmException;
@@ -36,7 +37,6 @@ import com.google.inject.Inject;
 import com.google.inject.Provider;
 import com.google.inject.assistedinject.Assisted;
 
-import org.apache.commons.validator.routines.EmailValidator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -88,7 +88,7 @@ public class CreateEmail implements RestModifyView<AccountResource, EmailInput>
       input = new EmailInput();
     }
 
-    if (!EmailValidator.getInstance().isValid(email)) {
+    if (!OutgoingEmailValidator.isValid(email)) {
       throw new BadRequestException("invalid email address");
     }
 

gerrit-server/src/main/java/com/google/gerrit/server/mail/OutgoingEmailValidator.java

@@ -19,12 +19,15 @@ import static org.apache.commons.validator.routines.DomainValidator.ArrayType.GE
 import org.apache.commons.validator.routines.DomainValidator;
 import org.apache.commons.validator.routines.EmailValidator;
 
+import java.util.concurrent.atomic.AtomicBoolean;
+
 public class OutgoingEmailValidator {
-  static {
-    DomainValidator.updateTLDOverride(GENERIC_PLUS, new String[]{"local"});
-  }
+  private static final AtomicBoolean initialized = new AtomicBoolean(false);
 
   public static boolean isValid(String addr) {
+    if (!initialized.getAndSet(true)) {
+      DomainValidator.updateTLDOverride(GENERIC_PLUS, new String[]{"local"});
+    }
     return EmailValidator.getInstance(true, true).isValid(addr);
   }
 }

lib/BUCK

@@ -1,4 +1,5 @@
 include_defs('//lib/maven.defs')
+include_defs('//lib/GUAVA_VERSION')
 
 define_license(name = 'antlr')
 define_license(name = 'Apache1.1')
@@ -67,7 +68,7 @@ maven_jar(
 
 maven_jar(
   name = 'guava',
-  id = 'com.google.guava:guava:19.0',
+  id = 'com.google.guava:guava:' + GUAVA_VERSION,
   sha1 = '6ce200f6b23222af3d8abb6b6459e6c44f4bb0e9',
   license = 'Apache2.0',
 )

lib/GUAVA_VERSION

@@ -0,0 +1,2 @@
+GUAVA_VERSION = '19.0'
+GUAVA_DOC_URL = 'https://google.github.io/guava/releases/' + GUAVA_VERSION + '/api/docs/'

lib/JGIT_VERSION

@@ -2,3 +2,5 @@ include_defs('//lib/maven.defs')
 
 REPO = GERRIT # Leave here even if set to MAVEN_CENTRAL.
 VERS = '4.4.1.201607150455-r.144-gb67df51'
+DOC_VERS = '4.4.1.201607150455-r' # Set to VERS unless using a snapshot
+JGIT_DOC_URL="http://download.eclipse.org/jgit/site/" + DOC_VERS + "/apidocs"

tools/java_doc.defs

@@ -6,9 +6,11 @@ def java_doc(
     srcs = [],
     deps = [],
     visibility = [],
+    external_docs = [],
   ):
   # TODO(davido): Actually we shouldn't need to extract the source
   # archive, javadoc should just work with provided archive.
+  external_docs.insert(0, 'http://docs.oracle.com/javase/7/docs/api')
   genrule(
     name = name,
     cmd = ' '.join([
@@ -21,7 +23,7 @@ def java_doc(
       '-charset UTF-8',
       '-notimestamp',
       '-windowtitle "' + title + '"',
-      '-link http://docs.oracle.com/javase/7/docs/api',
+      ' '.join(['-link %s' % url for url in external_docs]),
       '-subpackages ',
       ':'.join(pkgs),
       '-sourcepath $TMP/sourcepath',