[This is preliminary documentation and is subject to change.]
C# |
public class Persistent : IReference, ICloneable, IClassified, IEquatable<Persistent>
All Members | Constructors | Methods | Properties | Fields | Events |
Icon | Member | Description |
---|---|---|
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) | (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. |
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!