org.opensolaris.os.dtrace
Class LinearDistribution

java.lang.Object
  extended by org.opensolaris.os.dtrace.Distribution
      extended by org.opensolaris.os.dtrace.LinearDistribution
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<LinearDistribution>, java.lang.Iterable<Distribution.Bucket>, AggregationValue

public final class LinearDistribution
extends Distribution
implements java.io.Serializable, java.lang.Comparable<LinearDistribution>

A linear frequency distribution aggregated by the DTrace lquantize() action. Aggregated values fall into consecutive ranges bounded by the step parameter of the lquantize() action. Each range, known as a bucket, begins at the lquantize() lower bound, or base, plus a multiple of the lquantize() step, unless it is the first bucket, which is the frequency of all aggregated values less than the base. The last bucket counts all aggregated values greater than or equal to the lquantize() upper bound. For example

          @ = lquantize(n, 0, 100, 10);
results in a distribution with a base of 0, an upper bound of 100, and a step of 10. It has twelve buckets starting with n < 0 and ending with n >= 100. The buckets in between are 0 .. 9, 10 .. 19, etc.

Immutable. Supports persistence using XMLEncoder.

See Also:
LogDistribution, Aggregation, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.opensolaris.os.dtrace.Distribution
Distribution.Bucket
 
Constructor Summary
LinearDistribution(long lowerBound, long bucketStep, java.util.List<Distribution.Bucket> frequencies)
          Creates a linear distribution with the given base, step, and frequencies.
 
Method Summary
 int compareTo(LinearDistribution d)
          Compares the double values of getValue() for overall magnitude, and if those are equal, compares the frequencies at zero if the distributions include a bucket whose range has a minimum of zero.
 long getBase()
          Gets the lower bound of this distribution.
 long getStep()
          Gets the difference between the lower bounds of consecutive buckets after the first.
 java.lang.Number getValue()
          Gets the numeric value of this distribution used to compare distributions by overall magnitude, defined as the sum total of each bucket's frequency times the minimum of its range.
 java.lang.String toString()
          Gets a string representation of this linear distribution useful for logging and not intended for display.
 
Methods inherited from class org.opensolaris.os.dtrace.Distribution
asList, equals, get, getBuckets, getDisplayRange, getTotal, hashCode, iterator, size
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LinearDistribution

public LinearDistribution(long lowerBound,
                          long bucketStep,
                          java.util.List<Distribution.Bucket> frequencies)
Creates a linear distribution with the given base, step, and frequencies. Supports XML persistence.

Parameters:
lowerBound - also known as the base; the minimum of the second bucket in this distribution (the first bucket contains the frequency of everything lower than the base)
bucketStep - the distance between the lower bound of one bucket and the lower bound of the next consecutive bucket (excluding the first bucket)
frequencies - list of frequencies in each bucket range
Throws:
java.lang.NullPointerException - if frequencies is null
java.lang.IllegalArgumentException - if the given step is less than one, or if any bucket does not have the expected range (consecutive steps)
Method Detail

getBase

public long getBase()
Gets the lower bound of this distribution. In a linear distribution, the first bucket holds the frequency of all values less than the base, so the base is the minimum of the second bucket's range.

Returns:
the lower bound of this distribution

getStep

public long getStep()
Gets the difference between the lower bounds of consecutive buckets after the first.

Returns:
the step between the lower bounds of consecutive buckets after the first

getValue

public java.lang.Number getValue()
Description copied from class: Distribution
Gets the numeric value of this distribution used to compare distributions by overall magnitude, defined as the sum total of each bucket's frequency times the minimum of its range.

Specified by:
getValue in interface AggregationValue
Specified by:
getValue in class Distribution
Returns:
non-null numeric value

compareTo

public int compareTo(LinearDistribution d)
Compares the double values of getValue() for overall magnitude, and if those are equal, compares the frequencies at zero if the distributions include a bucket whose range has a minimum of zero.

Specified by:
compareTo in interface java.lang.Comparable<LinearDistribution>

toString

public java.lang.String toString()
Gets a string representation of this linear distribution useful for logging and not intended for display. The exact details of the representation are unspecified and subject to change, but the following format may be regarded as typical:

 class-name[property1 = value1, property2 = value2]
 

Overrides:
toString in class Distribution