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*/
011package mondrian.olap;
012
013import org.olap4j.AllocationPolicy;
014import org.olap4j.Scenario;
015
016import java.util.List;
017
018/**
019 * A <code>Cell</code> is an item in the grid of a {@link Result}.  It is
020 * returned by {@link Result#getCell}.
021 *
022 * @author jhyde
023 * @since 6 August, 2001
024 */
025public interface Cell {
026    /**
027     * Returns the coordinates of this Cell in its {@link Result}.
028     *
029     * @return Coordinates of this Cell
030     */
031    List<Integer> getCoordinateList();
032
033    /**
034     * Returns the cell's raw value. This is useful for sending to further data
035     * processing, such as plotting a chart.
036     *
037     * <p> The value is never null. It may have various types:<ul>
038     *   <li>if the cell is null, the value is  {@link Util#nullValue};</li>
039     *   <li>if the cell contains an error, the value is an instance of
040     *       {@link Throwable};</li>
041     *   <li>otherwise, the type of this value depends upon the type of
042     *       measure: possible types include {@link java.math.BigDecimal},
043     *       {@link Double}, {@link Integer} and {@link String}.</li>
044     * </ul>
045     *
046     * @post return != null
047     * @post (return instanceof Throwable) == isError()
048     * @post (return instanceof Util.NullCellValue) == isNull()
049     */
050    Object getValue();
051
052    /**
053     * Return the cached formatted string, that survives an aggregate cache
054     * clear.
055     */
056    String getCachedFormatString();
057
058    /**
059     * Returns the cell's value formatted according to the current format
060     * string, and locale-specific settings such as currency symbol. The
061     * current format string may itself be derived via an expression. For more
062     * information about format strings, see {@link mondrian.util.Format}.
063     */
064    String getFormattedValue();
065
066    /**
067     * Returns whether the cell's value is null.
068     */
069    boolean isNull();
070
071    /**
072     * Returns whether the cell's calculation returned an error.
073     */
074    boolean isError();
075
076    /**
077     * Returns a SQL query that, when executed, returns drill through data
078     * for this Cell.
079     *
080     * <p>If the parameter {@code extendedContext} is true, then the query will
081     * include all the levels (i.e. columns) of non-constraining members
082     * (i.e. members which are at the "All" level).
083     *
084     * <p>If the parameter {@code extendedContext} is false, the query will
085     * exclude the levels (coulmns) of non-constraining members.
086     *
087     * <p>The result is null if the cell is based upon a calculated member.
088     */
089    String getDrillThroughSQL(boolean extendedContext);
090
091    /**
092     * Returns true if drill through is possible for this Cell.
093     * Returns false if the Cell is based on a calculated measure.
094     *
095     * @return Whether can drill through on this cell
096     */
097    boolean canDrillThrough();
098
099    /**
100     * Returns the number of fact table rows which contributed to this Cell.
101     */
102    int getDrillThroughCount();
103
104    /**
105     * Returns the value of a property.
106     *
107     * @param propertyName Case-sensitive property name
108     * @return Value of property
109     */
110    Object getPropertyValue(String propertyName);
111
112    /**
113     * Returns the context member for a particular dimension.
114     *
115     * The member is defined as follows (note that there is always a
116     * member):<ul>
117     *
118     * <li>If the dimension appears on one of the visible axes, the context
119     * member is simply the member on the current row or column.
120     *
121     * <li>If the dimension appears in the slicer, the context member is the
122     * member of that dimension in the slier.
123     *
124     * <li>Otherwise, the context member is the default member of that
125     * dimension (usually the 'all' member).</ul>
126     *
127     * @param hierarchy Hierarchy
128     * @return current member of given hierarchy
129     */
130    Member getContextMember(Hierarchy hierarchy);
131
132    /**
133     * Helper method to implement {@link org.olap4j.Cell#setValue}.
134     *
135     * @param scenario Scenario
136     * @param newValue New value
137     * @param allocationPolicy Allocation policy
138     * @param allocationArgs Arguments for allocation policy
139     */
140    void setValue(
141        Scenario scenario,
142        Object newValue,
143        AllocationPolicy allocationPolicy,
144        Object... allocationArgs);
145}
146
147// End Cell.java