[This is preliminary documentation and is subject to change.]
Declaration Syntax| C# |
public interface IReference
Members| All Members | Methods | Properties | |||
| Icon | Member | Description |
|---|---|---|
 | Class | Returns the ObjectClass to which the object
referred to by this IReference belongs. |
| Database | Gets the Database object which holds the object
referred to by this IReference |
 | DeReference(Persistent) | Obtains the Persistent object which is the target
of this IReference. |
| IsForeign | Gets a value determining whether this IReference refers to an
object in a foreign Domain. |
| IsPersisted | Determines whether the object which is referred to by this
IReference has been persisted in a Database. |
| IsProvisional | Determines whether the object which is referred to by this
IReference is still provisional - i.e. has not yet been persisted in a
database.. |
| ObjectNumber | Returns a value with the object number of the referred to object.
This is guaranteed to be unique for all objects of the same ObjectClass within one Database. |
| OwningDomain | Gets the Domain to which the object referred to by
this IReference originally belongs. |
| SaveToMessage(Message) | Saves the object implementing this interface to a Message. |
| ToReference()()()() | Obtains a Reference which refers to the object
referred to by this IReference. If this IReference is already a Reference.
then this just returns this Reference. |
RemarksThe core method of this interface is DeReference, which takes the object address held in the implementing type and performs the addressing function, coming up with the addressed object. There is also a ToReference method which translates the IReference to the standard IReference implementation, Reference.
There are various properties which return information about the location or type of the referenced object. See OwningDomain, IsForeign, Database and Class. The properties IsPersisted and ObjectNumber provide information on the state of the referenced object.
The standard Reference implementation of this interface provides the fastest possible de-reference to objects in the local Domain, being almost physical in nature. There is also MetaReference which refers to an object using names to descend through each node in the persistent tree down to it. Whereas Reference can refer to any object, you must implement IMetaReferable in a class in order to refer to instances using MetaReferences. The ForeignReference implementation uses a similar physical addressing style to Reference, but can refer to objects in any Domain.
Finally, Persistent, the base class for all persistent objects, also implements IReference. At first, this might seem counter-intuitive, but there is a good reason for it. In many places in Persistate, especially in object properties, the underlying field for the property is an IReference, whereas the property itself is the type of the member object. This allows Persistate to read in an object from persistent storage, with References for its object members. Persistate then dereferences this reference, replacing it with the object itself, only when you access the property.