Tiled Data Storage Manager using the shape as id. More...

#include <TiledShapeStMan.h>

Inheritance diagram for casa::TiledShapeStMan:

Public Member Functions
	TiledShapeStMan (const String &hypercolumnName, const IPosition &defaultTileShape, uInt maximumCacheSize=0)
	Create a TiledShapeStMan storage manager for the hypercolumn with the given name.
	TiledShapeStMan (const String &hypercolumnName, const Record &spec)
	~TiledShapeStMan ()

virtual DataManager *	clone () const
	Clone this object.
virtual String	dataManagerType () const
	Get the type name of the data manager (i.e.
virtual Record	dataManagerSpec () const
	Return a record containing data manager specifications and info.
virtual Bool	canAccessColumn (Bool &reask) const
	TiledShapeStMan can access a column if there are 2 hypercubes and the first one is empty.
virtual TSMCube *	singleHypercube ()
	Test if only one hypercube is used by this storage manager.
virtual void	setShape (uInt rownr, TSMCube *hypercube, const IPosition &shape, const IPosition &tileShape)
	Set the shape and tile shape of the given hypercube.
Static Public Member Functions
static DataManager *	makeObject (const String &dataManagerType, const Record &spec)
	Make the object from the type name string.
Private Member Functions
	TiledShapeStMan ()
	Create a TiledShapeStMan.
	TiledShapeStMan (const TiledShapeStMan &)
	Forbid copy constructor.
TiledShapeStMan &	operator= (const TiledShapeStMan &)
	Forbid assignment.
virtual IPosition	defaultTileShape () const
	Get the default tile shape.
void	addRow (uInt nrrow)
	Add rows to the storage manager.
Int	findHypercube (const IPosition &shape)
	Find the hypercube for the given shape.
void	addHypercube (uInt rownr, const IPosition &cubeShape, const IPosition &tileShape)
	Add a hypercube.
void	extendHypercube (uInt rownr, uInt cubeNr)
	Extend the hypercube with the given number of elements in the last dimension.
virtual TSMCube *	getHypercube (uInt rownr)
	Get the hypercube in which the given row is stored.
virtual TSMCube *	getHypercube (uInt rownr, IPosition &position)
	Get the hypercube in which the given row is stored.
virtual void	setupCheck (const TableDesc &tableDesc, const Vector< String > &dataNames) const
	Check if the hypercolumn definition fits this storage manager.
virtual Bool	flush (AipsIO &, Bool fsync)
	Flush and optionally fsync the data.
virtual void	create (uInt nrrow)
	Let the storage manager create files as needed for a new table.
virtual void	readHeader (uInt nrrow, Bool firstTime)
	Read the header info.
void	updateRowMap (uInt cubeNr, uInt pos, uInt rownr)
	Update the map of row numbers to cube number plus offset.
void	extendRowMap (uInt nrow)
	Extend the map of row numbers to cube number plus offset will new empty entries.
Private Attributes
IPosition	defaultTileShape_p
	The default tile shape.
Block< uInt >	rowMap_p
	The map of row number to cube and position in cube.
Block< uInt >	cubeMap_p
Block< uInt >	posMap_p
uInt	nrUsedRowMap_p
	The nr of elements used in the map blocks.
Int	lastHC_p
	The last hypercube found.

Detailed Description

Tiled Data Storage Manager using the shape as id.

Intended use:

Public interface

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25

Prerequisite

TiledStMan
TSMCube
ROTiledStManAccessor for a discussion of the maximum cache size

Etymology

TiledShapeStMan is the Tiled Storage Manager where the shape is used as id to support variable shaped arrays.

Synopsis

TiledShapeStMan is a derivation from TiledStMan, the abstract tiled storage manager class. A description of the basics of tiled storage managers is given in the Tables module description.

TiledShapeStMan creates a hypercube for each different shape of the data arrays. For example, if a table contains line and continuum data of an observation, it results in 2 hypercubes. TiledShapeStMan does it all automatically, so it is much easier to use than class TiledDataStMan .
TiledShapeStMan is meant for columns with not too many different shapes, otherwise looking for a matching hypercube may take too long. When many different shapes are used, class TiledCellStMan should be used instead.

TiledShapeStMan has the following (extra) properties:

It can only handle columns containing arrays, thus not scalars.
Addition of a row sets the appropriate data arrays in that row temporarily to an empty hypercube. However, if the data arrays have a fixed shape, the shape is known and the hypercube can be generated immediately. Note that for a fixed shape column, one can as well use class TiledColumnStMan .
When the shape of the data array in a row is set for the first time, it is known which hypercube should be used or if a new hypercube has to be created.
Note that is is not possible to change the shape of an array. If that is needed, TiledCellStMan should be used instead.
Note that a hypercolumn has a given dimensionality, so each data cell in the hypercolumn has to match that dimensionality.
Although there are multiple hypercubes, an id value is not needed. The shape serves as the id value.
Coordinates for the hypercubes can be defined and (of course) their shapes have to match the hypercube shape. Their values have to be put explicitly (so it is not possible to define them via an addHypercube call like in TiledDataStMan ). It is possible to put the coordinate values before or after the shape of the data array in that row is defined.
It is possible to define a (default) tile shape in the TiledShapeStMan constructor. When setting the shape of the array in a row (using ArrayColumn::setShape ), it is possible to override that default for the hypercube in this particular row. However, since the tile shape is only used when creating a hypercube, using an overriding tile shape makes only sense when a given array shape is used for the first time. Note that the dimensionality of the hypercube is one higher than the dimensionality of the data arrays (since the hypercube contains multiple rows). It means that the number of values in tile shape can be one more than the number of axes in the data array. The last tile shape value defaults to 1; the other tile shape values have to be defined.

Motivation

TiledDataStMan proved to be very powerful, but also a bit cumbersome to use because a few special functions need to be called. TiledShapeStMan alleviates that problem.

Example

     // Define the table description and the columns in it.
     TableDesc td ("", "1", TableDesc::Scratch);
     td.addColumn (ArrayColumnDesc<float>  ("RA", 1));
     td.addColumn (ArrayColumnDesc<float>  ("Dec", 1));
     td.addColumn (ScalarColumnDesc<float> ("Velocity"));
     td.addColumn (ArrayColumnDesc<float>  ("Image", 2));
     // Define the 3-dim hypercolumn with its data and coordinate columns.
     // Note that its dimensionality must be one higher than the dimensionality
     // of the data cells.
     td.defineHypercolumn ("TSMExample",
                          3,
                          stringToVector ("Image"),
                          stringToVector ("RA,Dec,Velocity"));
     // Now create a new table from the description.
     SetupNewTable newtab("tTiledShapeStMan_tmp.data", td, Table::New);
     // Create a TiledShapeStMan storage manager for the hypercolumn
     // and bind the columns to it.
     // The (default) tile shape has to be specified for the storage manager.
     TiledShapeStMan sm1 ("TSMExample", IPosition(3,16,32,32));
     newtab.bindAll (sm1);
     // Create the table.
     Table table(newtab);
     // Define the values for the coordinates of the hypercube.
     Vector<float> raValues(512);
     Vector<float> DecValues(512);
     indgen (raValues);
     indgen (decValues, float(100));
     ArrayColumn<float> ra (table, "RA");
     ArrayColumn<float> dec (table, "Dec");
     ScalarColumn<float> velocity (table, "Velocity");
     ArrayColumn<float> image (table, "Image");
     Cube<float> imageValues(IPosition(2,512,512));
     indgen (imageValues);
     // Write some data into the data columns.
     uInt i;
     for (i=0; i<64; i++) {
         table.addRow();
         image.put (i, imageValues);
         ra.put (i, raValues);
         dec.put (i, decValues);
         velocity.put (i, float(i));
     }

Note that in this example the same shape is used for each row, but it could have been different.

Definition at line 184 of file TiledShapeStMan.h.

Constructor & Destructor Documentation

casa::TiledShapeStMan::TiledShapeStMan	(	const String &	hypercolumnName,
		const IPosition &	defaultTileShape,
		uInt	maximumCacheSize = `0`
	)

Create a TiledShapeStMan storage manager for the hypercolumn with the given name.

The hypercolumn name is also the name of the storage manager. The given maximum cache size (default is unlimited) is persistent, thus will be reused when the table is read back. Note that the class ROTiledStManAccessor allows one to overwrite the maximum cache size temporarily.
The constructor taking a Record expects fields in the record with the name of the arguments in uppercase. If not defined, their default value is used.

casa::TiledShapeStMan::TiledShapeStMan	(	const String &	hypercolumnName,
		const Record &	spec
	)

casa::TiledShapeStMan::~TiledShapeStMan ( )

casa::TiledShapeStMan::TiledShapeStMan ( ) [private]

Create a TiledShapeStMan.

This constructor is private, because it should only be used by makeObject.

casa::TiledShapeStMan::TiledShapeStMan ( const TiledShapeStMan & ) [private]

Forbid copy constructor.

Member Function Documentation

void casa::TiledShapeStMan::addHypercube	(	uInt	rownr,
		const IPosition &	cubeShape,
		const IPosition &	tileShape
	)		`[private]`

Add a hypercube.

The number of rows in the table must be large enough to accommodate this hypercube. The possible id values must be given in the record, while coordinate values are optional. The field names in the record should match the coordinate and id column names. The last dimension in the cube shape can be zero, indicating that the hypercube is extensible.

void casa::TiledShapeStMan::addRow ( uInt nrrow ) [private, virtual]

Add rows to the storage manager.

Reimplemented from casa::DataManager.

virtual Bool casa::TiledShapeStMan::canAccessColumn ( Bool & reask ) const [virtual]

TiledShapeStMan can access a column if there are 2 hypercubes and the first one is empty.

reask is set to True (because next time things might be different).

Reimplemented from casa::TiledStMan.

virtual DataManager* casa::TiledShapeStMan::clone ( ) const [virtual]

Clone this object.

It does not clone TSMColumn objects possibly used.

Implements casa::DataManager.

virtual void casa::TiledShapeStMan::create ( uInt nrrow ) [private, virtual]

Let the storage manager create files as needed for a new table.

This allows a column with an indirect array to create its file.

Implements casa::DataManager.

virtual Record casa::TiledShapeStMan::dataManagerSpec ( ) const [virtual]

Return a record containing data manager specifications and info.

Reimplemented from casa::TiledStMan.

virtual String casa::TiledShapeStMan::dataManagerType ( ) const [virtual]

Get the type name of the data manager (i.e.

TiledShapeStMan).

Implements casa::DataManager.

virtual IPosition casa::TiledShapeStMan::defaultTileShape ( ) const [private, virtual]

Get the default tile shape.

Reimplemented from casa::TiledStMan.

void casa::TiledShapeStMan::extendHypercube	(	uInt	rownr,
		uInt	cubeNr
	)		`[private]`

Extend the hypercube with the given number of elements in the last dimension.

The record should contain the id values (to get the correct hypercube) and optionally coordinate values for the elements added.

void casa::TiledShapeStMan::extendRowMap ( uInt nrow ) [private]

Extend the map of row numbers to cube number plus offset will new empty entries.

Int casa::TiledShapeStMan::findHypercube ( const IPosition & shape ) [private]

Find the hypercube for the given shape.

It returns -1 when not found.

virtual Bool casa::TiledShapeStMan::flush	(	AipsIO &	,
		Bool	fsync
	)		`[private, virtual]`

Flush and optionally fsync the data.

It returns a True status if it had to flush (i.e. if data have changed).

Implements casa::DataManager.

virtual TSMCube* casa::TiledShapeStMan::getHypercube ( uInt rownr ) [private, virtual]

Get the hypercube in which the given row is stored.

Implements casa::TiledStMan.

virtual TSMCube* casa::TiledShapeStMan::getHypercube	(	uInt	rownr,
		IPosition &	position
	)		`[private, virtual]`

Get the hypercube in which the given row is stored.

It also returns the position of the row in that hypercube.

Implements casa::TiledStMan.

static DataManager* casa::TiledShapeStMan::makeObject	(	const String &	dataManagerType,
		const Record &	spec
	)		`[static]`

Make the object from the type name string.

This function gets registered in the DataManager "constructor" map.

TiledShapeStMan& casa::TiledShapeStMan::operator= ( const TiledShapeStMan & ) [private]

Forbid assignment.

virtual void casa::TiledShapeStMan::readHeader	(	uInt	nrrow,
		Bool	firstTime
	)		`[private, virtual]`

Read the header info.

Implements casa::TiledStMan.

virtual void casa::TiledShapeStMan::setShape	(	uInt	rownr,
		TSMCube *	hypercube,
		const IPosition &	shape,
		const IPosition &	tileShape
	)		`[virtual]`

Set the shape and tile shape of the given hypercube.

It is used when the first row in a new hypercube is written. If needed it adds a dimension to the shape, which reflects the row dimension. The tile shape in that dimension is by default 1.

Reimplemented from casa::TiledStMan.