org.opensolaris.os.dtrace
Class PrintaRecord

java.lang.Object
  extended by org.opensolaris.os.dtrace.PrintaRecord
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<PrintaRecord>, Record

public final class PrintaRecord
extends java.lang.Object
implements Record, java.io.Serializable, java.lang.Comparable<PrintaRecord>

A record generated by the DTrace printa() action. Lists the aggregations passed to printa() and records the formatted output associated with each Tuple. If multiple aggregations were passed to the printa() action that generated this record, then the DTrace library tabulates the output, using a default format if no format string was specified. By default, the output string associated with a given Tuple includes a value from each aggregation, or zero wherever an aggregation has no value associated with that Tuple. For example, the D statements


     @a[123] = sum(1);
     @b[456] = sum(2);
     printa(@a, @b, @c);
 
produce output for the tuples "123" and "456" similar to the following:

        123     1       0       0
        456     0       2       0
 
The first column after the tuple contains values from @a, the next column contains values from @b, and the last column contains zeros because @c has neither a value associated with "123" nor a value associated with "456".

If a format string is passed to printa(), it may limit the aggregation data available in this record. For example, if the format string specifies a value placeholder for only one of two aggregations passed to printa(), then the resulting PrintaRecord will contain only one Aggregation. If no value placeholder is specified, or if the aggregation tuple is not completely specified, the resulting PrintaRecord will contain no aggregation data. However, the formatted output generated by the DTrace library is available in all cases. For details about printa() format strings, see the printa() section of the Output Formatting chapter of the Solaris Dynamic Tracing Guide.

Immutable. Supports persistence using XMLEncoder.

See Also:
Serialized Form

Constructor Summary
PrintaRecord(long snaptimeNanos, java.util.Collection<Aggregation> aggs, java.util.Map<Tuple,java.lang.String> formattedOutput, java.util.List<Tuple> orderedTuples, java.lang.String formattedOutputString)
          Creates a record with the given snaptime, aggregations, and formatted output.
 
Method Summary
 int compareTo(PrintaRecord r)
          Compares the formatted output of this record with that of the given record.
 boolean equals(java.lang.Object o)
          Compares the specified object with this PrintaRecord for equality.
 Aggregation getAggregation(java.lang.String name)
          Gets the named aggregation.
 java.util.List<Aggregation> getAggregations()
          Gets a list of the aggregations passed to the printa() action that generated this record.
 java.lang.String getFormattedString(Tuple key)
          Gets the formatted string, if any, associated with the given aggregation tuple.
 java.util.Map<Tuple,java.lang.String> getFormattedStrings()
          Gets the formatted output, if any, associated with each Tuple occurring in the aggregations belonging to this record, one formatted string per Tuple.
 java.lang.String getOutput()
          Gets this record's formatted output.
 long getSnaptime()
          Gets the nanosecond timestamp of the aggregate snapshot used to create this printa() record.
 java.util.List<Tuple> getTuples()
          Gets an ordered list of this record's aggregation tuples.
 int hashCode()
          Overridden to ensure that equal instances have equal hash codes.
 java.lang.String toString()
          Gets a string representation of this instance 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

PrintaRecord

public PrintaRecord(long snaptimeNanos,
                    java.util.Collection<Aggregation> aggs,
                    java.util.Map<Tuple,java.lang.String> formattedOutput,
                    java.util.List<Tuple> orderedTuples,
                    java.lang.String formattedOutputString)
Creates a record with the given snaptime, aggregations, and formatted output.

Parameters:
snaptimeNanos - nanosecond timestamp of the snapshot used to create this printa() record
aggs - aggregations passed to the printa() action that generated this record
formattedOutput - the formatted output, if any, associated with each Tuple occurring in the aggregations belonging to this record, one formatted string per Tuple, or an empty or null map if an incomplete printa() format string caused aggregation tuples to be omitted from this record
orderedTuples - list of aggregation tuples in the same order generated by the native DTrace library (determined by the various "aggsort" options such as Option.aggsortkey)
formattedOutputString - printa() formatted string output in the same order generated by the native DTrace library (determined by the various "aggsort" options such as Option.aggsortkey)
Throws:
java.lang.NullPointerException - if the given collection of aggregations is null, or if the given ordered lists of tuples or formatted strings are null
java.lang.IllegalArgumentException - if the given snaptime is negative
Method Detail

getSnaptime

public long getSnaptime()
Gets the nanosecond timestamp of the aggregate snapshot used to create this printa() record.

Returns:
nanosecond timestamp

getAggregation

public Aggregation getAggregation(java.lang.String name)
Gets the named aggregation.

Returns:
the named aggregation passed to printa(), or null if the named aggregation is not passed to printa(), or if it is omitted due to an incomplete printa() format string, or if it is empty (a future release of this API may represent an empty DTrace aggregation as a non-null Aggregation with no records; users of this API should not rely on a non-null return value to indicate a non-zero record count)

getAggregations

public java.util.List<Aggregation> getAggregations()
Gets a list of the aggregations passed to the printa() action that generated this record. The returned list is a copy, and modifying it has no effect on this record. Supports XML persistence.

Returns:
non-null, possibly empty list of aggregations belonging to this record (empty aggregations are excluded)

getFormattedString

public java.lang.String getFormattedString(Tuple key)
Gets the formatted string, if any, associated with the given aggregation tuple.

Parameters:
key - aggregation tuple
Returns:
the formatted string associated with the given aggregation tuple, or null if the given tuple does not exist in the aggregations belonging to this record or if it is omitted from this record due to an incomplete printa() format string
See Also:
getFormattedStrings(), getOutput()

getFormattedStrings

public java.util.Map<Tuple,java.lang.String> getFormattedStrings()
Gets the formatted output, if any, associated with each Tuple occurring in the aggregations belonging to this record, one formatted string per Tuple. Gets an empty map if aggregation tuples are omitted from this record due to an incomplete printa() format string. The returned map is a copy and modifying it has no effect on this record. Supports XML persistence.

Returns:
a map of aggregation tuples and their associated formatted output strings, empty if aggregation tuples are omitted from this record due to an incomplete printa() format string
See Also:
getFormattedString(Tuple key), getOutput()

getTuples

public java.util.List<Tuple> getTuples()
Gets an ordered list of this record's aggregation tuples. The returned list is a copy, and modifying it has no effect on this record. Supports XML persistence.

Returns:
a non-null list of this record's aggregation tuples in the order they were generated by the native DTrace library, as determined by the Option.aggsortkey, Option.aggsortrev, Option.aggsortpos, and Option.aggsortkeypos options

getOutput

public java.lang.String getOutput()
Gets this record's formatted output. Supports XML persistence.

Returns:
non-null formatted output in the order generated by the native DTrace library, as determined by the Option.aggsortkey, Option.aggsortrev, Option.aggsortpos, and Option.aggsortkeypos options

equals

public boolean equals(java.lang.Object o)
Compares the specified object with this PrintaRecord for equality. Returns true if and only if the specified object is also a PrintaRecord and both records have the same aggregations and the same formatted strings in the same order (by aggregation tuple).

Overrides:
equals in class java.lang.Object
Returns:
true if and only if the specified object is also a PrintaRecord and both records have the same aggregations and the same formatted strings in the same order (by aggregation tuple)

hashCode

public int hashCode()
Overridden to ensure that equal instances have equal hash codes.

Overrides:
hashCode in class java.lang.Object

compareTo

public int compareTo(PrintaRecord r)
Compares the formatted output of this record with that of the given record. Note that ordering printa records by their output string values is incompatible with equals(), which also checks the underlying aggregation data for equality.

Specified by:
compareTo in interface java.lang.Comparable<PrintaRecord>
Returns:
a negative number, 0, or a positive number as this record's formatted output is lexicographically less than, equal to, or greater than the given record's formatted output

toString

public java.lang.String toString()
Gets a string representation of this instance 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