Tuple.java revision e77b06d21580f630e0a7c437495ab283d3672828
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER START
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The contents of this file are subject to the terms of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Common Development and Distribution License (the "License").
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You may not use this file except in compliance with the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * See the License for the specific language governing permissions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and limitations under the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * When distributing Covered Code, include this CDDL HEADER in each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * If applicable, add the following below this CDDL HEADER, with the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * fields enclosed by brackets "[]" replaced with your own identifying
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * information: Portions Copyright [yyyy] [name of copyright owner]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER END
e77b06d21580f630e0a7c437495ab283d3672828tomee * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Use is subject to license terms.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ident "%Z%%M% %I% %E% SMI"
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Multi-element key to a value in an {@link Aggregation}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Tuple equality is based on the length of each tuple and the equality
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of each corresponding element. The natural ordering of tuples is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * based on a lenient comparison designed not to throw exceptions when
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * corresponding elements are not mutually comparable or the number of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * tuple elements differs.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Immutable. Supports persistence using {@link java.beans.XMLEncoder}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @author Tom Erickson
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeepublic final class Tuple implements Serializable, Comparable <Tuple>,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee static final long serialVersionUID = 5192674716869462720L;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The empty tuple has zero elements and may be used to obtain the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * singleton {@link AggregationRecord} of a non-keyed {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Aggregation}, such as the one derived from the D statement
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * <code>@a = count()</code>. (In D, an aggregation without
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * square brackets aggregates a single value.)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee BeanInfo info = Introspector.getBeanInfo(Tuple.class);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Need to prevent DefaultPersistenceDelegate from using
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * overridden equals() method, resulting in a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * StackOverFlowError. Revert to PersistenceDelegate
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * implementation. See
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * 477019&tstart=135
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee protected boolean
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee d.setValue("persistenceDelegate", persistenceDelegate);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /** @serial */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // expected to be a short list (usually one to three elements)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Creates a tuple with the given elements in the given order.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param tupleElements ordered series of tuple elements
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given array or any of its
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * elements is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (r == null) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Creates a tuple with the given element list in the given list
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @param tupleElements ordered list of tuple elements
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if the given list or any of its
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * elements is {@code null}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee throw new NullPointerException("element list is null");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (r == null) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Called by native code.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws NullPointerException if element is null
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @throws IllegalArgumentException if element is neither a {@link
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ValueRecord} nor one of the DTrace primitive types returned by
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * {@link ScalarRecord#getValue()}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee private void
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee throw new NullPointerException("tuple element is null at " +
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a modifiable list of this tuple's elements in the same order
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * as their corresponding variables in the original D program tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Modifying the returned list has no effect on this tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Supports XML persistence.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a modifiable list of this tuple's elements in the same order
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * as their corresponding variables in the original D program tuple
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a read-only {@code List} view of this tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a read-only {@code List} view of this tuple
e77b06d21580f630e0a7c437495ab283d3672828tomee return Collections. <ValueRecord> unmodifiableList(elements);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the number of elements in this tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return non-negative element count
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Returns {@code true} if this tuple has no elements.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return {@code true} if this tuple has no elements, {@code false}
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * otherwise
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @see Tuple#EMPTY
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public boolean
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets the element at the given tuple index (starting at zero).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return non-null tuple element at the given zero-based index
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets an iterator over the elements of this tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return an iterator over the elements of this tuple
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Compares the specified object with this {@code Tuple} instance
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * for equality. Defines equality as having the same elements in
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the same order.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return {@code true} if and only if the specified object is of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * type {@code Tuple} and both instances have the same size and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * equal elements at corresponding tuple indexes
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public boolean
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (o instanceof Tuple) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee return false;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Overridden to ensure that equals instances have equal hash codes.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // lenient sort does not throw exceptions
127bbe13a6d36580af6a8ded154f1201a6250772tomee private static int
127bbe13a6d36580af6a8ded154f1201a6250772tomee cmp = ProbeData.compareUnsigned(Comparable.class.cast(o1),
127bbe13a6d36580af6a8ded154f1201a6250772tomee // Compare string values.
127bbe13a6d36580af6a8ded154f1201a6250772tomee } else if (o1 instanceof byte[] && o2 instanceof byte[]) {
127bbe13a6d36580af6a8ded154f1201a6250772tomee // Compare string values.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Defines the natural ordering of tuples. Uses a lenient algorithm
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * designed not to throw exceptions. Sorts tuples by the natural
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * ordering of corresponding elements, starting with the first pair
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of corresponding elements and comparing subsequent pairs only
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * when all previous pairs are equal (as a tie breaker). If
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * corresponding elements are not mutually comparable, it compares
127bbe13a6d36580af6a8ded154f1201a6250772tomee * the string values of those elements. If all corresponding
127bbe13a6d36580af6a8ded154f1201a6250772tomee * elements are equal, then the tuple with more elements sorts
127bbe13a6d36580af6a8ded154f1201a6250772tomee * higher than the tuple with fewer elements.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * @return a negative integer, zero, or a postive integer as this
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * tuple is less than, equal to, or greater than the given tuple
127bbe13a6d36580af6a8ded154f1201a6250772tomee * @see Tuple#compare(Tuple t1, Tuple t2, int pos)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee for (int i = 0; (cmp == 0) && (i < len) && (i < tlen); ++i) {
127bbe13a6d36580af6a8ded154f1201a6250772tomee * Compares corresponding tuple elements at the given zero-based
127bbe13a6d36580af6a8ded154f1201a6250772tomee * index. Elements are ordered as defined in the native DTrace
127bbe13a6d36580af6a8ded154f1201a6250772tomee * library, which treats integer values as unsigned when sorting.
127bbe13a6d36580af6a8ded154f1201a6250772tomee * @param t1 first tuple
127bbe13a6d36580af6a8ded154f1201a6250772tomee * @param t2 second tuple
127bbe13a6d36580af6a8ded154f1201a6250772tomee * @param pos nth tuple element, starting at zero
127bbe13a6d36580af6a8ded154f1201a6250772tomee * @return a negative integer, zero, or a postive integer as the
127bbe13a6d36580af6a8ded154f1201a6250772tomee * element in the first tuple is less than, equal to, or greater
127bbe13a6d36580af6a8ded154f1201a6250772tomee * than the element in the second tuple
127bbe13a6d36580af6a8ded154f1201a6250772tomee * @throws IndexOutOfBoundsException if the given tuple index {@code
127bbe13a6d36580af6a8ded154f1201a6250772tomee * pos} is out of range {@code (pos < 0 || pos >= size())} for
127bbe13a6d36580af6a8ded154f1201a6250772tomee * either of the given tuples
127bbe13a6d36580af6a8ded154f1201a6250772tomee public static int
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee private void
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // Make a defensive copy of elements
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee throw new InvalidObjectException("element list is null");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee // check class invariants
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (e == null) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Gets a string representation of this tuple's elements in the same
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * format as that returned by {@link AbstractCollection#toString()}.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The representation, although specified, is subject to change.