SDB_Reference - Reference collections

Reference definitions are used to describe any sort of reference collections. Thus, the reference definition is the base for defining local collections (references or relationships) as well as extents.

References can be defined as persistent, temporary, and transient collection or as transient references.

Depending on the type of the reference, it will be updated automatically, on demand or by the application program (context function).

References refer to persistent collection by default, when being defined as a property of a persistent instance or as extent. For persistent references, the transient option must be switched off. Persistent collections never have a source definition.

Collections defined as property (reference or relationship) of temporary or transient instances are, by default, transient or temporary, i.e. transient is supposed to be set to true.

Persistent collections never have a data source. When changing the persistence type to persistent, data source definitions are removed or ignored.

Persistent collections are filled when reading the owning instance or opening an extent. No special user action is required.

Transient references are used to refer to collections defined in the database or in the process, i.e. a transient reference is not defining a collection by itself. Transient references may refer to persistent, temporary, transient or virtual collections.

Transient references are references being defined as property (reference) of an instance (structure). For defining a transient reference, the transient option must be switched on. Transient references must not have index definitions.

Transient references do not define a local collection but may refer to any other collection in the database.

For transient references, settings for index(es), source(s) and create option will be ignored or reset.

Transient references must be set by the application (e.g. in the read handler of an appropriate context class) and may refer to any type of collection.

Transient collection are used for storing view results or a result collection created by the application for a longer period in an application. Transient collections need more memory but are faster than temporary collections. In contrast to temporary collections, transient collections are used for storing small or medium result sets. Transient collections are the most efficient way for random access on small or medium result collections.

Transient collections are references being defined as property (reference) of an instance (structure) or globally as extent. For defining a transient collection, the transient option must be switched on. Transient collections must have at least one index definition and the created option must be switched off.

Transient collections must be filled by the application (e.g. in the read handler of an appropriate context class) or may refer to a source definition (view), which is automatically executed when accessing the collection. The data source expression or function has to be implemented in the context of the transient collection's data type. For instance properties, the view is evaluated for each instance, when referring to a source.

Subordinated transient collections with source definition are calculated after reading the parent instance, only, when being accessed directly (e.g. calling count() or get() for the transient collection). The first access to the transient collection causes the system to calculate the collection completely, which may take some time.

For global references (extents), the view is executed once, when opening the collection. Global collections are opened as transient extents, when the controlled option is switched on. In this case, the transient extent can be accessed from any property handle opened for the extent in the application. The extent will be removed when closing the database object or database handle for which the extent has been opened. Transient extents are created, when the first property handle referring to the transient extent is opened.

Extents not being defined as controlled are defined for the property handle opened, only, and will be removed when deleting the property handle. This is a simple way of referring to predefined queries.

Temporary collection are used for storing view results or a result collection created by the application for a longer period in an application. Temporary collections need less memory but are are not as fast as transient collections. In contrast to transient collections, temporary collections are used for storing large result sets. Temporary collections are the most efficient way for random access on large result collections.

Temporary collections or extents are references being defined globally as extent. For defining a temporary collection, the transient option and the create option must be switched on. Temporary collections must have got at least one index definition.

In contrast to transient collections, temporary collections are stored to a temporary database. Temporary collections must be filled by the application (e.g. in the open handler of an appropriate context class) or may refer to a source definition (view), which is automatically executed when opening the collection.

Temporary collections can be opened as temporary extents, when the controlled option is switched on. In this case, the temporary extent can be accessed from any property handle opened for the extent in the application. The extent will be removed when closing the database object or database handle for which the extent has been opened. Temporary extents are created, when the first property handle referring to the temporary extent is opened.

Extents not being defined as controlled are defined for the property handle opened, only, and will be removed when deleting the property handle. This is a simple way of referring to predefined queries.

When no source has been defined for a temporary collection, the collection must be filled by the application. When a source is defined, the collection is calculated from the source when opening a temporary extent or when initializing the reference after reading its parent instance.

Subordinated temporary collections with source definition are calculated after reading the parent instance, only, when being accessed directly (e.g. calling count() or get() for the temporary collection). The first access to the temporary collection causes the system to calculate the collection completely, which may take some time.

Virtual collection are used for accessing views. Virtual collections provide fast access to the first instance in a view, but it becomes very inefficient for random view access. Usually, virtual collections are used during a short period of the process to browse to a view result sequentially.

Virtual collections or references are also used for providing short cuts to far properties (grand_fathers_name: father(0).father(0).name).

Virtual collections are references being defined as property (reference) of an instance (structure) or globally as extent. For defining a virtual collection, the transient option must be switched on and a source must be defined for the reference or the reference must refer to a static view definition in the type. Virtual collections must not have index definitions and the created option must be switched off.

Usually, virtual collections are transient (bounded) properties, i.e. they are evaluated each time after selecting an instance having virtual collections. In order to avoid re-calculation for virtual properties, thous may marked as permanent transient (persistence type).

When defining a virtual collection as instance property, the collection changes from instance to instance.

Virtual collections are not filled but calculate instances on demand. Virtual collections can be access by position, only. When opening a virtual collection, only the calculation rule is set up.