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