00001 //# Table.h: Primary interface for the rest of the browser to a table. 00002 //# Copyright (C) 2007-2008 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id: $ 00027 #ifndef TBTABLE_H_ 00028 #define TBTABLE_H_ 00029 00030 #include <casaqt/QtBrowser/TBConstants.h> 00031 #include <casaqt/QtBrowser/TBPlotter.qo.h> 00032 00033 #include <casa/BasicSL/String.h> 00034 00035 #include <vector> 00036 00037 namespace casa { 00038 00039 //# Forward Declarations 00040 class TBField; 00041 class TBKeyword; 00042 class TBArray; 00043 class ProgressHelper; 00044 class XMLtoken; 00045 class TBParser; 00046 class TBTableDriver; 00047 class TBData; 00048 class TBArrayData; 00049 class TBPlotData; 00050 class TBFilterRuleSequence; 00051 00052 // <summary> 00053 // Parameters to indicate what driver should be used for the table backend. 00054 // </summary> 00055 // 00056 // <synopsis> 00057 // The DriverParams consist of two parameters: the driver type and (if 00058 // applicable) the parser type. The parser type is only used for the XML 00059 // driver. 00060 // </synopsis> 00061 00062 class DriverParams { 00063 public: 00064 // Default Constructor. 00065 DriverParams(tb::Driver t = tb::DIRECT, tb::Parser p = tb::XERCES_SAX) : type(t), 00066 parser(p) { } 00067 00068 // Copy Constructor. 00069 DriverParams(DriverParams* dp) : type(dp->type), parser(dp->parser) { } 00070 00071 00072 // Driver type. 00073 tb::Driver type; 00074 00075 // Parser type (for XML driver). 00076 tb::Parser parser; 00077 }; 00078 00079 // <summary> 00080 // Parameters that define all table data and meta-deta. 00081 // </summary> 00082 // 00083 // <synopsis> 00084 // A TableParams contains references to all important table members. Since 00085 // this information needs to be accessed and potentially changed by both the 00086 // TBTable and the TBTableDriver, the references are shared by passing a 00087 // TableParams object. 00088 // </synopsis> 00089 00090 class TableParams { 00091 public: 00092 TableParams(String& l, bool& ir, bool& rr, 00093 std::vector<std::vector<TBData*>*>& d, 00094 std::vector<TBField*>& f, std::vector<TBKeyword*>& k, 00095 std::vector<int>& sr, int& tr, int& lr, std::vector<bool>& w, bool& t, 00096 DriverParams* dp): location(l), insertRow(ir), removeRow(rr), 00097 data(d), fields(f), keywords(k), subtableRows(sr), 00098 totalRows(tr), loadedRows(lr), writable(w), taql(t), 00099 dParams(dp) { } 00100 00101 00102 // See TBTable::location. 00103 String& location; 00104 00105 // See TBTable::insertRow. 00106 bool& insertRow; 00107 00108 // See TBTable::removeRow. 00109 bool& removeRow; 00110 00111 // See TBTable::data. 00112 std::vector<std::vector<TBData*>*>& data; 00113 00114 // See TBTable::fields. 00115 std::vector<TBField*>& fields; 00116 00117 // See TBTable::keywords. 00118 std::vector<TBKeyword*>& keywords; 00119 00120 // See TBTable::subtableRows. 00121 std::vector<int>& subtableRows; 00122 00123 // See TBTable::totalRows. 00124 int& totalRows; 00125 00126 // See TBTable::loadedRows. 00127 int& loadedRows; 00128 00129 // See TBTable::writable. 00130 std::vector<bool>& writable; 00131 00132 // See TBTable::taql. 00133 bool& taql; 00134 00135 // See TBTable::dParams. 00136 DriverParams* dParams; 00137 }; 00138 00139 // <summary> 00140 // Primary interface for the rest of the browser to a table. 00141 // </summary> 00142 // 00143 // <synopsis> 00144 // Although TBTable is considered the table backend, it is actually more like 00145 // an interface over a TBTableDriver. However, since there may be multiple 00146 // implementations of the driver, the table provides a unified interface over 00147 // the driver as well as other useful operations. Generally speaking, the 00148 // driver handles dealing with the table on disk while the TBTable handles 00149 // dealing with the data represented in memory. 00150 // </synopsis> 00151 00152 class TBTable { 00153 public: 00154 // Constructor that takes the filename and driver parameters. If taql is 00155 // true, then this table is a table constructed from a TaQL command stored 00156 // in filename; otherwise filename holds the location on disk of the table. 00157 TBTable(String filename, DriverParams* dp, bool taql = false); 00158 00159 ~TBTable(); 00160 00161 00162 // Returns the filename where this table is located. 00163 String getFile(); 00164 00165 // Returns the name of this table (which the last the part of the 00166 // filename). If this is a TaQL table, returns "TaQL Table". 00167 String getName(); 00168 00169 // Returns the driver parameters for this table. 00170 DriverParams* getDriverParams(); 00171 00172 // Returns the fields for this table. 00173 std::vector<TBField*>* getFields(); 00174 00175 // Returns the field at the given index, or NULL if there is none. 00176 TBField* field(int i); 00177 00178 // Returns the field with the given name, or NULL if there is none. 00179 TBField* field(String name); 00180 00181 // Returns the table keywords. 00182 std::vector<TBKeyword*>* getTableKeywords(); 00183 00184 // Returns the keyword at the given index, or NULL if there is none. 00185 TBKeyword* keyword(int i); 00186 00187 // Returns the keyword with the given name, or NULL if there is none. 00188 TBKeyword* keyword(String name); 00189 00190 // Indicates if the table is ready for access or not. 00191 bool isReady(); 00192 00193 // Returns true if the underlying table allows for insertion of rows, 00194 // false otherwise. 00195 bool canInsertRows(); 00196 00197 // Returns true if the underlying table allows for deletion of rows, 00198 // false otherwise. 00199 bool canDeleteRows(); 00200 00201 // Returns the total number of rows in the table. 00202 int getTotalRows(); 00203 00204 // Returns the number of rows loaded into the table. 00205 int getLoadedRows(); 00206 00207 // Returns the number of selected rows. Note: this may be different than 00208 // the number of loaded rows. For example, if you load rows [0 - 1000] but 00209 // the table has only 20 rows, getSelectedRows() would return 1000 while 00210 // getLoadedRows() would return 20. 00211 int getSelectedRows(); 00212 00213 // Returns the number of pages in the table. 00214 int getNumPages(); 00215 00216 // Return the currently loaded page. 00217 int getPage(); 00218 00219 // Returns the first loaded row in the table. 00220 int getRowIndex(); 00221 00222 // Returns the number of columns in the table. 00223 int getNumFields(); 00224 00225 // Sets whether the table should print debug information or not. 00226 void setPrintDebug(bool pdb); 00227 00228 // Returns the data at the given indices, or NULL if they are invalid. 00229 TBData* dataAt(unsigned int row, unsigned int col); 00230 00231 // Returns the shape of the array for the given field, or an empty list 00232 // if the field is not an array. 00233 std::vector<int> dataDimensionsAt(unsigned int col); 00234 00235 // Returns whether all the columns in this table are editable or not. 00236 bool isEditable(); 00237 00238 // Returns whether any of the columns in this table are editable or not. 00239 bool isAnyEditable(); 00240 00241 // Returns whether the column at the given index is editable or not. 00242 bool isEditable(int index); 00243 00244 // Returns whether this table is constructed from a TaQL query or not. 00245 bool isTaQL(); 00246 00247 // See TBTableDriver::canRead(). 00248 bool canRead(); 00249 00250 // See TBTableDriver::canWrite(). 00251 bool canWrite(); 00252 00253 // See TBTableDriver::tryWriteLock(). 00254 bool tryWriteLock(); 00255 00256 // See TBTableDriver::releaseWriteLock(). 00257 bool releaseWriteLock(); 00258 00259 00260 // Loads the given rows into the table and returns a Result indicating the 00261 // success of the loading. The rows loaded will be from start to start + 00262 // number (inclusive). If full is true, array data will be included; 00263 // otherwise only the shapes of the array will be included. If columns 00264 // is a non-NULL, non-empty list, then only those fields will be loaded 00265 // into the table. If parsedata is true, the table data will be loaded; 00266 // otherwise only the meta-data will be loaded. If a ProgressHelper is 00267 // provided, the label and progress meter will be periodically updated 00268 // as progress is made. 00269 Result loadRows(int start = 0, 00270 int number = TBConstants::DEFAULT_SELECT_NUM, 00271 bool full = false, std::vector<String>* columns = NULL, 00272 bool parsedata = true, 00273 ProgressHelper* progressPanel = NULL); 00274 00275 // Returns the column headers (field names) for this table. 00276 std::vector<String> getColumnHeaders(); 00277 00278 // Returns the row headers (row numbers) for the loaded rows in this table. 00279 std::vector<String> getRowHeaders(); 00280 00281 // Loads and returns the array at the given indices. 00282 TBArrayData* loadArray(unsigned int row, unsigned int col); 00283 00284 // Release the array at the given indices and returns whether the release 00285 // succeeded. 00286 bool releaseArray(unsigned int row, unsigned int col); 00287 00288 // Edits the data at the given indices to have the new value and returns 00289 // whether the operation succeeded. 00290 Result editData(unsigned int row, unsigned int col, TBData* newVal); 00291 00292 // Updates the table on disk with the new value at the given coordinates 00293 // in the array at the given row and column. oneDim must be true for a 00294 // one-dimensional array, false otherwise. Returns a result indicating 00295 // the success of the editing. 00296 Result editArrayData(unsigned int row, unsigned int col, 00297 std::vector<int> coords, TBData* newVal, bool oneDim); 00298 00299 // Exports the entirety of this table to VOTable XML format to the given 00300 // file. If a ProgressHelper is provided, progress information is updated 00301 // periodically. 00302 void exportVOTable(String file, ProgressHelper* progressPanel = NULL); 00303 00304 // Returns data used for plotting, using the given plot parameters and row 00305 // information. If a ProgressHelper is provided, progress information is 00306 // updated periodically. 00307 TBPlotData* plotRows(PlotParams& x, PlotParams& y, int rowFrom, int rowTo, 00308 int rowInterval, TBFilterRuleSequence* rule = NULL, 00309 ProgressHelper* ph = NULL); 00310 00311 // Returns data used for plotting (an 1-D array and its indices), 00312 // using the given plot parameters, slice axis, and row number. 00313 // If a ProgressHelperis provided, progress information is updated 00314 // periodically. 00315 TBPlotData* plotIndices(PlotParams& dp, int axis, bool x, int row, 00316 TBFilterRuleSequence* rule = NULL, 00317 ProgressHelper* ph = NULL); 00318 00319 // Returns the total number of rows for the table at the given location, or 00320 // -1 for an invalid location or other problem. TBTable caches the total 00321 // rows of all subtables (i.e., tables pointed to in the table keywords). 00322 int totalRowsOf(String location); 00323 00324 // Returns a tooltip for the field at index i. 00325 String fieldToolTip(int i); 00326 00327 // Returns a tooltip for this table. 00328 String tableToolTip(); 00329 00330 // Inserts the given number of rows at the end of the table. Returns a 00331 // Result indicating the success of the operation. 00332 Result insertRows(int n); 00333 00334 // Deletes the given rows from the table. Each element in the vector 00335 // should be a row number. Returns a Result indicating the success of the 00336 // operation. 00337 Result deleteRows(std::vector<int> r); 00338 00339 private: 00340 // Driver parameters. 00341 DriverParams* dParams; 00342 00343 // Location of the table. 00344 String location; 00345 00346 // Indicates whether the table is ready for access or not. 00347 bool ready; 00348 00349 // Indicates whether this table allows for the insertion of rows or not. 00350 bool insertRow; 00351 00352 // Indicates whether this table allows for the deletion of rows or not. 00353 bool removeRow; 00354 00355 // Holds the table data. 00356 std::vector< std::vector<TBData*>* > data; 00357 00358 // The total number of rows in the table. 00359 int totalRows; 00360 00361 // The number of rows currently loaded in the table. 00362 int loadedRows; 00363 00364 // The last number of rows selected for loading during the last load. 00365 int selectedRows; 00366 00367 // The index of the first row loaded in this table. 00368 int rowIndex; 00369 00370 // The table fields. 00371 std::vector<TBField*> fields; 00372 00373 // The table keywords. 00374 std::vector<TBKeyword*> keywords; 00375 00376 // Cache of total number of rows for subtables. 00377 std::vector<int> subtableRows; 00378 00379 // Indicates whether this table is writable or not. 00380 std::vector<bool> writable; 00381 00382 // Indates whether this table was constructed from a TaQL command or not. 00383 bool taql; 00384 00385 // Table driver. 00386 TBTableDriver* driver; 00387 00388 00389 // Helper method for plotRows(). 00390 double getDouble(TBData* d, std::vector<int>* slice, bool complex, bool amp); 00391 00392 // Helper method for plotRows(). 00393 void filter(TBPlotData* data, TBTable& table, TBFilterRuleSequence* rules, 00394 int rowFrom, int rowTo, int rowInterval); 00395 }; 00396 00397 } 00398 00399 #endif /* TBTABLE_H_ */