Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.opensolaris.os.dtrace
Class Aggregation

    java.lang.Object
      org.opensolaris.os.dtrace.Aggregation

All Implemented Interfaces:
  java.io.Serializable

    public final class Aggregation

extends java.lang.Object
implements java.io.Serializable

A snapshot of a DTrace aggregation. The name of an `Aggregation` instance matches the source declaration, for example

            @a[execname] = count();

results in an `Aggregation` named "a" (the name does not include the preceding `@`). For convenience, a single aggregation can remain unnamed (multiple aggregations in the same D program need distinct names). The unnamed aggregation results in an `Aggregation` instance whose name is the empty string, for example

            @[execname] = count();

An aggregation can list more than one variable in square brackets in order to accumulate a value for each unique combination, or `Tuple`. Each tuple instance is associated with its accumulated `AggregationValue` in an `AggregationRecord`. For example

            @counts[execname, probefunc, cpu] = count();

results in an `Aggregation` named "counts" containing records each pairing a `CountValue` to a three-element `Tuple`. It is also possible to omit the square brackets, for example

            @a = count();

results in an `Aggregation` named "a" with only a single record keyed to the empty tuple (`Tuple.EMPTY`).

For more information, see the Aggregations chapter of the Solaris Dynamic Tracing Guide. Also, the Built-in Variables section of the Variables chapter describes variables like `execname`, `probefunc`, and `cpu` useful for aggregating.

Immutable. Supports persistence using `XMLEncoder`.

See Also:
  `Aggregate`, `PrintaRecord`, Serialized Form

Constructor Summary
`Aggregation(java.lang.String aggregationName, long aggregationID, java.util.Collection<AggregationRecord> aggregationRecords)` Creates an aggregation with the given name, ID, and records.

Method Summary
`java.util.Map<Tuple,AggregationRecord>` | `asMap()` Gets a read-only `Map` view of this aggregation.
`boolean` | `equals(java.lang.Object o)` Compares the specified object with this aggregation for equality.
`long` | `getID()` Gets the D compiler-generated ID of this aggregation.
`java.lang.String` | `getName()` Gets the name of this aggregation.
`AggregationRecord` | `getRecord(Tuple key)` Gets the record associated with the given key, or the singleton record of an aggregation declared without square brackets if `key` is `null` or empty.
`java.util.List<AggregationRecord>` | `getRecords()` Gets an unordered list of this aggregation's records.
`int` | `hashCode()` Overridden to ensure that equal aggregations have equal hash codes.
`java.lang.String` | `toString()` Gets a string representation of this aggregation useful for logging and not intended for display.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

### Aggregation

    public Aggregation(java.lang.String aggregationName,
                       long aggregationID,
                       java.util.Collection<AggregationRecord> aggregationRecords)

  Creates an aggregation with the given name, ID, and records. Supports XML persistence.

  Parameters:
    `aggregationName` - the name of this aggregation, empty string if this aggregation is unnamed
    `aggregationID` - ID generated from a sequence by the native DTrace library
    `aggregationRecords` - unordered collection of records belonging to this aggregation
  Throws:
    `java.lang.NullPointerException` - if the specified name or list of records is `null`
    `java.lang.IllegalArgumentException` - if any record has an empty tuple, unless it is the only record in the given collection (only a singleton generated by an aggregation without square brackets uses `Tuple.EMPTY` as a key)
  See Also:
    `getRecord(Tuple key)`

Method Detail

### getName

    public java.lang.String getName()

  Gets the name of this aggregation.

  Returns:
    the name of this aggregation exactly as it appears in the D program minus the preceding `@`, or an empty string if the aggregation is unnamed, for example:

                  @[execname] = count();

### getID

    public long getID()

  Gets the D compiler-generated ID of this aggregation.

  Returns:
    the D compiler-generated ID

### getRecords

    public java.util.List<AggregationRecord> getRecords()

  Gets an unordered list of this aggregation's records. The list is easily sortable using `Collections.sort(List list, Comparator c)` provided any user-defined ordering. Modifying the returned list has no effect on this aggregation. Supports XML persistence.

  Returns:
    a newly created list that copies this aggregation's records by reference in no particular order

### asMap

    public java.util.Map<Tuple,AggregationRecord> asMap()

  Gets a read-only `Map` view of this aggregation.

  Returns:
    a read-only `Map` view of this aggregation

### equals

    public boolean equals(java.lang.Object o)

  Compares the specified object with this aggregation for equality. Defines equality as having equal names and equal records.

  Overrides:
    `equals` in class `java.lang.Object`
  Returns:
    `true` if and only if the specified object is an `Aggregation` with the same name as this aggregation and the `Map` views of both aggregations returned by `asMap()` are equal as defined by `AbstractMap.equals()`

### hashCode

    public int hashCode()

  Overridden to ensure that equal aggregations have equal hash codes.

  Overrides:
    `hashCode` in class `java.lang.Object`

### getRecord

    public AggregationRecord getRecord(Tuple key)

  Gets the record associated with the given key, or the singleton record of an aggregation declared without square brackets if `key` is `null` or empty.

  Parameters:
    `key` - The record key, or an empty tuple (see `Tuple.EMPTY`) to obtain the value from a singleton (a non-keyed instance with only a single value) generated from a DTrace aggregation declarated without square brackets, for example:

                  @a = count();

  Returns:
    the record associated with the given key, or `null` if no record in this aggregation is associated with the given key

### toString

    public java.lang.String toString()

  Gets a string representation of this aggregation 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 `java.lang.Object`

Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD