io.deephaven.engine.table.impl.by.AggregationRowLookup Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of deephaven-engine-table Show documentation

Engine Table: Implementation and closely-coupled utilities

There is a newer version: 0.37.1

Show newest version

package io.deephaven.engine.table.impl.by;

import static io.deephaven.engine.rowset.RowSequence.NULL_ROW_KEY;

/**
 * Tool to identify the aggregation result row key (also row position) from a logical key representing a set of values
 * for the aggregation's group-by columns.
 */
public interface AggregationRowLookup {

    /**
     * Re-usable empty key, for use in (trivial) reverse lookups against no-key aggregations.
     */
    Object[] EMPTY_KEY = new Object[0];

    /**
     * Re-usable unknown row constant to serve as the default return value for {@link #noEntryValue()}.
     */
    int DEFAULT_UNKNOWN_ROW = (int) NULL_ROW_KEY;

    /**
     * Gets the row key value where {@code key} exists in the aggregation result table, or the {@link #noEntryValue()}
     * if {@code key} is not found in the table.
     * 
     * This serves to map group-by column values to the row position (also row key) in the result table. Missing keys
     * will map to {@link #noEntryValue()}.
     * 

     * Keys are specified as follows:
     * 

     * No group-by columns
     * "Empty" keys are signified by the {@link AggregationRowLookup#EMPTY_KEY} object, or any zero-length
     * {@code Object[]}
     * One group-by column
     * Singular keys are (boxed, if needed) objects
     * Multiple group-by columns
     * Compound keys are {@code Object[]} of (boxed, if needed) objects, in the order of the aggregation's group-by
     * columns
     * 
     * 
     * All key fields must be reinterpreted to the appropriate primitive value before boxing. See
     * {@link io.deephaven.engine.table.impl.sources.ReinterpretUtils#maybeConvertToPrimitive}.
     *
     * @param key A single (boxed) value for single-column keys, or an array of (boxed) values for compound keys
     * @return The row key where {@code key} exists in the table
     */
    int get(Object key);

    /**
     * @return The value that will be returned from {@link #get(Object)} if no entry exists for a given key
     */
    default int noEntryValue() {
        return DEFAULT_UNKNOWN_ROW;
    }
}