company logo

Version_Modes - Versioning modes

In order to define a versioning strategy (versioning mode) for an ODABA database, several versioning features are provided. Versioning features may be combined to versioning modes, which defines the way of versioning instances and collections. The following (more or less independent) versioning features may be referred to:

  • Versioning scope: The versioning scope defines the scope for consistent versioning
  • instance - instance scope
  • owner - owner scope
  • objectspace - object space scope
  • database - database scope
  • default - no versioning scope
  • Versioning levels: Versioning levels support managed (hierarchical) or simple versioning
  • managed - major and minor versions are supported. Major versions are always consistent.
  • default - simple (no hierarchical) versioning (major versions are not available)
  • Versioning consistency: Different levels of consistency may be requested
  • synchronized - version numbers are synchronized among versioning scopes (temporal order)
  • default - Independent, i.e. each versioning scope defines its own version numbers

Boldface terms are enumerators for versioning modes. In order to define a versioning strategy, enumerators of different features my be combined or combined enumerators may be selected instead. Some combinations are not supported. E.g. combining database versioning with synchronized versioning does not make sense, since database versioning is always consistent, i.e. synchronized by default. In general, it is more save to use combined enumerator values, which define all supported combinations. After versioning mode has been set, consistency level and versioning scope may be changed (less consistent, smaller scope), when scope and/or consistency level had been defined. When updating versioning modes, one or more of the changes listed below may be included:

  • managed --> simple (default)
  • synchronized --> independent (default)
  • database --> objectspace --> owner --> instance

Until version 12, ODABA supported VM_managed versioning mode, only, in order to manage schema versions. VM_managed versioning mode is still supported because of downward compatibility, only, and cannot be changed without copying the database. Instead of VM_managed versioning mode, one should use VM_managedDatabase versioning mode instead.

database.versioningMode(VM_managed_synchronized_owner);

database.versioningMode(VM_managed | VM_synchronized | VM_owner); // possible but not suggested

Notes:

It is suggested always to refer to combined enumerators, which is more save. Moreover, combining versioning features by or operator is not supported in OSI.

Enumarators overview

Enumerator details

  1. VM_undefined - Versioning mode undefined

    When no version mode has been set for the database, the version mode is selected when creating new versions depending on the function causing a new version.

    Code: 0
    to list
  2. VM_instance - Instance scope versioning

    The most flexible way of creating versions is creating instance scope versions (local versioning). Instance scope versions can be created in order to create an instance history.

    Instance scope versioning allows creating new versions for an instance scope whenever required. Instance scope versions are not time-stamped, but one may refer to the instance timestamp in order to locate an instance version by date/time (supposed the instance inherits from system type __OBJECT ).

    The instance scope is defined by the instance data, collections owned by the instance (but not the referenced instances), MEMO and BLOB references as well as generic attributes. Also extension properties as such belong the the instance scope, but not the instances referenced for e.g. relationship extensions.

    Within the instance scope, instance versioning is consistent for all versions. Considering relationships to other instances, consistency is guaranteed for the current version but not for history. Relationship and reference collections as well as string and binary data references belong to the instance scope and will create proper versions, but changes in related instances are usually not reflected properly considering older versions.

    Instance scope versioning is supported as simple instance scope versioning ( instance ) or as managed instance scope versioning ( managedInstance ), but also in combination with synchronized versioning ( synchronizedInstance , managedSynchronizedInstance )

    In case of simple local versioning up to 4,294,967,295 versions may be created. In this case, major versions are not created, but the two high order bytes of the version number are formally interpreted as major version.

    When combining local with managed versioning, for each major version up to 65,535 minor versions may be created for each instance scope. Minor version numbers are not associated with time stamps.

    Code: 1
    to list
  3. VM_owner - Owner scope versioning

    Another flexible way of creating versions is creating owner scope versions. Owner scopes are global instances (instance owner scope). Owner scope versions can be created in order to preserve the state for a global instance and all the instances recursively owned by the instance or for root extents and its subsets. Versions are consistent within the owner scope. Considering relationships to other global instances, consistency is guaranteed for the current version, only, but not for history.

    Older owner scope versions are consistent considering owning references and relationships, but may become inconsistent concerning relationships to other owner scopes. Using owner scope versions, no versions are created for extents, i.e. extent indexes always reflect the current collection of referenced instances with current key values. Only, when combining owner scope versioning with managed versioning, extent versions are created for major versions.

    Owner scope versioning allows creating new versions for an owner scope whenever required. Owner scope versions are not timestamped, but in case of instance owner scope one may refer to the instance timestamp in order to locate an instance version by date/time (supposed that the global instance (owner) inherits from system type __OBJECT ).

    Owner scope versioning is supported as simple owner scope versioning ( owner ) and as managed owner scope versioning ( managedOwner ), but also in combination with synchronized ( synchronizedOwner , managedSynchronizedOwner )

    Simple owner scope versioning allows creating up to 4,294,967,295 versions for each owner scope. In this case, major versions are not created, but the two high order bytes of the version number are formally interpreted as major version number. When combining owner scope versioning with managed versioning, for each major version up to 65,535 minor versions may be created for an owner scope. Minor version numbers are not associated with time stamps.

    Relationships to other instance owner scopes (global instances) refer to the current state of those instances. The relationship collection belongs to the instance owner scope and will create proper versions, but changes in related instances are not always reflected properly. One may reduce formal consistency problems by using fixed (unchangeable) keys for such relationships and by not deleting related global instances.

    Code: 2
    to list
  4. VM_synchronized - Synchronized versioning

    Synchronized versioning works similar to independent scope versioning but version numbers are uniquely defined on database level and represent the temporal sequence. Thus, proper versions may be selected when accessing related global instances. When selecting an instance in a property handle, related instances are automatically read for the version older or equal to the version of the selected instance. This prevents applications from many inconsistencies, but not from all. Since creating new versions for an instance owner scope A will not automatically create new versions for instance owner scope B, which is referenced via relationship in A. Thus, changes made in A in version v1, v2, ... cannot be reflected properly in B.

    Synchronized versioning also provides flexibility for creating application specific version management. Instance or owner scope versions are not upgraded automatically, but have to be upgraded explicitly by the application. Besides creating new versions, one may upgrade each instance (or collection) to a version number greater than the current owner scope version but lower or equal to the last database version.

    Running synchronized versioning modes is based on versions created on database level, i.e. one must not call the owner scope specific createVersion() function, but Database ::createVersion() , instead. In order to upgrade the owner scope (instance or object space) to a new version, one may call the owner scope specific updateVersion() function. Before creating a new scope version, instance data will be stored for the current instance version, i.e. the function has to be called before entering modifications for the new version.

    In general, synchronized versioning is a better solution than independent versioning concerning consistency, but it is not a perfect one.

    Synchronized versioning may be defined in connection with object space, owner scope or instance versioning. Usually, synchronized versioning makes not much sense in combination with object space versioning, but in some special cases this might be a useful option. One must not define synchronized versioning together with database versioning.

    More about the behavior of synchronized versioning is described in " Versioning scopes ".

    Code: 4
    to list
  5. VM_synchronized_instance - Synchronized instance versioning

    For synchronized instance versioning each new version created for an instance will create a new consecutive version number. Thus, version numbers represent a history, since database entries with lower version numbers are older than those with higher version numbers.

    A roll back to an earlier version allows recreating an earlier state of the database ( Database ::resetVersion() ). One may also reset single instance scope ( Property ::resetVersion() ).

    Version numbers are not associated with timestamps, i.e. one may roll back an instance to a certain version number, but not to a time point. Time stamps are associated implicitly with a version when the instance data type inherits from __OBJECT ( Property ::setInstanceVersion() ).

    Using not-managed synchronized versioning will not explicitly create major version numbers, but the two high order bytes of the version number are formally interpreted as major version.

    database.versioningMode(synchronizedInstance);

    Code: 5
    to list
  6. VM_synchronized_owner - Synchronized owner scope versioning

    For synchronized owner scope versioning each new version created for an owner scope will create a new consecutive version number. Thus, version numbers represent a temporal sequence, since database entries with lower version numbers are older than those with higher version numbers.

    A roll back to an earlier version allows recreating an earlier state of the database ( Database ::resetVersion() ). One may also reset single owner scopes ( Property ::resetVersion() ).

    Version numbers are not associated with timestamps, i.e. one may roll back the owner scope to a certain version number, but not to a time point. Time stamps are associated implicitly with a version when the global instance data type inherits from __OBJECT ( Property ::setInstanceVersion() ).

    Using not-managed synchronized versioning will not explicitly create major version numbers, but the two high order bytes of the version number are formally interpreted as major version.

    database.versioningMode(synchronizedOwner);

    Code: 6
    to list
  7. VM_objectspace - Object space versioning

    Object space versioning makes sense in case of different object spaces defined within a database. Otherwise, database versioning should be used rather than object space versioning.

    Object space versioning creates independent version numbers for each object space, i.e. each object space gets its own consecutive version numbers. Within the object space, versions are consistent. In case of links (relationships) between instances in different object spaces, consistency is guaranteed for the current version, only, but not for history.

    Object space versioning is supported as simple object space versioning ( objectspace ) but also in combination with managed or synchronized versioning.

    Simple object space versioning allows creating up to 4,294,967,295 versions for each object space. No major versions will be created, but the two high order bytes of the version number are formally interpreted as major version numbers.

    When combining object space versioning with managed versioning, for each major version up to 65,535 minor versions may be created for an object space. Minor version numbers are not associated with timestamps.

    Notes:

    In the current ODABA version, object space versioning does not support roll back ( reset() ) to an earlier object space version.

    Code: 8
    to list
  8. VM_synchronized_objectspace - Synchronized object space versioning

    For synchronized object space versioning each new version created for an object space will create a new consecutive version number in the database. Thus, version numbers represent a temporal sequence, since database entries with lower version numbers are older than those with higher version numbers.

    A roll back to an earlier version allows recreating an earlier state of the database ( Database ::resetVersion() ). One cannot, however, roll back an object space to an object space minor version. Version numbers are not associated with timestamps, i.e. one may roll back the owner scope to a certain version number, but not to a time point.

    Using not-managed synchronized versioning will not explicitly create major version numbers, but the two high order bytes of the version number are formally interpreted as major version.

    database.versioningMode(synchronizedObjectspace);

    Notes:

    Rollback for object space versions to minor version may be implemented, but this seems not to be very urgent, so that it had been postponed.

    Code: 12
    to list
  9. VM_database - Database versioning

    Database versioning is the strongest way of versioning strategies. Database versioning creates new database entry versions always for the last version number created (current database version). When creating a new version, the database version will be increased by 1 (similar to synchronized versioning).

    Database versioning always upgrades database entries to the last version number, when going to be updated (copy on write). Thus, consistency is guaranteed for each version.

    Database versioning is supported as simple database versioning ( database ) or as managed database versioning ( managedDatabase ).

    In case of simple database versioning, up to 4,294,967,295 versions may be created. In this case, major (managed) versions are not created explicitly, but the two high order bytes of the version number are formally interpreted as major version number.

    When combining database versioning with managed versioning, for each major version up to 65,535 minor versions may be created. Version numbers are not associated with time stamps.

    Code: 16
    to list
  10. VM_managed - Managed versioning

    Managed versioning creates new database entry versions for the current major database version. Major version may be defined by using a versioning schema, which is maintained in a version list. The version list allows assigning a version to a date/time interval defining the begin and end of a version. Thus, one may also define versions in advance, which automatically start a new version, when the timestamp has been reached (version schema). The number of major versions in a database is limited to 65535.

    Database states for major versions are consistent. Starting a new major version will create new database entry versions, whenever a database entry needs to be updated (copy on write).

    Combining managed versioning with any of the owner scope versioning features allows creating up to 65535 minor versions for each major version.

    Pure managed database versioning is the versioning mode which is supported since ODABA version 8, especially for creating schema versions for resource databases. When pure managed versioning has been defined, it cannot be changed to any other versioning mode.

    More about the behavior of managed versioning is described in " Versioning scopes ".

    database.versioningMode(managed);

    Notes:

    Pure managed versioning is supported in order to be compatible with older database versions, which use this type for schema versioning. For new databases, it is suggested to use managed in combination with other database features.

    Code: 128
    to list
  11. VM_managed_instance - Managed instance versioning

    This versioning mode combines managed and instance scope versioning mode. Between two major versions, up to 65535 instance scope versions (minor versions) may be created for each instance.

    A roll back to an earlier major version allows recreating an earlier state of the database ( Database ::resetMajorVersion() ). One may also reset single owner scopes ( Property ::resetVersion() ).

    Version numbers for minor versions are preceded by the major version number in 16 high order bits of the version number. Creating or starting a new major version will reset the last minor version number, i.e. creating individual versions for instance scopes will start with new major version number and minor version 0.

    database.versioningMode(managedInstance);

    Code: 129
    to list
  12. VM_managed_owner - Managed owner scope versioning

    This versioning mode allows combining managed and owner scope versioning mode. Between two major versions, up to 65535 owner scope minor versions may be created for each owner scope (global instance, extent).

    A roll back to an earlier major version allows recreating an earlier state of the database ( Database ::resetMajorVersion() ). One may also reset single owner scopes ( Property ::resetVersion() ).

    Version numbers for minor versions are preceded by the major version number in 16 high order bits of the version number. Creating or starting a new major version will reset the last minor version number, i.e. creating individual versions for an owner scope will start with new major version number and minor version 0.

    database.versioningMode(managedOwner);

    Code: 130
    to list
  13. VM_managed_synchronized_instance - Managed and synchronized instance versioning

    This versioning mode combines synchronized and managed versioning with instance scope versioning. Between two major versions, up to 65535 synchronized instance scope versions may be created.

    A roll back to an earlier major version allows recreating an earlier state of the database ( Database ::resetVersion() ). One may also reset single instance scopes ( Property ::resetVersion() ).

    Version numbers for minor versions are preceded by the major version number in the two high order bytes of the version number. Creating or starting a new major version will reset the last minor version number, i.e. next minor version number created for any instance scope begins with 0.

    database.versioningMode(managedSynchronizedInstance);

    Code: 133
    to list
  14. VM_managed_synchronized_owner - Managed and synchronized owner scope versioning

    This versioning mode combines synchronized and managed versioning feature with owner scope versioning. Between two major versions, up to 65535 synchronized owner scope versions may be created.

    A roll back to an earlier major version allows recreating an earlier state of the database ( Database ::resetMajorVersion(), Database ::resetVersion() ). One may also reset single owner scopes ( Property ::resetVersion() ).

    Version numbers for minor versions are preceded by the major version number in the two high order bytes of the version number. Creating or starting a new major version will reset the last minor version number, i.e. next minor version number created for any owner scope begins with 0.

    database.versioningMode(managedSynchronizedOwner);

    Code: 134
    to list
  15. VM_managed_objectspace - Managed object space versioning

    This versioning mode combines managed versioning with object space versioning. versions. Between two major versions, up to 65535 minor versions may be created for each object space.

    A roll back to an earlier major version allows recreating an earlier state of the database ( Database ::resetMajorVersion() ). One cannot, however, roll back an object space to an object space minor version.

    Version numbers for minor versions are preceded by the major version number in 16 high order bits of the version number. Creating or starting a new major version for the database will reset the last minor version number for all object spaces, i.e. creating minor versions for object spaces will start with new major version number and minor version number 0.

    Notes:

    Rollback for object space versions to minor version may be implemented, but this seems not to be very urgent, so that it had been postponed.

    Code: 136
    to list
  16. VM_managed_synchronized_objectspace - Managed and synchronized object space versioning

    This versioning mode combines synchronized and managed versioning feature with object space versioning. Between two major versions, up to 65535 synchronized object space versions may be created.

    A roll back to an earlier major version allows recreating an earlier state of the database ( Database ::resetMajorVersion() ). One cannot, however, roll back an object space to an object space minor version.

    Version numbers for minor versions are preceded by the major version number in the two high order bytes of the version number. Creating or starting a new major version will reset the last minor version number, i.e. next minor version number created for any object space begins with 0.

    database.versioningMode(managedSynchronizedObjectspace);

    Notes:

    Rollback for object space versions to minor version may be implemented, but this seems not to be very urgent, so that it had been postponed.

    Code: 140
    to list
  17. VM_managed_database - Managed database versioning

    This versioning mode combines managed (major) and minor database versions. Between two major versions, up to 65535 minor versions may be created for a database.

    A roll back to an earlier major or minor version allows recreating an earlier state of the database ( Database ::resetMajorVersion() , Property ::resetVersion() ).

    Version numbers for minor versions are preceded by the major version number in 16 high order bits of the version number. Creating or starting a new major version will reset the last minor version number, i.e. creating owner scope versions for any kind of owner scope will start with new major version number and minor version 0.

    database.versioningMode(managedDatabase);

    Code: 144
    to list