001/*
002// $Id: Cell.java 482 2012-01-05 23:27:27Z jhyde $
003//
004// Licensed to Julian Hyde under one or more contributor license
005// agreements. See the NOTICE file distributed with this work for
006// additional information regarding copyright ownership.
007//
008// Julian Hyde licenses this file to you under the Apache License,
009// Version 2.0 (the "License"); you may not use this file except in
010// compliance with the License. You may obtain a copy of the License at:
011//
012// http://www.apache.org/licenses/LICENSE-2.0
013//
014// Unless required by applicable law or agreed to in writing, software
015// distributed under the License is distributed on an "AS IS" BASIS,
016// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017// See the License for the specific language governing permissions and
018// limitations under the License.
019*/
020package org.olap4j;
021
022import org.olap4j.metadata.Property;
023
024import java.sql.ResultSet;
025import java.util.List;
026
027/**
028 * Cell returned from a {@link CellSet}.
029 *
030 * @author jhyde
031 * @version $Id: Cell.java 482 2012-01-05 23:27:27Z jhyde $
032 * @since Aug 22, 2006
033 */
034public interface Cell {
035    /**
036     * Returns the {@link CellSet} that this Cell belongs to.
037     *
038     * @return CellSet, never null
039     */
040    CellSet getCellSet();
041
042    /**
043     * Returns the ordinal of this Cell.
044     *
045     * <p>The formula is the sequence, zero-based, which the cell would be
046     * visited in a raster-scan through all of the cells of this
047     * {@link CellSet}. The ordinal of the first cell is zero, and the
048     * ordinal of the last cell is the product of the lengths of the axes, minus
049     * 1. For example, if a result has 10 columns and 20
050     * rows, then:<ul>
051     * <li>(row 0, column 0) has ordinal 0,</li>
052     * <li>(row 0, column 1) has ordinal 1,</li>
053     * <li>(row 1, column 0) has ordinal 10,</li>
054     * <li>(row 19, column 9) has ordinal 199.</li>
055     * </ul>
056     *
057     * @return Ordinal of this Cell
058     */
059    int getOrdinal();
060
061    /**
062     * Returns the coordinates of this Cell in its {@link CellSetAxis}.
063     *
064     * <p>This method is provided for convenience. It is equivalent to the
065     * following code:
066     * <blockquote>
067     * <code>
068     *    getResult().ordinalToCoordinateList(getOrdinal())
069     * </code>
070     * </blockquote>
071     *
072     * @return Coordinates of this Cell
073     */
074    List<Integer> getCoordinateList();
075
076    /**
077     * Returns the value of a given property for this Cell.
078     *
079     * <p>The list of allowable properties may be obtained by calling
080     * {@link org.olap4j.CellSet#getMetaData()} followed by
081     * {@link CellSetMetaData#getCellProperties()}.</p>
082     *
083     * <p>Every cell has certain system properties such as "VALUE" and
084     * "FORMAT_STRING" (the full list is described in the
085     * {@link org.olap4j.metadata.Property.StandardCellProperty}
086     * enumeration), as well as extra properties defined by the query.</p>
087     *
088     * @param property Property whose value to retrieve
089     *
090     * @return Value of the given property for this Cell; if the property is
091     * not set, returns null
092     */
093    Object getPropertyValue(Property property);
094
095    /**
096     * Returns whether this cell is empty.
097     *
098     * @return Whether this cell is empty.
099     */
100    boolean isEmpty();
101
102    /**
103     * Returns whether an error occurred while evaluating this cell.
104     *
105     * @return Whether an error occurred while evaluating this cell.
106     */
107    boolean isError();
108
109    /**
110     * Returns whether the value of this cell is NULL.
111     *
112     * @return Whether the value of this cell is NULL.
113     */
114    boolean isNull();
115
116    /**
117     * Returns the value of this cell as a <code>double</code> value.
118     *
119     * <p>Not all values can be represented as using the Java
120     * <code>double</code>, therefore for some providers, {@link #getValue()}
121     * may return a more accurate result.
122     *
123     * @return The value of this cell; if the cell is null, the
124     * returns <code>0</code>
125     *
126     * @throws OlapException if this cell does not have a numeric value
127     */
128    double getDoubleValue() throws OlapException;
129
130    /**
131     * Returns the error message of this Cell, or null if the cell is not
132     * in error.
133     *
134     * <p>If the cell is an error, the value will be an {@link OlapException}.
135     * (This value is returned, not thrown.)
136     *
137     * @return value of this Cell
138     */
139    String getErrorText();
140
141    /**
142     * Returns the value of this Cell.
143     *
144     * <p>If the cell is an error, the value will be an {@link OlapException}.
145     * (This value is returned, not thrown.)
146     *
147     * <p>If the cell has a numeric value, returns an object which implements
148     * the {@link Number} interface.
149     *
150     * @see #getDoubleValue()
151     *
152     * @return value of this Cell
153     */
154    Object getValue();
155
156    /**
157     * Returns the value of this Cell, formatted according to the
158     * FORMAT_STRING property and using the numeric formatting tokens the
159     * current locale.
160     *
161     * <p>The formatted value is never null. In particular, when the cell
162     * contains the MDX NULL value, {@link #getValue()} will return the Java
163     * <code>null</code> value but this method will return the empty string
164     * <code>""</code>.
165     *
166     * @return Formatted value of this Cell
167     */
168    String getFormattedValue();
169
170    /**
171     * Drills through from this cell to the underlying fact table data,
172     * and returns a {@link java.sql.ResultSet} of the results.
173     *
174     * <p>If drill-through is not possible, returns null.
175     *
176     * @return result set of the fact rows underlying this Cell
177     *
178     * @throws OlapException if a database error occurs
179     */
180    ResultSet drillThrough() throws OlapException;
181
182    /**
183     * Sets the value of a cell.
184     *
185     * <p>When this method may be called depends on the provider. But typically,
186     * the connection must at least have an active scenario; see
187     * {@link OlapConnection#setScenario(Scenario)}.
188     *
189     * <p>The number and type of additional arguments specified in the
190     * {@code allocationArgs} parameter depends on the allocation policy chosen.
191     * Some policies, such as {@link AllocationPolicy#EQUAL_ALLOCATION}, do not
192     * require any additional arguments, in which case {@code allocationArgs}
193     * may be {@code null}.
194     *
195     * @param value Cell value
196     * @param allocationPolicy Allocation policy
197     * @param allocationArgs Allocation policy arguments
198     *
199     * @throws OlapException if a database error occurs
200     */
201    void setValue(
202        Object value,
203        AllocationPolicy allocationPolicy,
204        Object... allocationArgs)
205        throws OlapException;
206}
207
208// End Cell.java