001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2001-2005 Julian Hyde
008// Copyright (C) 2005-2009 Pentaho and others
009// All Rights Reserved.
010//
011// jhyde, 10 August, 2001
012*/
013package mondrian.rolap;
014
015import mondrian.olap.Util;
016
017/**
018 * A <code>CellReader</code> finds the cell value for the current context
019 * held by <code>evaluator</code>.
020 *
021 * <p>It returns:<ul>
022 * <li><code>null</code> if the source is unable to evaluate the cell (for
023 *   example, <code>AggregatingCellReader</code> does not have the cell
024 *   in its cache). This value should only be returned if the caller is
025 *   expecting it.</li>
026 * <li>{@link Util#nullValue} if the cell evaluates to null</li>
027 * <li>{@link mondrian.olap.Util.ErrorCellValue} if the cell evaluates to an
028 *   error</li>
029 * <li>an Object representing a value (often a {@link Double} or a {@link
030 *   java.math.BigDecimal}), otherwise</li>
031 * </ul>
032 *
033 * @author jhyde
034 * @since 10 August, 2001
035 */
036interface CellReader {
037    /**
038     * Returns the value of the cell which has the context described by the
039     * evaluator.
040     * A cell could have optional compound member coordinates usually specified
041     * using the Aggregate function. These compound members are contained in the
042     * evaluator.
043     *
044     * <p>If no aggregation contains the required cell, returns null.
045     *
046     * <p>If the value is null, returns {@link Util#nullValue}.
047     *
048     * @return Cell value, or null if not found, or {@link Util#nullValue} if
049     * the value is null
050     */
051    Object get(RolapEvaluator evaluator);
052
053    /**
054     * Returns the number of times this cell reader has told a lie
055     * (since creation), because the required cell value is not in the
056     * cache.
057     */
058    int getMissCount();
059
060    /**
061     * @return whether thus cell reader has any pending cell requests that are
062     * not loaded yet.
063     */
064    boolean isDirty();
065}
066
067// End CellReader.java