From 04dbe6336645e7f50ff729b123a3588506add4c1 Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Tue, 7 Sep 2010 10:24:53 +0100 Subject: [PATCH] INT-1420: add javadocs --- .../integration/control/ControlBus.java | 6 ++- .../monitor/ExponentialMovingAverage.java | 33 ++++++++++++- .../monitor/ExponentialMovingAverageRate.java | 36 ++++++++++++-- .../ExponentialMovingAverageRatio.java | 36 ++++++++++++-- .../monitor/IntegrationMBeanExporter.java | 27 +++++++++-- .../LifecycleMessageHandlerMonitor.java | 8 +++- .../monitor/MessageChannelMonitor.java | 48 ++++++++++++++++++- .../monitor/MessageHandlerMonitor.java | 18 +++++++ .../monitor/ObjectNameLocator.java | 9 ++++ 9 files changed, 203 insertions(+), 18 deletions(-) diff --git a/spring-integration-jmx/src/main/java/org/springframework/integration/control/ControlBus.java b/spring-integration-jmx/src/main/java/org/springframework/integration/control/ControlBus.java index fe549c2c16..53e88a4311 100644 --- a/spring-integration-jmx/src/main/java/org/springframework/integration/control/ControlBus.java +++ b/spring-integration-jmx/src/main/java/org/springframework/integration/control/ControlBus.java @@ -33,7 +33,11 @@ import org.springframework.integration.support.MessageBuilder; import org.springframework.util.Assert; /** - * JMX-based Control Bus implementation. Exports all channel and endpoint beans from a given BeanFactory as MBeans. + * JMX-based Control Bus implementation. Routes control messages on an operation channel to the other control points + * (channels and handlers) via JMX. To use the control bus send a message to the operation channel with a header + * {@link #TARGET_BEAN_NAME} equal to the bean name of the channel or endpoint you want to target. Include also a header + * {@link JmxHeaders#OPERATION_NAME} to specify the operation you want to invoke and a message payload containing the + * arguments (if any). * * @author Mark Fisher * @since 2.0 diff --git a/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverage.java b/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverage.java index bf47c86a0c..8a9de55043 100644 --- a/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverage.java +++ b/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverage.java @@ -14,8 +14,11 @@ package org.springframework.integration.monitor; /** * Cumulative statistics for a series of real numbers with higher weight given to recent data but without storing any - * history. Older values are given exponentially smaller weight, with a decay factor determined by a "window" size - * chosen by the client. + * history. Clients call {@link #append(double)} every time there is a new measurement, and then can collect summary + * statistics from the convenience getters (e.g. {@link #getStatistics()}). Older values are given exponentially smaller + * weight, with a decay factor determined by a "window" size chosen by the caller. The result is a good approximation to + * the statistics of the series but with more weight given to recent measurements, so if the statistics change over time + * those trends can be approximately reflected. * * @author Dave Syer * @@ -37,12 +40,20 @@ public class ExponentialMovingAverage { private final double decay; /** + * Create a moving average accumulator with decay lapse window provided. Measurements older than this will have + * smaller weight than 1/e. + * * @param window the exponential lapse window (number of measurements) */ public ExponentialMovingAverage(int window) { this.decay = 1 - 1. / window; } + /** + * Add a new measurement to the series. + * + * @param value the measurement to append + */ public void append(double value) { if (value > max || count == 0) max = value; @@ -54,28 +65,46 @@ public class ExponentialMovingAverage { count++; } + /** + * @return the number of measurements recorded + */ public int getCount() { return count; } + /** + * @return the mean value + */ public double getMean() { return weight > 0 ? sum / weight : 0.; } + /** + * @return the approximate standard deviation + */ public double getStandardDeviation() { double mean = getMean(); double var = weight > 0 ? sumSquares / weight - mean * mean : 0.; return var > 0 ? Math.sqrt(var) : 0; } + /** + * @return the maximum value recorded (not weighted) + */ public double getMax() { return max; } + /** + * @return the minimum value recorded (not weighted) + */ public double getMin() { return min; } + /** + * @return summary statistics (count, mean, standard deviation etc.) + */ public Statistics getStatistics() { return new Statistics(count, min, max, getMean(), getStandardDeviation()); } diff --git a/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRate.java b/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRate.java index bae74a915c..aa096c29bb 100644 --- a/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRate.java +++ b/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRate.java @@ -13,8 +13,17 @@ package org.springframework.integration.monitor; /** - * Cumulative statistics for rate with higher weight given to recent data but without storing any history. Older values - * are given exponentially smaller weight, with a decay factor determined by a duration chosen by the client. + * Cumulative statistics for an event rate with higher weight given to recent data but without storing any history. + * Clients call {@link #increment()} when a new event occurs, and then use convenience methods (e.g. {@link #getMean()}) + * to retrieve estimates of the rate of event arrivals and the statistics of the series. Older values are given + * exponentially smaller weight, with a decay factor determined by a duration chosen by the client. The rate measurement + * weights decay in two dimensions: + * * * @author Dave Syer * @@ -48,6 +57,9 @@ public class ExponentialMovingAverageRate { this.period = period * 1000; // convert to millisecs } + /** + * Add a new event to the series. + */ public void increment() { long t = System.currentTimeMillis(); @@ -66,6 +78,9 @@ public class ExponentialMovingAverageRate { } + /** + * @return the number of measurements recorded + */ public int getCount() { return rates.getCount(); } @@ -77,9 +92,12 @@ public class ExponentialMovingAverageRate { return (System.currentTimeMillis() - t0) / 1000.; } + /** + * @return the mean value + */ public double getMean() { int count = rates.getCount(); - if (count==0) { + if (count == 0) { return 0; } long t = System.currentTimeMillis(); @@ -87,18 +105,30 @@ public class ExponentialMovingAverageRate { return count / (count / rates.getMean() + value); } + /** + * @return the approximate standard deviation + */ public double getStandardDeviation() { return rates.getStandardDeviation(); } + /** + * @return the maximum value recorded (not weighted) + */ public double getMax() { return min > 0 ? 1 / min : 0; } + /** + * @return the minimum value recorded (not weighted) + */ public double getMin() { return max > 0 ? 1 / max : 0; } + /** + * @return summary statistics (count, mean, standard deviation etc.) + */ public Statistics getStatistics() { return new Statistics(getCount(), min, max, getMean(), getStandardDeviation()); } diff --git a/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRatio.java b/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRatio.java index 2e2ca1a0e0..48297f2bb0 100644 --- a/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRatio.java +++ b/spring-integration-jmx/src/main/java/org/springframework/integration/monitor/ExponentialMovingAverageRatio.java @@ -13,9 +13,15 @@ package org.springframework.integration.monitor; /** - * Cumulative statistics for success rate (ratio) with higher weight given to recent data but without storing any - * history. Older values are given exponentially smaller weight, with a decay factor determined by a duration chosen by - * the client. + * Cumulative statistics for success ratio with higher weight given to recent data but without storing any history. + * Clients call {@link #success()} or {@link #failure()} when an event occurs, and the ratio of success to total events + * is accumulated. Older values are given exponentially smaller weight, with a decay factor determined by a duration + * chosen by the client. The rate measurement weights decay in two dimensions: + *