Persistate API documentation
Persistent Class
NamespacesPersistatePersistent

[This is preliminary documentation and is subject to change.]

This is the base class for all persistent objects.
Declaration Syntax
C#
public class Persistent : IReference, ICloneable, 
	IClassified, IEquatable<Persistent>
Members
All MembersConstructorsMethodsPropertiesFieldsEvents



IconMemberDescription
Persistent(Reference, IReference)
This constructor is intended for use only from generated code, and you should not use it in open code.

Persistent(Boolean, Boolean)
When overridden, provides a means to create a derived object with optional initialisation of scalar members and collection members.

Adopt(Persistent, IReference%, Int32)
This method is intended for use only from generated code, and you should not use it in open code.

Adopted
Occurs when this object is adopted as a contained (not associated) child object of another object.

AnnotationSeparator
This string is used to separate the text in NominativeText and DiscriminativeText properties

Associate(Persistent, IReference%, Int32)
This method is intended for use only from generated code, and you should not use it in open code.

Associated
Occurs when this object is taken as an associated child object of another object.

AssociatorCount()()()()
Gets the number of associations made to this object.

BaseClassReference(Persistent, Reference)
Here only to allow consistent use of new keyword in generated classes. Always throws an exception.

CallTree(CallTreeData, Int32)
In derived classes, calls a particular delegate for every node in a persistent tree.

CallTree(CallTreeData)
Starts a recursive descent of the persistent containment tree from this object, calling a delegate for every node in the tree below this object.

Class
Returns the ObjectClass for this object.

ClassFlags
Obtains the FlagSet containing flags concerning the ObjectClass of this persistent.

Clone()()()()
Creates a copy of this object.

Collection()()()()
Creates a Persistent collection to contain provisional objects

Collection(Persistent, FlagSet, Int32, Boolean)
Creates a Persistent collection to contain persistent objects

ContainingEnvironment
Gets the Environment that this object is contained within.

CopyFrom(Persistent)
Copies values of fields from another Persistent of the same type.

CopyTransientFrom(Persistent)
Allows derived classes to copy transient data when CopyFrom is called.

CreateFromDatabase(Database, IDataReader, Reference, Persistent)
This is a dummy method allowing consistent use of the new keyword in generated classes. Do not use - it always throws an exception.

CreateFromMessage(Message, Reference, IReference)
This is a dummy method allowing consistent use of the new keyword in generated classes. Do not use - it always throws an exception.

Database
Gets the Database object for the database in which this object is or is to be stored.

DeAssociate(Persistent, IReference, Int32)
This method is intended for use only from generated code, and you should not use it in open code.

DeAssociateFrom(Persistent, Int32)
This method is intended for use only from generated code, and you should not use it in open code.

DebugDisplay(IReference)
Provides a debugger display for scalar objects, with no side effects.

DebugDisplay(IPersistateList)
Provides a debugger display for collections, with no side effects.

Deleted
This event occurs when an object is deleted.

DeleteVolatile(IReference)
This method is intended for use only from generated code, and you should not use it in open code.

DePersist(Object)
This method is intended for use only from generated code, and you should not use it in open code.

DePersistFrom(IPersistateList, Object)
This method is intended for use only from generated code, and you should not use it in open code.

DeReference(Persistent)
Returns this object.

DiscriminativeText
Returns a string showing the ToString value of the object.

Disowned
Occurs when this object is disowned from being a contained (not associated) child object of another object.

Dissociated
Occurs when this object is removed from being an associated child object of another object.

Equals(Persistent)
Determines if this Persistent is equal to another.

Equals(Object)
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
FillFromDatabase(Database, IDataReader)
This method is intended for use only from generated code, and you should not use it in open code.

FillFromMessage(Message)
This method is intended for use only from generated code, and you should not use it in open code.

Finalize()()()()
Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection.
(Inherited from Object.)
GetAssociators()()()()
Gets a collection of all objects which have associations to this object.

GetAssociators<(Of <<'(T>)>>)()()()()
Gets a collection of all objects of a particular type which have associations to this object.

GetChildren<(Of <<'(T>)>>)(IndexedList<(Of <<'(T>)>>), ObjectClass, FlagSet, Int32, String, array<Object>[]()[][])
This method is intended for use only from generated code, and you should not use it in open code.

GetChildren<(Of <<'(T>)>>)(IndexedList<(Of <<'(T>)>>), ObjectClass, String, array<Object>[]()[][])
This method is intended for use only from generated code, and you should not use it in open code.

GetDefaultLayout()()()()
Finds the default layout for this object. This will always be of layout type Form.

GetFieldValue(Int32)
In derived generated classes, gets the value of the field of this object with a particular slot number.

GetHashCode()()()()
Serves as a hash function for a particular type.
(Inherited from Object.)
GetKey(Int32)
Gets the value of the distinctive property with a particular key number.

GetMemberValue(Int32)
In derived generated classes, gets the value of the member of this object with a particular slot number.

GetSelected<(Of <<'(T>)>>)(IndexedList<(Of <<'(T>)>>), ObjectClass, array<Object>[]()[][])
This method is intended for use only from generated code, and you should not use it in open code.

GetType()()()()
Gets the Type of the current instance.
(Inherited from Object.)
InitialiseMembers(Boolean, Boolean)
In derived classes, initialises members of the Persistent object.

IsAttached
Determines whether this object is attached to the persistent tree.

IsDistributedFrom(Persistent)
Determines whether this object is held or is to be held in a different Database than another object.

IsEmpty
Determines whether this is the Empty object of its class, as returned by the EmptyObject property.

IsEmptyOrNull(Persistent)
Determines whether a object is either null or an empty object.

IsForeign
Gets a value determining whether this object is originally from a Domain other than the local Domain.

IsInvalid
Gets a value indicating the validity of the current state of this object.

IsModified
Gets a value indicating whether this object has been modified

IsPersisted
Gets a value indicating whether the object has been persisted in a Database.

IsProvisional
Gets a value indicating whether this object is still provisional - has not been persisted in a Database.

ItsObjectClass
This method returns the ObjectClass object for the Persistent .Net class.

locker
This object is used to synchronise fetches of contained objects and collections in generated code.

MemberwiseClone()()()()
Creates a shallow copy of the current Object.
(Inherited from Object.)
Modified
Occurs when an object is modified.

Move(String, Persistent, String)
Moves this object from its current parent object to a new one.

Move(String, Persistent, String, Int32)
Moves this object from its current parent object to a new one, optionally inserting it at a particular position in a collection.

NominativeText
Returns a string showing the nominative text of the object.

ObjectNumber
This returns the object number part of the object's Reference.

OnModified()()()()
Raises events signalling that the current object has been modified.

OwningDomain
Gets the Domain to which this object originally belongs.

Parent
This returns the parent object of this one.

ParentReference
Gets a Reference to this object's parent object.

PreviousVersion
Returns the previous version of this object.

Refresh()()()()
Gets the current value of this object from persistent storage.

RefreshAndLock()()()()
Gets the current value of this object from persistent storage and sets a database lock.

RefreshTree()()()()
Refreshes the entire persistent containment tree under this object.

RestoreUnmodified(Boolean)
Restores the values of an object's members to those of the previous version.

SaveToDatabase(Database, Reference, Object)
This method is intended for use only from generated code, and you should not use it in open code.

SaveToMessage(Message)
Saves this Persistent object to a Message.

SaveToMessage(Message, Boolean)
Saves this Persistent object to a Message.

SetFieldValue(Int32, Object)
In derived generated classes, sets the value of the field of this object with a particular slot number.

SetMemberFromMessage(Int32, Int32, Message)
This method is intended for use only from generated code, and you should not use it in open code.

SetMemberValue(Int32, Object)
In derived generated classes, sets the value of the member of this object with a particular slot number.

SetModified()()()()
Signals to Persistate that an object has been modified.

SetModifiedSynced()()()()
Signals to Persistate that an object has been modified. The call is protected by a lock on this object.

SetObjectClass(ObjectClass)
This method is intended for use only by the Persistate infrastructure, and you should not use it in open code. Sets the objClass field.

StoreInDatabase(Database)
Marks this object so that it will be stored in a particular Database.

ThisObj
This property is used in binding combo box selected values. It returns the current object.

TitleText
Gets a title for this object.

ToMetaReference()()()()
Creates a MetaReference referring to this object, if possible.

ToMetaReference(Boolean)
Creates an environment relative MetaReference referring to this object, if possible.

ToReference()()()()
Obtains a Reference to this Object.

ToString()()()()
Obtains a string describing the object.
(Overrides Object.ToString()()()().)
Traverse(String)
Traverses the persistent object graph from this object using a period delimited navigation path.

TraverseFrom(Persistent, String)
Traverses the object graph from a particular object using a period delimited navigation path.

Validate()()()()
Allows inheritors to create a validation method for Persistent classes.

ValueOf<(Of <<'(T>)>>)(Object)
Returns the value of an object as a particular type.

VersionNumber
Gets the version number of this object.

WriteTestAssociations(IClassified, Int32, CreateTestDataParameterSet)
Creates test association(s) for an associated member of this object.

WriteTestData(Persistent, Int32, CreateTestDataParameterSet)
Fills this object with test data.

Remarks

When you write a Persistate definition file, you create amongst other items, a number of classes which Persistate models as ObjectClass objects. when Persistate generates the source code for these classes, it creates .Net classes for you which are derived from this Persistent class. Each generated .Net class corresponds to one ObjectClass object. You can access the ObjectClass from a generated class using the Class instance property, or the ItsObjectClass static property. From an ObjectClass object, you can access the Type for the generated .Net class with the TargetType property.

The Persistent class contains six instance fields, three of which are written to persistent storage along with the object properties, and three which are not. The three persisted fields are as follows.

  • The thisObject field is an IReference which refers to the current object. Although Persistent itself implements IReference, this is never a Persistent, but can be a Reference or a ForeignReference. In the latter case, this will be the local copy of an object originally from a foreign Domain. The ToReference()()()() method gets this if it is a Reference - if it is a ForeignReference, it gets a Reference to the local copy of the object.
  • The parent field contains an IReference to the parent object of this one. This works similarly to the backing fields of generated object properties. This may contain a Reference or ForeignReference to the parent object, but when you access it using the Parent property, if it is still a Reference it will be dereferenced (which may mean accessing persistent storage) and replaced with the actual parent object. This is why Persistent implements IReference.
  • The versionNumber integer contains the current version number of this object. This is incremented each time the object is modified, and is available through the VersionNumber property. Version numbers are used in detecting update conflicts when objects are saved in persistent storage.

The three fields which are not written to persistent storage are as follows.

  • The flagsFlagSet stores important state indicators for the object. The flags that are useful in this context are Modified, which is set by SetModified()()()() and tested with IsModified, Attached which is set when you attach a new object to a parent object and is tested with IsAttached. Invalid, which is set when the object's state requires a Refresh()()()() or manual setting, and is tested with IsInvalid.
  • The previousVersion field is a Persistent which will contain a Clone()()()() of this object made by SetModified()()()() when an object is first modified by setting a persistent property or other means. The copy is made only if this object's ObjectClass is in a ClassCategory which has the Clone on Mutate function. You can access this with the PreviousVersion property.
  • The events field is not directly accessible. It stores an object which contains all event subscriptions for the object. The events available for a persistent object are Modified, Deleted, Adopted, Disowned, Associated and Dissociated.

There are a number of methods in Persistent which are designed to be overridden in and/or called from generated code only, such as CreateFromDatabase or SaveToDatabase. These are documented here for completeness, but you should never call these. This fact is noted in the documentation. These generated methods allow Persistate to avoid the use of reflection in many areas, making such methods relatively efficient.

Persistent has a number of properties which get you information concerning the object. Database returns the Database object representing the database in which the object is stored, ObjectNumber returns a value guaranteed to be unique for this class in one database, OwningDomain returns the domain that the object was created in, IsPersisted determines if the object has been persisted in a Database, IsForeign determines if the OwningDomain is the local Domain, ParentReference gets a Reference to its parent object.

Normally you navigate the persistent tree simply by accessing object property members and objects in collections, using the standard dot notation for property access, or indexers or the generated indexing methods for accessing objects in collections. The Persistent class also has methods which allows you to access the persistent tree in other ways. The Traverse(String) and TraverseFrom(Persistent, String) methods allow you to traverse the tree from an object using late bound property names. The CallTree method allows you to walk the tree under a particular object, calling a delegate for each node.

Persistent provides a default means of creating test data for your application. This is done in collaboration with the standard CreateTestData Operation. The WriteTestData and WriteTestAssociations methods will create a full persistent tree under an object, with data properties given pseudo-random values, and object members and collections filled with new objects. You can override these methods to provide a more tailored set of test objects.

The above is by no means an exhaustive summary of the Persistent class - it's the biggest class in the Persistate application, and warrants a browse through the members to see what's available. However, do remember that programming Persistate's persistent objects is done mainly using the code generated for you from your definition file. You actually need very little of this API to use it!

Inheritance Hierarchy

Assembly: Persistate (Module: Persistate) Version: 0.6.1.20 (0.6.1.20)