Model classes

Hide Navigation Pane

Model classes

Previous topic Next topic No directory for this topic  

Model classes

Previous topic Next topic Topic directory requires JavaScript JavaScript is required for the print function Mail us feedback on this topic!  

Persistate generates one class in the Model module for each object class that you define in your definition file.  The class hierarchy of the generated classes reflects exactly the hierarchy you define in the file.  Each generated class is held in two files, as partial classes.  For a class called MyClass, these will be MyClass.cs and MyClass.gen.cs.  The first file is the one you use for your own development.  The  second contains all the generated fields, properties and methods, and is recreated every time you process the definition file.

Persistate also generates one struct in the Model module for each multi-value data class.  This is also created in two parts, in a similar way to generated classes.  Persistate generates these structs, rather than simply using enums, for a number of reasons.  For example, it allows the use of display names for each value, and also allows you to write methods for them.

Finally, Persistate generates a class called The.  In this class, there will be one property for every singleton class that you defined in your definition file.  Singleton classes are so called because there is only a single instance in any deployment of your application, and these are at the root of the portion of the persistent tree used by the application.  In the Example Definition File, there is one singleton called Library, and this will be available in code through the property The.Library.

Generated Object Classes

For each object class in your definition file, Persistate generates a C# class.  This generated class can be quite complex, so the following list is a concise summary of the contents.

Members to access the object class meta-data.  The instance property Class and static property ItsObjectClass both return an ObjectClass object which you can use to discover details of the persistent class definition.  The ClassFlags property returns a value containing a number of flags holding important information about the object.
Methods which perform serialisation or persistence functions.  These transfer data in and out of the databases and inter-module messages.  You never have to use these directly, as they are used internally by the Persistate run-time.
Utility members, such as the NominativeText property, which returns the value of all members marked as nominative in the definition file, separated, by default, with spaces.
Finally, and most importantly, Persistate generates class members for each member of the persistent class that you specified in your definition file.  These members vary depending on their type and modifiers, but the following list describes the most important.   See Using Generated Properties below for details of how these work and how you use them.
oFor simple value type members, a single property and supporting field is generated.  The property set method performs infrastructure calls to mark the object as modified, and to raise event(s).
oFor single object members, i.e. references to other persistent objects either owned or associated, again a single property and supporting field is generated.
oFor collections of several objects, a collection property and supporting field is generated, as well as a property which returns the number of objects in the collection.
oFor collections of many objects, a collection property and field is generated, as for several collections. Persistate also generates methods to access subsets of the collection.  One method, taking a single parameter, is generated for every distinctive, discriminative or nominative member of the class of objects in the collection.  Finally, Persistate generates a general method for retrieving subsets, which takes a parameter for every such member, and which can use wildcard matching.

Using Generated Properties

A fundamental principle in the design of Persistate is that there should be as little infrastructure visible to the developer as possible.  Consequently, accessing persistent data is performed simply by accessing the properties and methods of the generated classes. Persistate turns C# into a language for programming persistent objects directly.  How does this work?  The following list explains in very general terms.  See Accessing persistent objects and Manipulating persistent objects for more details.

When you read a property value for a single object or collection of several objects, if the object or collection is not already in memory, Persistate will fetch it within the property get method.  It returns the existing or newly fetched object or collection.
When you write a single property, Persistate will mark the object as modified and put into a list of modified objects.  It also remembers any change of object links.  For example, if you overwrite an owned object with a new one, or simply null, this change will be reflected in the database at the next commit.
If you add or remove objects from a collection, using standard collection methods, Persistate remembers this, and updates the database appropriately at the next commit.
Subsets of collections of many objects are brought in explicitly by calling generated methods.  However, you also modify these collections by simply adding and removing objects from the returned subsets, as with several collections.
At the end of the operation execution, or on demand, all modifications are written to the database under control of a transaction.  If more than one database was updated, then this is a distributed transaction.

There are a number of examples of generated code for the Library example you can check out.  The first shows the code for the Library class, generated in the Library.gen.cs file.  The second shows the code for the Borrower class, generated in the Borrower.gen.cs file..  The third shows the   code for the LendStatus struct, generated in the LendStatus.gen.cs file.  The last one shows the generated The class in file The.cs.