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