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 PrintaRecord

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

All Implemented Interfaces:
  java.io.Serializable, Record

    public final class PrintaRecord

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

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
`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.
`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, equals, finalize, getClass, hashCode, 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

### 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`

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