Aggregate.java revision e77b06d21580f630e0a7c437495ab283d3672828
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 2008 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*
* ident "%Z%%M% %I% %E% SMI"
*/
/**
* A consistent snapshot of all aggregations requested by a single
* {@link Consumer}.
* <p>
* Immutable. Supports persistence using {@link java.beans.XMLEncoder}.
*
* @see Consumer#getAggregate()
*
* @author Tom Erickson
*/
public final class Aggregate implements Serializable
{
static final long serialVersionUID = 3180340417154076628L;
static {
try {
} catch (IntrospectionException e) {
}
}
/** @serial */
private final long snaptime;
// Map must not have same name as named PersistenceDelegate property
// ("aggregations"), otherwise it gets confused for a bean property
// and XMLDecoder calls the constructor with a Map instead of the
// value of the getAggregations() method.
private transient int recordSequence;
/**
* Called by native code.
*/
private
Aggregate(long snaptimeNanos)
{
}
/**
* Creates an aggregate with the given snaptime and aggregations.
* Supports XML persistence.
*
* @param snaptimeNanos nanosecond timestamp when this aggregate was
* snapped
* @param aggregations unordered collection of aggregations
* belonging to this aggregate
* @throws NullPointerException if the given collection of
* aggregations is {@code null}
* @throws IllegalArgumentException if the record ordinals of the
* given aggregations are invalid
*/
public
{
validate();
}
// assumes map is not yet created
private void
{
// avoid rehashing and optimize lookup; will never be modified
for (Aggregation a : aggregations) {
}
}
private void
validate()
{
// Allow all ordinals to be zero for backward
// compatibility (allows XML decoding of aggregates that
// were encoded before the ordinal property was added).
throw new IllegalArgumentException(
"duplicate record ordinal: " + ordinal);
}
}
}
}
throw new IllegalArgumentException(
"equal the number of records (" + recordSequence +
") minus one.");
}
}
/**
* Gets the nanosecond timestamp of this aggregate snapshot.
*
* @return nanosecond timestamp of this aggregate snapshot
*/
public long
{
return snaptime;
}
/**
* Gets an unordered list of all aggregations in this aggregate
* snapshot. The list is easily sortable using {@link
* java.util.Collections#sort(List list, Comparator c)} provided any
* user-defined ordering. Modifying the returned list has no effect
* on this aggregate. Supports XML persistence.
*
* @return modifiable unordered list of all aggregations in this
* aggregate snapshot; list is non-null and possibly empty
*/
public List <Aggregation>
{
// Must return an instance of a public, mutable class in order
// to support XML persistence.
return list;
}
/**
* Gets the aggregation with the given name if it exists in this
* aggregate snapshot.
*
* @param name the name of the desired aggregation, or empty string
* to request the unnamed aggregation. In D, the unnamed
* aggregation is used anytime a name does not follow the
* aggregation symbol '{@code @}', for example:
* <pre> {@code @ = count();}</pre> as opposed to
* <pre> {@code @counts = count()}</pre> resulting in an
* {@code Aggregation} with the name "counts".
*
* @return {@code null} if no aggregation by the given name exists
* in this aggregate
* @see Aggregation#getName()
*/
public Aggregation
{
// This was decided March 18, 2005 in a meeting with the DTrace
// team that calling getAggregation() with underbar should
// return the unnamed aggregation (same as calling with empty
// string). Underbar is used to identify the unnamed
// aggregation in libdtrace; in the jave API it is identifed by
// the empty string. The API never presents underbar but
// accepts it as input (just converts underbar to empty string
// everywhere it sees it).
}
/**
* Gets an unordered list of this aggregate'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 aggregate.
*
* @return a newly created list that copies this aggregate's records
* by reference in no particular order
*/
public List <AggregationRecord>
{
}
return list;
}
/**
* Gets an ordered list of this aggregate's records sequenced by
* their {@link AggregationRecord#getOrdinal() ordinal} property.
* Note that the unordered list returned by {@link #getRecords()}
* can easily be sorted by any arbitrary criteria, for example by
* key ascending:
* <pre><code>
* List <AggregationRecord> records = aggregate.getRecords();
* Collections.sort(records, new Comparator <AggregationRecord> () {
* public int compare(AggregationRecord r1, AggregationRecord r2) {
* return r1.getTuple().compareTo(r2.getTuple());
* }
* });
* </code></pre>
* Use {@code getOrderedRecords()} instead of {@code getRecords()}
* when you want to list records as they would be ordered by {@code
* dtrace(1M)}.
*
* @return a newly created list of this aggregate's records
* in the order used by the native DTrace library
*/
public List <AggregationRecord>
{
}
});
return list;
}
/**
* In the native DTrace library, the unnamed aggregation {@code @}
* is given the name {@code _} (underbar). The Java DTrace API does
* not expose this implementation detail but instead identifies the
* unnamed aggregation with the empty string. Here we convert the
* name of the unnamed aggregation at the earliest opportunity.
* <p>
* Package level access. Called by this class and PrintaRecord when
* adding the Aggregation abstraction on top of native aggregation
* records.
*/
static String
{
return "";
}
return name;
}
/**
* Gets a read-only {@code Map} view of this aggregate.
*
* @return a read-only {@code Map} view of this aggregate keyed by
* aggregation name
*/
asMap()
{
}
/**
* Called by native code.
*
* @throws IllegalStateException if the aggregation with the given
* name already has a record with the same tuple key as the given
* record.
*/
private void
{
if (aggregation == null) {
}
}
/**
* Serialize this {@code Aggregate} instance.
*
* @serialData Serialized fields are emitted, followed by a {@link
* java.util.List} of {@link Aggregation} instances.
*/
private void
{
s.defaultWriteObject();
s.writeObject(getAggregations());
}
@SuppressWarnings("unchecked")
private void
throws IOException, ClassNotFoundException
{
s.defaultReadObject();
// cannot cast to parametric type without compiler warning
// load serialized form into private map as a defensive copy
// check class invariants after defensive copy
try {
validate();
} catch (Exception e) {
e.getMessage());
x.initCause(e);
throw x;
}
}
/**
* Gets a string representation of this aggregate snapshot 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:
* <pre><code>
* class-name[property1 = value1, property2 = value2]
* </code></pre>
*/
public String
toString()
{
}
});
}
}