org.opensolaris.os.dtrace
Class Aggregation

java.lang.Object
  extended by 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 sortable using Collections.sort(List list, Comparator c) with 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
See Also:
Aggregate.getRecords(), Aggregate.getOrderedRecords()

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