XdmfHeavyDataController.hpp 8.91 KB
Newer Older
Kenneth Leiter's avatar
Kenneth Leiter committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/*****************************************************************************/
/*                                    XDMF                                   */
/*                       eXtensible Data Model and Format                    */
/*                                                                           */
/*  Id : XdmfHeavyDataController.hpp                                         */
/*                                                                           */
/*  Author:                                                                  */
/*     Kenneth Leiter                                                        */
/*     kenneth.leiter@arl.army.mil                                           */
/*     US Army Research Laboratory                                           */
/*     Aberdeen Proving Ground, MD                                           */
/*                                                                           */
/*     Copyright @ 2011 US Army Research Laboratory                          */
/*     All Rights Reserved                                                   */
/*     See Copyright.txt for details                                         */
/*                                                                           */
/*     This software is distributed WITHOUT ANY WARRANTY; without            */
/*     even the implied warranty of MERCHANTABILITY or FITNESS               */
/*     FOR A PARTICULAR PURPOSE.  See the above copyright notice             */
/*     for more information.                                                 */
/*                                                                           */
/*****************************************************************************/

24 25 26 27 28 29 30 31 32
#ifndef XDMFHEAVYDATACONTROLLER_HPP_
#define XDMFHEAVYDATACONTROLLER_HPP_

// Forward Declarations
class XdmfArray;
class XdmfArrayType;

// Includes
#include <string>
33
#include <vector>
34
#include "XdmfCore.hpp"
35
#include "XdmfSharedPtr.hpp"
36 37 38 39

/**
 * @brief Couples an XdmfArray with heavy data stored on disk.
 *
40 41 42 43 44 45 46 47
 * This is an abstract base class to support the reading of different
 * heavy data formats.
 *
 * Serves as an interface between data stored in XdmfArrays and data
 * stored on disk. When an Xdmf file is read from or written to disk
 * an XdmfHeavyController is attached to XdmfArrays. This allows data
 * to be released from memory but still be accessible or have its
 * location written to light data.
48
 */
49
class XDMFCORE_EXPORT XdmfHeavyDataController {
50

51
public:
52 53 54 55

  virtual ~XdmfHeavyDataController() = 0;

  /**
56 57
   * Get the path of the data set within the heavy data file owned by
   * this controller.
58 59
   * For "/home/output.h5:/foo/data" this is "/foo/data"
   *
60 61 62 63
   * Example of use:
   *
   * C++
   *
64
   * @code {.cpp}
65 66 67
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * std::string examplePath = exampleController->getDataSetPath();
68
   * @endcode
69 70 71
   *
   * Python
   *
72
   * @code {.py}
73 74 75 76 77
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * examplePath = exampleController.getDataSetPath()
78
   * @endcode
79
   *
80 81 82 83
   * @return a std::string containing the path of the data set.
   */
  std::string getDataSetPath() const;

84 85 86
  /**
   * Get the dimensions of the heavy data set owned by this controller.
   *
87 88 89 90
   * Example of use:
   *
   * C++
   *
91
   * @code {.cpp}
92 93 94
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * std::vector<unsigned int>  exampleDimensions = exampleController->getDimensions();
95
   * @endcode
96 97 98
   *
   * Python
   *
99
   * @code {.py}
100 101 102 103 104
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * exampleDimensions = exampleController.getDimensions()
105
   * @endcode
106
   *
107 108 109 110 111
   * @return a vector containing the size in each dimension of the heavy data
   * set owned by this controller.
   */
  std::vector<unsigned int> getDimensions() const;

112
  /**
113 114
   * Get the absolute path to the heavy data file on disk where the
   * data set owned by this controller resides.
115 116
   * For "/home/output.h5:/foo/data" this is "/home/output.h5"
   *
117 118 119 120
   * Example of use:
   *
   * C++
   *
121
   * @code {.cpp]
122 123 124
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * std::string examplePath = exampleController->getFilePath();
125
   * @endcode
126 127 128
   *
   * Python
   *
129
   * @code {.py}
130 131 132 133 134
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * examplePath = exampleController.getFilePath()
135
   * @endcode
136
   *
137 138 139 140 141
   * @return a std::string containing the path to the heavy data file.
   */
  std::string getFilePath() const;

  /**
142 143
   * Get the name of this heavy data format. E.g. "HDF" for hdf5
   * format.
144
   *
145 146 147 148
   * Example of use:
   *
   * C++
   *
149
   * @code {.cpp}
150 151 152
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * std::string exampleName = exampleController->getName();
153
   * @endcode
154 155 156
   *
   * Python
   *
157
   * @code {.py}
158 159 160 161 162
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * exampleName = exampleController.getName()
163
   * @endcode
164
   *
165 166 167 168 169 170 171
   * @return std::string containing the name of this heavy data format
   */
  virtual std::string getName() const = 0;

  /**
   * Get the size of the heavy data set owned by this controller.
   *
172 173 174 175
   * Example of use:
   *
   * C++
   *
176
   * @code {.cpp}
177 178 179
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * unsigned int exampleSize = exampleController->getSize();
180
   * @endcode
181 182 183
   *
   * Python
   *
184
   * @code {.py}
185 186 187 188 189
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * exampleSize = exampleController.getSize()
190
   * @endcode
191
   *
192 193 194 195 196
   * @return a int containing the size of the heavy data set.
   */
  unsigned int getSize() const;

  /**
197 198
   * Get the array type of the heavy data set owned by this
   * controller.
199
   *
200 201 202 203
   * Example of use:
   *
   * C++
   *
204
   * @code {.cpp}
205 206 207
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * shared_ptr<const XdmfArrayType> exampleType = exampleController->getType();
208
   * @endcode
209 210 211
   *
   * Python
   *
212
   * @code {.py}
213 214 215 216 217
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * exampleType = exampleController.getType()
218
   * @endcode
219
   *
220 221
   * @return an XdmfArrayType containing the array type of the heavy data set.
   */
222
  shared_ptr<const XdmfArrayType> getType() const;
223 224

  /**
225 226
   * Read data owned by this controller on disk into the passed
   * XdmfArray.
227
   *
228 229 230 231
   * Example of use:
   *
   * C++
   *
232
   * @code {.cpp}
233 234 235 236 237
   * //Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * //Since XdmfHeavyDataController is an abstract class
   * shared_ptr<XdmfArray> exampleArray = XdmfArray::New();
   * exampleController->read(exampleArray);
   * //exampleArray now holds the data that exampleController holds.
238
   * @endcode
239 240 241
   *
   * Python
   *
242
   * @code {.py}
243 244 245 246 247 248 249 250 251
   * '''
   * Assuming that exampleController is a shared pointer to an XdmfHDF5Controller object
   * Since XdmfHeavyDataController is an abstract class
   * '''
   * exampleArray = XdmfArray.New()
   * exampleController.read(exampleArray)
   * '''
   * exampleArray now holds the data that exampleController holds.
   * '''
252
   * @endcode
253
   *
254 255 256 257
   * @param array and XdmfArray to read data into.
   */
  virtual void read(XdmfArray * const array) = 0;

258
protected:
259 260 261

  XdmfHeavyDataController(const std::string & filePath,
                          const std::string & dataSetPath,
262
                          const shared_ptr<const XdmfArrayType> type,
263
                          const std::vector<unsigned int> & dimensions);
264

265 266 267
  const std::string mDataSetPath;
  const std::vector<unsigned int> mDimensions;
  const std::string mFilePath;
268
  const shared_ptr<const XdmfArrayType> mType;
269

270
private:
271 272 273

  XdmfHeavyDataController(const XdmfHeavyDataController&);  // Not implemented.
  void operator=(const XdmfHeavyDataController &);  // Not implemented.
274 275 276

};

277
#ifdef _WIN32
278
XDMFCORE_TEMPLATE template class XDMFCORE_EXPORT
279
shared_ptr<const XdmfArrayType>;
280 281
#endif

282
#endif /* XDMFHEAVYDATACONTROLLER_HPP_ */