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