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