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