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    */
020    package org.olap4j;
021    
022    import org.olap4j.metadata.Property;
023    
024    import java.sql.ResultSet;
025    import 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     */
034    public 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