TBTable.h

Go to the documentation of this file.
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_ */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1