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