1 /*
2 * Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package com.sun.corba.se.spi.monitoring;
26
27 import java.util.*;
28
29 /**
30 * @author Hemanth Puttaswamy
31 *
32 * StatisticsAccumulator accumulates the samples provided by the user and
33 * computes the value of minimum, maximum, sum and sample square sum. When
34 * the StatisticMonitoredAttribute calls getValue(), it will compute all
35 * the statistics for the collected samples (Which are Minimum, Maximum,
36 * Average, StandardDeviation) and provides a nice printable record as a
37 * String.
38 *
39 * Users can easily extend this class and provide the implementation of
40 * toString() method to format the stats as desired. By default all the stats
41 * are printed in a single line.
42 */
43 public class StatisticsAccumulator {
44
45 ///////////////////////////////////////
46 // attributes
47
48
49 // Users can extend this class to get access to current Max value
50 protected double max = Double.MIN_VALUE;
51
52 // Users can extend this class to get access to current Min value
53 protected double min = Double.MAX_VALUE;
54
55 private double sampleSum;
56
57 private double sampleSquareSum;
58
59 private long sampleCount;
60
61 protected String unit;
62
63
64
65 ///////////////////////////////////////
66 // operations
67
68
69
70 /**
71 * User will use this method to just register a sample with the
72 * StatisticsAccumulator. This is the only method that User will use to
73 * expose the statistics, internally the StatisticMonitoredAttribute will
74 * collect the information when requested from the ASAdmin.
75 *
76 * @param value a double value to make it more precise
77 */
78 public void sample(double value) {
79 sampleCount++;
80 if( value < min ) min = value;
81 if( value > max) max = value;
82 sampleSum += value;
83 sampleSquareSum += (value * value);
84 } // end sample
85
86
87
88 /**
89 * Computes the Standard Statistic Results based on the samples collected
90 * so far and provides the complete value as a formatted String
91 */
92 public String getValue( ) {
93 return toString();
94 }
95
96 /**
97 * Users can extend StatisticsAccumulator to provide the complete
98 * Stats in the format they prefer, if the default format doesn't suffice.
99 */
100 public String toString( ) {
101 return "Minimum Value = " + min + " " + unit + " " +
102 "Maximum Value = " + max + " " + unit + " " +
103 "Average Value = " + computeAverage() + " " + unit + " " +
104 "Standard Deviation = " + computeStandardDeviation() + " " + unit +
105 " " + "Samples Collected = " + sampleCount;
106 }
107
108 /**
109 * If users choose to custom format the stats.
110 */
111 protected double computeAverage( ) {
112 return (sampleSum / sampleCount);
113 }
114
115
116 /**
117 * We use a derived Standard Deviation formula to compute SD. This way
118 * there is no need to hold on to all the samples provided.
119 *
120 * The method is protected to let users extend and format the results.
121 */
122 protected double computeStandardDeviation( ) {
123 double sampleSumSquare = sampleSum * sampleSum;
124 return Math.sqrt(
125 (sampleSquareSum-((sampleSumSquare)/sampleCount))/(sampleCount-1));
126 }
127
128 /**
129 * Construct the Statistics Accumulator by providing the unit as a String.
130 * The examples of units are {@literal "Hours", "Minutes",
131 * "Seconds", "MilliSeconds", "Micro Seconds"} etc.
132 *
133 * @param unit a String representing the units for the samples collected
134 */
135 public StatisticsAccumulator( String unit ) {
136 this.unit = unit;
137 sampleCount = 0;
138 sampleSum = 0;
139 sampleSquareSum = 0;
140 }
141
142
143 /**
144 * Clears the samples and starts fresh on new samples.
145 */
146 void clearState( ) {
147 min = Double.MAX_VALUE;
148 max = Double.MIN_VALUE;
149 sampleCount = 0;
150 sampleSum = 0;
151 sampleSquareSum = 0;
152 }
153
154 /**
155 * This is an internal API to test StatisticsAccumulator...
156 */
157 public void unitTestValidate( String expectedUnit, double expectedMin,
158 double expectedMax, long expectedSampleCount, double expectedAverage,
159 double expectedStandardDeviation )
160 {
161 if( !expectedUnit.equals( unit ) ){
162 throw new RuntimeException(
163 "Unit is not same as expected Unit" +
164 "\nUnit = " + unit + "ExpectedUnit = " + expectedUnit );
165 }
166 if( min != expectedMin ) {
167 throw new RuntimeException(
168 "Minimum value is not same as expected minimum value" +
169 "\nMin Value = " + min + "Expected Min Value = " + expectedMin);
170 }
171 if( max != expectedMax ) {
172 throw new RuntimeException(
173 "Maximum value is not same as expected maximum value" +
174 "\nMax Value = " + max + "Expected Max Value = " + expectedMax);
175 }
176 if( sampleCount != expectedSampleCount ) {
177 throw new RuntimeException(
178 "Sample count is not same as expected Sample Count" +
179 "\nSampleCount = " + sampleCount + "Expected Sample Count = " +
180 expectedSampleCount);
181 }
182 if( computeAverage() != expectedAverage ) {
183 throw new RuntimeException(
184 "Average is not same as expected Average" +
185 "\nAverage = " + computeAverage() + "Expected Average = " +
186 expectedAverage);
187 }
188 // We are computing Standard Deviation from two different methods
189 // for comparison. So, the values will not be the exact same to the last
190 // few digits. So, we are taking the difference and making sure that
191 // the difference is not greater than 1.
192 double difference = Math.abs(
193 computeStandardDeviation() - expectedStandardDeviation);
194 if( difference > 1 ) {
195 throw new RuntimeException(
196 "Standard Deviation is not same as expected Std Deviation" +
197 "\nStandard Dev = " + computeStandardDeviation() +
198 "Expected Standard Dev = " + expectedStandardDeviation);
199 }
200 }
201
202
203 } // end StatisticsAccumulator