XdmfHeavyDataController.hpp 9.34 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 "XdmfItemProperty.hpp"
36
#include "XdmfSharedPtr.hpp"
37 38 39 40

/**
 * @brief Couples an XdmfArray with heavy data stored on disk.
 *
41 42 43 44 45 46 47 48
 * 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.
49
 */
50
class XDMFCORE_EXPORT XdmfHeavyDataController : public XdmfItemProperty {
51

52
public:
53 54 55

  virtual ~XdmfHeavyDataController() = 0;

56 57 58
  /**
   * Get the dimensions of the heavy data set owned by this controller.
   *
59 60 61 62
   * Example of use:
   *
   * C++
   *
63
   * @dontinclude ExampleXdmfHeavyDataController.cpp
64 65 66 67
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getDimensions
   * @until //#getDimensions
68 69 70
   *
   * Python
   *
71
   * @dontinclude XdmfExampleHeavyDataController.py
72 73 74 75
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getDimensions
   * @until #//getDimensions
76
   *
77 78
   * @return    A vector containing the size in each dimension of the heavy data
   *            set owned by this controller.
79 80 81
   */
  std::vector<unsigned int> getDimensions() const;

82
  /**
83 84
   * Get the name of this heavy data format. E.g. "HDF" for hdf5
   * format.
85
   *
86 87 88 89
   * Example of use:
   *
   * C++
   *
90
   * @dontinclude ExampleXdmfHeavyDataController.cpp
91 92 93 94
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getName
   * @until //#getName
95 96 97
   *
   * Python
   *
98
   * @dontinclude XdmfExampleHeavyDataController.py
99 100 101 102
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getName
   * @until #//getName
103
   *
104
   * @return    std::string containing the name of this heavy data format
105 106 107 108 109 110
   */
  virtual std::string getName() const = 0;

  /**
   * Get the size of the heavy data set owned by this controller.
   *
111 112 113 114
   * Example of use:
   *
   * C++
   *
115
   * @dontinclude ExampleXdmfHeavyDataController.cpp
116 117 118 119
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getSize
   * @until //#getSize
120 121 122
   *
   * Python
   *
123
   * @dontinclude XdmfExampleHeavyDataController.py
124 125 126 127
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getSize
   * @until #//getSize
128
   *
129
   * @return    An int containing the size of the heavy data set.
130 131 132
   */
  unsigned int getSize() const;

133
  /**
134 135
   * For use in conjunction with heavy data controllers set to arrays
   * the offset within the array from which the controller will be inserted
136 137 138 139 140
   * Is also set when created by a writer.
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
141 142 143 144
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setArrayOffset
   * @until //#setArrayOffset
145 146 147 148
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
149 150 151 152
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setArrayOffset
   * @until #//setArrayOffset
153
   *
154
   * @param     newOffset       The new index at which the controller will be written
155 156 157 158
   */
  void setArrayOffset(unsigned int newOffset);

  /**
159 160
   * Gets the index at which the controller will offset when
   * an array reads it from its associated controllers.
161 162 163 164 165
   * Set when created by a Writer or set manually.
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
166 167 168 169 170 171
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setArrayOffset
   * @until //#setArrayOffset
   * @skipline //#getArrayOffset
   * @until //#getArrayOffset
172 173 174 175
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
176 177 178 179 180 181
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setArrayOffset
   * @until #//setArrayOffset
   * @skipline #//getArrayOffset
   * @until #//getArrayOffset
182
   *
183
   * @return    The offset that the array will read from
184 185 186
   */
  unsigned int getArrayOffset() const;

187
  /**
188 189 190 191 192
   * Get the path of the data set within the heavy data file owned by
   * this controller.
   * For "/home/output.h5:/foo/data" this is "/foo/data"
   *
   * Example of use:
193
   *
194 195 196
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
197 198
   * @skipline //#initialization
   * @until //#initialization
199 200
   * @skipline //#getDataSetPath
   * @until //#getDataSetPath
201 202 203 204
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
205 206
   * @skipline #//initialization
   * @until #//initialization
207 208
   * @skipline #//getDataSetPath
   * @until #//getDataSetPath
209
   *
210
   * @return    A std::string containing the path of the data set.
211
   */
212
  std::string getDataSetPath() const;
213 214

  /**
215 216 217 218 219
   * Get the absolute path to the heavy data file on disk where the
   * data set owned by this controller resides.
   * For "/home/output.h5:/foo/data" this is "/home/output.h5"
   *
   * Example of use:
220
   *
221 222 223
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
224 225
   * @skipline //#initialization
   * @until //#initialization
226 227
   * @skipline //#getFilePath
   * @until //#getFilePath
228 229 230 231
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
232 233
   * @skipline #//initialization
   * @until #//initialization
234 235
   * @skipline #//getFilePath
   * @until #//getFilePath
236
   *
237
   * @return    A std::string containing the path to the heavy data file.
238
   */
239 240 241 242
  std::string getFilePath() const;

  virtual void
  getProperties(std::map<std::string, std::string> & collectedProperties) const = 0;
243

244
  /**
245 246
   * Get the array type of the heavy data set owned by this
   * controller.
247
   *
248 249 250 251
   * Example of use:
   *
   * C++
   *
252
   * @dontinclude ExampleXdmfHeavyDataController.cpp
253 254 255 256
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getType
   * @until //#getType
257 258 259
   *
   * Python
   *
260
   * @dontinclude XdmfExampleHeavyDataController.py
261 262 263 264
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getType
   * @until #//getType
265
   *
266
   * @return    An XdmfArrayType containing the array type of the heavy data set.
267
   */
268
  shared_ptr<const XdmfArrayType> getType() const;
269 270

  /**
271 272
   * Read data owned by this controller on disk into the passed
   * XdmfArray.
273
   *
274 275 276 277
   * Example of use:
   *
   * C++
   *
278
   * @dontinclude ExampleXdmfHeavyDataController.cpp
279 280 281 282
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#read
   * @until //#read
283 284 285
   *
   * Python
   *
286
   * @dontinclude XdmfExampleHeavyDataController.py
287 288 289 290
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//read
   * @until #//read
291
   *
292
   * @param     array   An XdmfArray to read data into.
293 294 295
   */
  virtual void read(XdmfArray * const array) = 0;

296
protected:
297

298
  XdmfHeavyDataController(const std::string & hdf5FilePath,
299
                          const std::string & dataSetPath,
300 301
                          const shared_ptr<const XdmfArrayType> & type,
                          const std::vector<unsigned int> & dimensions);
302

303 304 305
  const std::string mDataSetPath;
  const std::vector<unsigned int> mDimensions;
  const std::string mFilePath;
306
  const shared_ptr<const XdmfArrayType> mType;
307
  unsigned int mArrayStartOffset;
308

309
private:
310 311 312

  XdmfHeavyDataController(const XdmfHeavyDataController&);  // Not implemented.
  void operator=(const XdmfHeavyDataController &);  // Not implemented.
313 314 315

};

316
#ifdef _WIN32
317
XDMFCORE_TEMPLATE template class XDMFCORE_EXPORT
318
shared_ptr<const XdmfArrayType>;
319 320
#endif

321
#endif /* XDMFHEAVYDATACONTROLLER_HPP_ */