/*
* Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.opensolaris.os.dtrace;
import java.util.*;
import java.beans.*;
import java.io.*;
/**
* A snapshot of a DTrace aggregation. The name of an {@code
* Aggregation} instance matches the source declaration, for example
* <pre> {@code @a[execname] = count();}</pre>
* results in an {@code Aggregation} named "a" (the name does not
* include the preceding {@code @}). For convenience, a single
* aggregation can remain unnamed (multiple aggregations in the same D
* program need distinct names). The unnamed aggregation results in an
* {@code Aggregation} instance whose name is the empty string, for
* example
* <pre> {@code @[execname] = count();}</pre>
* An aggregation can list more than one variable in square brackets in
* order to accumulate a value for each unique combination, or {@link
* Tuple}. Each tuple instance is associated with its accumulated
* {@link AggregationValue} in an {@link AggregationRecord}. For
* example
* <pre> {@code @counts[execname, probefunc, cpu] = count();}</pre>
* results in an {@code Aggregation} named "counts" containing records
* each pairing a {@link CountValue} to a three-element {@code Tuple}.
* It is also possible to omit the square brackets, for example
* <pre> {@code @a = count();}</pre>
* results in an {@code Aggregation} named "a" with only a single record
* keyed to the empty tuple ({@link Tuple#EMPTY}).
* <p>
* For more information, see the <a
* href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlh7?a=view>
* <b>Aggregations</b></a> chapter of the <i>Solaris Dynamic Tracing
* Guide</i>. Also, the <a
* href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlfv?a=view>
* <b>Built-in Variables</b></a> section of the <b>Variables</b> chapter
* describes variables like {@code execname}, {@code probefunc}, and
* {@code cpu} useful for aggregating.
* <p>
* Immutable. Supports persistence using {@link java.beans.XMLEncoder}.
*
* @see Aggregate
* @see PrintaRecord
*
* @author Tom Erickson
*/
public final class Aggregation implements Serializable {
static final long serialVersionUID = 2340811719178724026L;
/**
* Creates an aggregation with the given name, ID, and records.
* Supports XML persistence.
*
* @param aggregationName the name of this aggregation, empty string
* if this aggregation is unnamed
* @param aggregationID ID generated from a sequence by the native
* DTrace library
* @param aggregationRecords unordered collection of records
* belonging to this aggregation
* @throws NullPointerException if the specified name or list of
* records is {@code null}
* @throws 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 {@link Tuple#EMPTY} as a key)
* @see #getRecord(Tuple key)
*/
public
Aggregation(String aggregationName, long aggregationID,
Collection <AggregationRecord> aggregationRecords)
{
}
/**
* Gets the name of this aggregation.
*
* @return the name of this aggregation exactly as it appears in the
* D program minus the preceding {@code @}, or an empty string if
* the aggregation is unnamed, for example:
* <pre> {@code @[execname] = count();}</pre>
*/
public String
getName()
{
return "";
}
/**
* Gets the D compiler-generated ID of this aggregation.
*
* @return the D compiler-generated ID
*/
public long
getID()
{
return -1L;
}
/**
* Gets an unordered list of this aggregation's records. The list is
* sortable using {@link java.util.Collections#sort(List list,
* Comparator c)} with any user-defined ordering. Modifying the
* returned list has no effect on this aggregation. Supports XML
* persistence.
*
* @return a newly created list that copies this aggregation's
* records by reference in no particular order
* @see Aggregate#getRecords()
* @see Aggregate#getOrderedRecords()
*/
public List <AggregationRecord>
getRecords()
{
return Collections.EMPTY_LIST;
}
/**
* Gets a read-only {@code Map} view of this aggregation.
*
* @return a read-only {@code Map} view of this aggregation
*/
public Map <Tuple, AggregationRecord>
asMap()
{
return Collections.EMPTY_MAP;
}
/**
* Gets the record associated with the given key, or the singleton
* record of an aggregation declared without square brackets if
* {@code key} is {@code null} or empty.
*
* @param key The record key, or an empty tuple (see {@link
* Tuple#EMPTY}) to obtain the value from a <i>singleton</i> (a
* non-keyed instance with only a single value) generated from a
* DTrace aggregation declarated without square brackets, for
* example:
* <pre> {@code @a = count();}</pre>
* @return the record associated with the given key, or {@code null}
* if no record in this aggregation is associated with the given key
*/
public AggregationRecord
getRecord(Tuple key)
{
return null;
}
}