Defining version slices
In order to provide consistent versioning for an object space, version slices need to be defined by creating object space versions. When creating a new version slice for an object space, modifications on instances will create new instance versions automatically. Moreover, indices and relationships of the older versions are duplicated before being modified in the newer version.
In order to define new version slice, the DBVersion utility might be called or versions could be maintained calling appropriate ObjectSpace functions. New version slices can be defined, removed or timestamp of version slice might be changed.
When no versioning mode has been set so far, versioning mode is set to Consistent when terminating the first version slice for the root object space or database ( ObjectSpace ::createDataVersion() ). The version mode might, however, also be set in advance.
By default, the version 0 is defined for each object space as open version slice, which will never terminate, until a new version slice will be created. The first version slice has got an open starting point. The last version slice always has got an open termination point. Time intervals for time slices cannot overlap and there are never gaps between time slices.
One may reset a complete time slice, which will remove all changes made in this time slice.
// DBVersion Utility: set version mode
DBVersion.exe c:\Sample\sample.dat -M:C[onsistent]
// set version mode from within a program: Database dbh;
... fragment ( ObjectSpace &dbh ) {
dbh.versioningMode(Consistent);
}
All though version support is an object space feature, the current ODABA version provides full supports for version slices for root object space, only. One may define versions for subordinated vobject spaces as well, but resetting versions will work properly only for the complete database. In order to be able to reset versions, version sliced for subordinated object spaces should be synchronized with the root object space.
In order to create a new version slice, the DBVersion utility might be called or versions could be created by calling ObjectSpace ::createDataVersion() . When creating a new data version, the current version will get a termination time point, which is the starting time point for the new version slice. By default, the starting point is the current time.
Using object versions, version slices are timestamped. Thus, one may define the starting points of new versions in advance ( ObjectSpace ::createDataVersion() ). When opening the database, object spaces automatically activate the version valid for the current time point, i.e. the version automatically changes, when the time for the new version has been reached.
The last defined version is always an open version, which is valid, until the next version will be created defining the end of the current version.
// DBVersion Utility: Create new version slice
DBVersion.exe c:\Sample\sample.dat -C -T(2010-01-01 00:00:00,00)
// create new version from within a program: ObjectSpace osh;
... fragment ( ObjectSpace &osh ) {
osh.createDataVersion(DateTime("2010-01-01 00:00:00,00"));
}
Versions are not automatically changed, when the object space has been opened, i.e. in oder to adjust the version currently active for an object space, one has to close the object space (database) and reopen it again.
In order to change version slice borders, version slice intervals might be updated. Updating version slice termination date is possible via the DBVersion utility or by calling ObjectSpace ::updateDataVersion() . As long as versions are defined in the future, the version interval might be updated. Once, a version has been activated, version borders cannot be changed anymore.
Changing version slice borders is possible for active and future version slices, but not for version slices, which had already been closed, i.e. where the termination date has already expired. When updating the termination date for a version slice, the timestamp value has to be between the termination data of the previous and the next version slice. The termination date for the last version slice is always open and cannot be updated.
// DBVersion Utility: Update version slice
DBVersion.exe c:\Sample\sample.dat -U -V:5 -T(2010-06-01)
// Update version slice from within a program: ObjectSpace osh;
... fragment ( ObjectSpace &osh ) {
osh.updateDataVersion(5,DateTime("2010-01-01"));
}
When versioning mode is Consistent , all object space versions of a database can be reset. Resetting versions for the object spaces to an earlier version (roll back) can be done by calling the DBVersion utility or by calling Database ::resetDataVersion() . Resetting a version will remove all database version entries from the database with a version number greater than the version number to be reset. Finally, the object space version numbers are reset to the given version slice.
Resetting version numbers also removes database entries with higher version numbers. Thus, one cannot undo a version reset.
// DBVersion Utility: Update version slice
DBVersion.exe c:\Sample\sample.dat -R -V:5
// Update version slice from within a program: Database dbh;
... fragment ( Database &dbh ) {
dbh.resetDataVersion(5);
}
In order to reset version slice in databases with object space hierarchies, versions for all object spaces have to be synchronized.
In order to browse data for an older version, one may set the version for an object space by calling ObjectSpace ::setDataVersion() . Older versions should be used in read mode, only.
Instances, which have already been updated in a higher database version cannot be updated at all. Instances, which have not been changed in higher versions, might be updated, but this may lead to conflicts (e.g. when indexes needs to be maintained, which already got a higher version). Thus, browsing data only is suggested, when activating older versions.
In order to retrieve information about start and stop time for version slices, one might call the list operation of the DBVersion utility or call ObjectSpace ::dataVersionInterval() .
// DBVersion Utility: List version slices
DBVersion.exe c:\Sample\sample.dat -L
// Update version slice from within a program: ObjectSpace osh;
... fragment ( ObjectSpace &osh ) {
int i = 0;
int count = osh.dataVersionCount();
DateTime start, stop;
while ( i < count ) {
osh.dataVersionIntervall(i,start,stop);
// print i, start, stop
}
}