%Library.RelationshipObject
Class %Library.RelationshipObject Extends (%SerialObject, %Collection.AbstractIterator) [ Inheritance = right, StorageStrategy = Custom, System = 2 ]
For information on this class, see Defining and Using Relationships.
Registered relationship class for relationship cardinalities many and children. Instances of this class are used by n-cardinality relationships to manage objects currently related to the container object and also to manage the objects whose relationship with the container object has been removed. Related objects are loaded into this object using a query-like interface that is implemented by the inverse relationship. The order in which related objects are loaded is neither guaranteed or maintained as objects are related or unrelated. This class is used internally by InterSystems IRIS. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this class.
Parameters
CARDINALITY;
Parameter CARDINALITY;
CLASSNAMEINOID
Parameter CLASSNAMEINOID = 0;
This parameter determines how the collection object stores OID values. If this parameter is set to 0, then partially-formed OID values (containing only an ID number) are used. If this parameter is set to 1, then fully-formed OID values (containing both a class name and an ID number) are used.
ELEMENTTYPE
Parameter ELEMENTTYPE = "%ObjectHandle";
The type (class name) of the elements stored in the collection.
INVERSEPROPERTY;
Parameter INVERSEPROPERTY;
PERSISTENT
Parameter PERSISTENT = 0;
INVERSEPERSISTENT
Parameter INVERSEPERSISTENT = 0;
Properties
InverseReference
Property InverseReference As %RawString;
Oref
Property Oref As %RawString [ MultiDimensional, Private ];
Oref is a private property used to hold the related object references in the form i%Oref(key)=oref.
RelationshipData
Property RelationshipData [ MultiDimensional, Private ];
Private property used to hold some relationship data
ElementType
Property ElementType As %RawString [ InitialExpression = {..#ELEMENTTYPE} ];
The type (class name) of the elements stored in the collection.
Disconnected
Property Disconnected As %RawString [ MultiDimensional, Private ];
Private storage area used to hold OREF values for objects no longer related to the container object.
Cardinality
Property Cardinality As %RawString [ InitialExpression = {..#CARDINALITY} ];
The property name of the inverse relationship in the related class.
InversePersistent
Property InversePersistent As %RawString [ InitialExpression = {..#PERSISTENT} ];
TRUE if the ElementType class is a persistent class.
InverseProperty
Property InverseProperty As %RawString [ InitialExpression = {..#INVERSEPROPERTY} ];
The property name of the inverse relationship in the related class.
NotLoaded
Property NotLoaded As %Boolean [ InitialExpression = 1, Transient ];
TRUE if related objects have not been retrieved by calling Load().
Persistent
Property Persistent As %RawString [ InitialExpression = {..#PERSISTENT} ];
TRUE if the container class is a persistent class.
Methods
%OnNew
Method %OnNew(initvalue As %String = "") As %Status [ Private ]
%New callback - initializes ElementType, Cardinality, InverseProperty and InverseReference from initvalue parameter.
%OnClose
Method %OnClose() As %Status [ Private ]
%SetSerial
Method %SetSerial(initvalue As %String) As %Status [ Private ]
%GetSerial
Method %GetSerial(force As %Integer = 0) As %String [ CodeMode = expression, Private ]
%AddToSaveSet
Method %AddToSaveSet(force As %Integer = 0, refresh As %Integer = 0) As %Status
Overrides %SerialObject implementation. Scans objects for modifications in the related list (Element) and the terminated relationship list (DeleteOref). Modified/Scheduled to delete objects are added to the save graph.
%RollBack
Method %RollBack() As %Status [ ProcedureBlock = 1, ServerOnly = 1 ]
This method is called by %TRollBack^%occTransaction when a transaction is rolled back.
Returns a %Status value indicating success or failure.
%SerializeObject
Method %SerializeObject(ByRef serial As %Binary, partial As %Integer = 0) As %Status
This method retrieves all of the serial values for referenced objects and places them into the instance variables and then validates, normalizes, and serializes the object (with a save of the persistent image if persistent).
%OnConstructClone
Method %OnConstructClone(oref As %RegisteredObject, deep As %Boolean = 0, ByRef cloned As %String) As %Status [ Private ]
Clear
Method Clear() As %Status
Clears the contents of the array. Both the OID and OREF values are cleared.
Returns a %Status value indicating success or failure.
Count
Method Count() As %Integer
Returns the number of elements contained in the Relationship.
FindObject
Method FindObject(oid As %ObjectIdentity, key As %String) As %String [ CodeMode = expression, Final ]
Starting from, but not including, position key, FindObject finds the next element in the list whose ID value equals the id from oid ($$$oidPrimary is the id). If key is a null string, FindObject starts at the beginning of the list.
FindObject returns the position of the found element or null string ("") if no element was found.
FindObjectId
Method FindObjectId(id As %String, key As %String = "") As %String
Starting from, but not including, position key, FindObjectId finds the next element in the list whose ID value equals id. If key is a null string, FindObjectId starts at the beginning of the list.
FindObjectId returns the position of the found element or null string ("") if no element was found.
FindOref
Method FindOref(oref As %ObjectHandle, key As %String = "", id As %String) As %String
Starting from, but not including, location key, finds the next element in the array whose Oref value equals oref.
If key is a null string (""), the search starts at the beginning of the array.
FindOref returns the key associated with the found element or null string ("") if no element is found. Unswizzled references are compared to oref.%Oid() and if equal, swizzling will occur.
GetAt
Method GetAt(key As %String) As %ObjectHandle
Finds and returns the OREF value referring to the object at position key in the list.
GetAt returns the value of the element at location key or null string ("") if no element is found.
GetNext
Method GetNext(ByRef key As %String) As %ObjectHandle
Finds and returns the OREF value referring to the object at the position after key in the list. If key is a null string (""), it returns the OREF value of the first element in the list.
The value of key, which is passed by reference, is updated to the position value of the returned element or null string ("") if key is at the end of the list.
GetObjectAt
Method GetObjectAt(key As %String = "", force As %Integer = 0) As %ObjectIdentity
Finds and returns the OID value referring to the object at position key in the list.
Returns the value of the element at location key or the null OID if no element is found.
GetObjectIdAt
Method GetObjectIdAt(key As %String = "", force As %Integer = 0) As %String [ CodeMode = expression ]
Finds and returns the ID value of the element associated with key.
GetObjectIdAt returns the ID value of the element associated with key or null string ("") if no element is found.
GetObjectNext
Method GetObjectNext(ByRef key As %String = "") As %ObjectIdentity
Finds and returns the OID value referring to the object at the position after key in the list. If key is a null string (""), it returns the OID value of the first element in the list.
The value of key, which is passed by reference, is updated to the position value of the returned element or the null OID if key is at the end of the list.
GetObjectIdNext
Method GetObjectIdNext(ByRef key As %String) As %String [ CodeMode = expression ]
Finds and returns the ID value of the element at the location after key in the array. If key is a null string (""), it returns the ID value of the first element in the array.
The value of key, which is passed by reference, is updated to the key value of the returned element or null string ("") if key is at the end of the array.
GetObjectPrevious
Method GetObjectPrevious(ByRef key As %String) As %ObjectIdentity
Finds and returns the OID value referring to the object at the position before key in the list. If key is a null string (""), it returns the OID value of the last element in the list.
The value of key, which is passed by reference, is updated to the position value of the returned element or the null OID if key is at the beginning of the list.
GetObjectIdPrevious
Method GetObjectIdPrevious(ByRef key As %String) As %String [ CodeMode = expression ]
Finds and returns the ID value of the element at the location before key in the array. If key is a null string (""), it returns the ID value of the last element in the array.
The value of key, which is passed by reference, is updated to the key value of the returned element or null string ("") if key is at the beginning of the array.
GetOrefAt
Method GetOrefAt(key As %String, force As %Integer = 0) As %ObjectHandle [ CodeMode = expression, Final ]
This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
Finds and returns the OREF at position key in the list without automatically swizzling the object. Returns $$$NULLOREF if no element is found or if the referenced object hasn't been swizzled.
GetPrevious
Method GetPrevious(ByRef key As %String) As %ObjectHandle
Finds and returns the OREF value referring to the object at the position before key in the list. If key is a null string (""), it returns the OREF value of the last element in the list.
The value of key, which is passed by reference, is updated to the position value of the returned element or the null OREF if key is at the beginning of the list.
IsDefined
Method IsDefined(key As %String) As %Boolean [ Final ]
Returns true (1) if a value is defined at location key, otherwise false (0).
Load
Method Load() As %Status
Retrieves a list of all objects related to InverseReference and inserts them into array of related objects.
IsEmpty
Method IsEmpty() As %Boolean
Returns true if this collection is empty. To get better performance, if the contents of the collection are not already loaded, then this will run a minimal query to determine if the collection is empty, and will not actually load the contents.
Next
Method Next(key As %String = "") As %String [ Final ]
Finds and returns the key value of the element at the location following key in the array. If key is a null string (""), then Next returns the key value for the first element in the array.
Previous
Method Previous(key As %String = "") As %String [ Final ]
Finds and returns the key value of the element at the location preceding key in the array. If key is a null string (""), then Previous returns the key value for the last element in the array.
Insert
Method Insert(oref As %ObjectHandle) As %Status
Inserts an element with OREF value oref at the end of the array.
Returns a %Status value indicating success or failure.
InsertObject
Method InsertObject(oid As %ObjectIdentity) As %Status
Inserts an element with OID value oid at the end of the array.
Returns a %Status value indicating success or failure.
InsertObjectId
Method InsertObjectId(id As %String) As %Status [ CodeMode = expression, Final ]
Inserts an element with ID value id at the end of the array.
Returns a %Status value indicating success or failure.
RemoveAt
Method RemoveAt(key As %String) As %ObjectIdentity
Removes the element at position key in the array.
RemoveAt returns the OID value of the removed element or the null OID if no element was removed.
Remove
Method Remove(oref As %ObjectHandle) As %ObjectIdentity
Removes the element whose oref is oref.
Remove returns the OID value of the removed element or the null OID if no element was removed.
RemoveObject
Method RemoveObject(oid As %ObjectIdentity) As %ObjectIdentity
Removes the element whose OID is oid.
RemoveAt returns the OID value of the removed element or then null OID if no element was removed.
SetAt
Method SetAt(oref As %ObjectHandle, key As %String) As %Status [ Internal ]
Method for INTERNAL USE ONLY, not for public use.
Sets the OREF value of the element associated with key to oref.
Returns a %Status value indicating success or failure.
SetObjectAt
Method SetObjectAt(oid As %ObjectIdentity, key As %String) As %Status [ Internal ]
Method forINTERNAL USE ONLY, not for public use.
Sets the OID value of the element associated with key to oid.
Returns a %Status value indicating success or failure.
%UnSwizzleAt
Method %UnSwizzleAt(key As %String, force As %Integer = 0) As %Status
Unswizzles (removes from memory) the individual element at position key in the list.
Returns a %Status value indicating success or failure.
Relate
Method Relate(oref As %ObjectHandle) As %Status
Inserts an element with OREF value oref at the end of the list.
Returns a %Status value indicating success or failure. This method should not be invoked directly. It is invoked by the inverse relationship.
UnRelate
Method UnRelate(oref As %ObjectHandle) As %Status
Moves an element with OREF value oref from the array of related objects to the list of terminated relationships.
Returns a %Status value indicating success or failure. This method should not be invoked directly. It is invoked by the inverse relationship.
FindExistingObjectId
Method FindExistingObjectId(id As %String, key As %String = "") As %String [ Private ]
Like FindObjectId but is private, and will not trigger a Load()
FindExistingOref
Method FindExistingOref(oref As %ObjectHandle) As %String [ Private ]
Like FindOref but doesn't support key starting point, is private, and will not trigger a Load()
GetExistingObjectAt
Method GetExistingObjectAt(key As %String, force As %Integer = 0) As %ObjectIdentity
Finds and returns the OID value referring to the object at position key in the list.
Returns the value of the element at location key or the null OID if no element is found.
GetExistingObjectNext
Method GetExistingObjectNext(ByRef key As %String) As %ObjectIdentity
Finds and returns the OID value referring to the object at the position after key in the list. If key is a null string (""), it returns the OID value of the first element in the list.
The value of key, which is passed by reference, is updated to the position value of the returned element or the null OID if key is at the end of the list.