MeanStatistic (Apache Hadoop Main 3.5.0 API)
Description: declaration: package: org.apache.hadoop.fs.statistics, class: MeanStatistic

Package org.apache.hadoop.fs.statistics

# Class MeanStatistic

java.lang.Object
org.apache.hadoop.fs.statistics.MeanStatistic

All Implemented Interfaces:
  `Serializable`, `Cloneable`

@Public @Evolving public final class MeanStatistic extends Object implements Serializable, Cloneable
A mean statistic represented as the sum and the sample count; the mean is calculated on demand.

It can be used to accrue values so as to dynamically update the mean. If so, know that there is no synchronization on the methods.

If a statistic has 0 samples then it is considered to be empty.

All 'empty' statistics are equivalent, independent of the sum value.

For non-empty statistics, sum and sample values must match for equality.

It is serializable and annotated for correct serializations with jackson2.

Thread safety. The operations to add/copy sample data, are thread safe.

1. `add(MeanStatistic)`
2. `addSample(long)`
3. `clear()`
4. `setSamplesAndSum(long, long)`
5. `set(MeanStatistic)`
6. `setSamples(long)` and `setSum(long)`

So is the `mean()` method. This ensures that when used to aggregated statistics, the aggregate value and sample count are set and evaluated consistently.

Other methods marked as synchronized because Findbugs overreacts to the idea that some operations to update sum and sample count are synchronized, but that things like equals are not.

See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MeanStatistic()`
  Create an empty statistic.
  `MeanStatistic(long samples, long sum)`
  Constructor, with some resilience against invalid sample counts.
  `MeanStatistic(MeanStatistic that)`
  Create from another statistic.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MeanStatistic`
  `add(MeanStatistic other)`
  Add another MeanStatistic.
  `void`
  `addSample(long value)`
  Add a sample.
  `void`
  `clear()`
  Set the values to 0.
  `MeanStatistic`
  `clone()`
  `MeanStatistic`
  `copy()`
  Create a copy of this instance.
  `boolean`
  `equals(Object o)`
  `long`
  `getSamples()`
  Get the sample count.
  `long`
  `getSum()`
  Get the sum of samples.
  `int`
  `hashCode()`
  The hash code is derived from the mean and sample count: if either is changed the statistic cannot be used as a key for hash tables/maps.
  `boolean`
  `isEmpty()`
  Is a statistic empty?
  `double`
  `mean()`
  Get the arithmetic mean value.
  `void`
  `set(MeanStatistic other)`
  Set the statistic to the values of another.
  `void`
  `setSamples(long samples)`
  Set the sample count.
  `void`
  `setSamplesAndSum(long sampleCount, long newSum)`
  Set the sum and samples.
  `void`
  `setSum(long sum)`
  Set the sum.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### MeanStatistic

    public MeanStatistic(long samples, long sum)
    Constructor, with some resilience against invalid sample counts. If the sample count is 0 or less, the sum is set to 0 and the sample count to 0.
    Parameters:
      `samples` - sample count.
      `sum` - sum value

  - ### MeanStatistic

    public MeanStatistic(MeanStatistic that)
    Create from another statistic.
    Parameters:
      `that` - source

  - ### MeanStatistic

    public MeanStatistic()
    Create an empty statistic.

- ## Method Details

  - ### getSum

    public long getSum()
    Get the sum of samples.
    Returns:
      the sum

  - ### getSamples

    public long getSamples()
    Get the sample count.
    Returns:
      the sample count; 0 means empty

  - ### isEmpty

    public boolean isEmpty()
    Is a statistic empty?
    Returns:
      true if the sample count is 0

  - ### clear

    public void clear()
    Set the values to 0.

  - ### setSamplesAndSum

    public void setSamplesAndSum(long sampleCount, long newSum)
    Set the sum and samples. Synchronized.
    Parameters:
      `sampleCount` - new sample count.
      `newSum` - new sum

  - ### set

    public void set(MeanStatistic other)
    Set the statistic to the values of another. Synchronized.
    Parameters:
      `other` - the source.

  - ### setSum

    public void setSum(long sum)
    Set the sum.
    Parameters:
      `sum` - new sum

  - ### setSamples

    public void setSamples(long samples)
    Set the sample count. If this is less than zero, it is set to zero. This stops an ill-formed JSON entry from breaking deserialization, or get an invalid sample count into an entry.
    Parameters:
      `samples` - sample count.

  - ### mean

    public double mean()
    Get the arithmetic mean value.
    Returns:
      the mean

  - ### add

    public MeanStatistic add(MeanStatistic other)
    Add another MeanStatistic.
    Parameters:
      `other` - other value
    Returns:
      mean statistic.

  - ### addSample

    public void addSample(long value)
    Add a sample. Thread safe.
    Parameters:
      `value` - value to add to the sum

  - ### hashCode

    public int hashCode()
    The hash code is derived from the mean and sample count: if either is changed the statistic cannot be used as a key for hash tables/maps.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash value

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### clone

    public MeanStatistic clone()
    Overrides:
      `clone` in class `Object`

  - ### copy

    public MeanStatistic copy()
    Create a copy of this instance.
    Returns:
      copy.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`