fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER START
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The contents of this file are subject to the terms of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Common Development and Distribution License (the "License").
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You may not use this file except in compliance with the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * See the License for the specific language governing permissions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and limitations under the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * When distributing Covered Code, include this CDDL HEADER in each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * If applicable, add the following below this CDDL HEADER, with the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * fields enclosed by brackets "[]" replaced with your own identifying
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * information: Portions Copyright [yyyy] [name of copyright owner]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER END
4ae67516a1d5dc4a5dbc761762bad5b596647388tomee * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Use is subject to license terms.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ident "%Z%%M% %I% %E% SMI"
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * A linear frequency distribution aggregated by the DTrace {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * lquantize()} action. Aggregated values fall into consecutive ranges
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * bounded by the step parameter of the {@code lquantize()} action.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Each range, known as a bucket, begins at the {@code lquantize()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * lower bound, or base, plus a multiple of the {@code lquantize()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * step, unless it is the first bucket, which is the frequency of all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregated values less than the base. The last bucket counts all
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * aggregated values greater than or equal to the {@code lquantize()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * upper bound. For example
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <pre> {@code @ = lquantize(n, 0, 100, 10);}</pre>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * results in a distribution with a base of 0, an upper bound of 100,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and a step of 10. It has twelve buckets starting with {@code n < 0}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and ending with {@code n >= 100}. The buckets in between are {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * 0 .. 9}, {@code 10 .. 19}, etc.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Immutable. Supports persistence using {@link java.beans.XMLEncoder}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see LogDistribution
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see Aggregation
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @author Tom Erickson
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeepublic final class LinearDistribution extends Distribution
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee implements Serializable, Comparable <LinearDistribution>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee static final long serialVersionUID = 7100080045858770132L;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /** @serial */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /** @serial */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee BeanInfo info = Introspector.getBeanInfo(LinearDistribution.class);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee d.setValue("persistenceDelegate", persistenceDelegate);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Called by native C code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee LinearDistribution(long lowerBound, long frequencyStep,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // initializes using lowerBound and frequencyStep
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Creates a linear distribution with the given base, step, and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * frequencies. Supports XML persistence.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param lowerBound also known as the <i>base</i>; the minimum of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the second bucket in this distribution (the first bucket contains
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the frequency of everything lower than the base)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param bucketStep the distance between the lower bound of one
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * bucket and the lower bound of the next consecutive bucket
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * (excluding the first bucket)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param frequencies list of frequencies in each bucket range
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if {@code frequencies} is {@code
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if the given step is less than
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * one, or if any bucket does not have the expected range
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * (consecutive steps)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee initialize(); // checks class invariants, calculates total
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee throw new IllegalArgumentException("step is less than one");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a two element array: the first elelemt is the range minimum
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * (inclusive), the second element is the range maximum (inclusive).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (i == 0) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // first bucket is everything less than the base
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // last bucket is everything greater than or equal to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // the upper bound
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the lower bound of this distribution. In a linear
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * distribution, the first bucket holds the frequency of all values
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * less than the base, so the base is the minimum of the second
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * bucket's range.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return the lower bound of this distribution
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public long
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the difference between the lower bounds of consecutive
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * buckets after the first.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return the step between the lower bounds of consecutive buckets
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * after the first
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public long
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee total = (double)bucket.getFrequency() * (double)(getBase() - 1);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee total += (double)bucket.getFrequency() * (double)bucket.getMin();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // There doesn't seem to be any reason to add one to the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // minimum of the last bucket range, but that's how it's
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // implemented in libdtrace dt_aggregate.c.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee private long
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Compares the {@code double} values of {@link #getValue()} for
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * overall magnitude, and if those are equal, compares the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * frequencies at zero if the distributions include a bucket whose
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * range has a minimum of zero.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee private void
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee } catch (Exception e) {
4ae67516a1d5dc4a5dbc761762bad5b596647388tomee InvalidObjectException x = new InvalidObjectException(
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee throw new InvalidObjectException("step is less than one");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a string representation of this linear distribution useful
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * for logging and not intended for display. The exact details of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the representation are unspecified and subject to change, but the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * following format may be regarded as typical:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <pre><code>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * class-name[property1 = value1, property2 = value2]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * </code></pre>