From a2f70c6f4fa4d6ededba02d81c80ba02064ee4ce Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Wed, 22 Jan 2014 09:53:52 +0000 Subject: [PATCH] Add javadocs to some Metrics interfaces Fixes gh-250 --- .../export/PrefixMetricGroupExporter.java | 18 +++++++++++++++++ .../actuate/metrics/reader/MetricReader.java | 17 ++++++++++++++++ .../metrics/reader/PrefixMetricReader.java | 6 ++++++ .../repository/MultiMetricRepository.java | 20 +++++++++++++++++++ .../actuate/metrics/rich/RichGaugeReader.java | 14 +++++++++++++ .../actuate/metrics/writer/MetricWriter.java | 17 ++++++++++++++++ 6 files changed, 92 insertions(+) diff --git a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/export/PrefixMetricGroupExporter.java b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/export/PrefixMetricGroupExporter.java index db3dec0e6e..67c4fa187b 100644 --- a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/export/PrefixMetricGroupExporter.java +++ b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/export/PrefixMetricGroupExporter.java @@ -26,6 +26,9 @@ import org.springframework.boot.actuate.metrics.repository.MultiMetricRepository import org.springframework.boot.actuate.metrics.writer.MetricWriter; /** + * A convenient exporter for a group of metrics from a {@link PrefixMetricReader}. Exports + * all metrics whose name starts with a prefix (or all metrics if the prefix is empty). + * * @author Dave Syer */ public class PrefixMetricGroupExporter extends AbstractMetricExporter { @@ -36,10 +39,25 @@ public class PrefixMetricGroupExporter extends AbstractMetricExporter { private Set groups = new HashSet(); + /** + * Create a new exporter for metrics to a writer based on an empty prefix for the + * metric names. + * + * @param reader a reader as the source of metrics + * @param writer the writer to send the metrics to + */ public PrefixMetricGroupExporter(PrefixMetricReader reader, MetricWriter writer) { this(reader, writer, ""); } + /** + * Create a new exporter for metrics to a writer based on a prefix for the metric + * names. + * + * @param reader a reader as the source of metrics + * @param writer the writer to send the metrics to + * @param prefix the prefix for metrics to export + */ public PrefixMetricGroupExporter(PrefixMetricReader reader, MetricWriter writer, String prefix) { super(prefix); diff --git a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/MetricReader.java b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/MetricReader.java index a54f437f34..01039de70d 100644 --- a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/MetricReader.java +++ b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/MetricReader.java @@ -25,10 +25,27 @@ import org.springframework.boot.actuate.metrics.Metric; */ public interface MetricReader { + /** + * Find an instance of the metric with the given name (usually the latest recorded + * value). + * + * @param metricName the name of the metric to find + * @return a metric value or null if there are none with that name + */ Metric findOne(String metricName); + /** + * Find all the metrics known to this reader. + * + * @return all instances of metrics known to this reader + */ Iterable> findAll(); + /** + * The number of metrics known to this reader. + * + * @return the number of metrics + */ long count(); } diff --git a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/PrefixMetricReader.java b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/PrefixMetricReader.java index 71e366306f..136944d77b 100644 --- a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/PrefixMetricReader.java +++ b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/reader/PrefixMetricReader.java @@ -25,6 +25,12 @@ import org.springframework.boot.actuate.metrics.Metric; */ public interface PrefixMetricReader { + /** + * Find all metrics whose name starts with the given prefix. + * + * @param prefix the prefix for metric names + * @return all metrics with names starting with the prefix + */ Iterable> findAll(String prefix); } diff --git a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/repository/MultiMetricRepository.java b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/repository/MultiMetricRepository.java index 8838a98a56..8f612e2897 100644 --- a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/repository/MultiMetricRepository.java +++ b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/repository/MultiMetricRepository.java @@ -29,12 +29,32 @@ import org.springframework.boot.actuate.metrics.reader.PrefixMetricReader; */ public interface MultiMetricRepository extends PrefixMetricReader { + /** + * Save some metric values and associate them with a group name. + * + * @param group the name of the group + * @param values the metric values to save + */ void save(String group, Collection> values); + /** + * Rest the values of all metrics in the group. Implementations may choose to discard + * the old values. + * + * @param group reset the whole group + */ void reset(String group); + /** + * The names of all the groups known to this repository + * + * @return all available group names + */ Iterable groups(); + /** + * @return the number of groups available + */ long count(); } diff --git a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/rich/RichGaugeReader.java b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/rich/RichGaugeReader.java index c1a5d80b8d..43ea9ab1d4 100644 --- a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/rich/RichGaugeReader.java +++ b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/rich/RichGaugeReader.java @@ -23,10 +23,24 @@ package org.springframework.boot.actuate.metrics.rich; */ public interface RichGaugeReader { + /** + * Find a single instance of a rich gauge by name. + * + * @param name the name of the gauge + * @return a rich gauge value + */ RichGauge findOne(String name); + /** + * Find all instances of rich gauge known to this reader. + * + * @return all instances known to this reader + */ Iterable findAll(); + /** + * @return the number of gauge values available + */ long count(); } diff --git a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/writer/MetricWriter.java b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/writer/MetricWriter.java index 1a6e7868a7..1545f0d098 100644 --- a/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/writer/MetricWriter.java +++ b/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/writer/MetricWriter.java @@ -25,10 +25,27 @@ import org.springframework.boot.actuate.metrics.Metric; */ public interface MetricWriter { + /** + * Increment the value of a metric (or decrement if the delta is negative). The name + * of the delta is the name of the metric to increment. + * + * @param delta the amount to increment by + */ void increment(Delta delta); + /** + * Set the value of a metric. + * + * @param value + */ void set(Metric value); + /** + * Reset the value of a metric, usually to zero value. Implementations can discard the + * old values if desired, but may choose not to. + * + * @param metricName the name to reset + */ void reset(String metricName); }