Skip to main content


abstract class %Library.RegisteredObject extends %Library.Base

For information on this class, see Working with Registered Objects.

The %RegisteredObject class provides the core capabilities needed to manage the in-memory version of an object. Specifically, %RegisteredObject provides the ability to create and destroy object references (OREFs) as well as support for polymorphism. The %RegisteredObject class also provides the ability to swizzle other referenced objects (persistent or serial) into memory.

Classes derived directly from %RegisteredObject can be used as transient objects; objects that exist in memory-and can be used from client applications-but are not stored in the database.

Method Inventory


parameter CAPTION;
Optional name used by the Form Wizard for a class when generating forms.
parameter JAVATYPE;
The Java type to be used when exported.
This parameter controls the default validation behavior for the object.

It can take one of the following values:

0: NoValidate Perform no automatic property validation.
1: ValidateOnSet Perform validation (call the property's ..IsValid method) every time an attribute value is set.
2: ValidateOnSave Perform property validation (in the %ValidateObject() method)) when the object is saved. This is only applicable to persistent objects.

Note: The use of ValidateOnSet is not recommended-it can cause excessive communication between client and server in distributed applications. It is provided for compatability with previous versions.


method %AddToSaveSet(depth As %Integer = 3, refresh As %Integer = 0) as %Status

This method adds the current object to the SaveSet containing objects that are part of the current %Save() for persistent classes or %GetSwizzleObject for serial classes. A queue of objects to be saved or serialized is also constructed. Only modified objects are included in the save queue. The value (OID or serial value in OID form) of each object is also placed in the SaveSet.

This method will invoke the %OnAddToSaveSet method if it is implemented. See that method for more information.

%AddToSaveSet should not ever be invoked directly except from %OnAddToSaveSet().

This method takes these parameters: depth, with these values:

1: Include this object in the SaveSet and, if it has not been serialized put it in the save queue and invoke %AddToSaveSet on any objects referenced by this object to the SaveSet with a depth of 1.
2: Include this object in the SaveSet and save queue. Also invoke %AddToSaveSet on any referenced objects in the SaveSet with a depth of 1.
3: Include this object in the SaveSet and, if modified, the save queue. Also invoke %AddToSaveSet on any referenced objects in the SaveSet with a depth of 3.
refresh, with these values:
0: Add this object to the save set only if it isn't already included.
1: Add this object to the SaveSet even if it already exists. This causes object dependencies to be rebuilt. Typically, this value is only passed by %OnAddToSaveSet when it modifies objects other than the current one.

Note: Swizzled serial objects always have an empty serial value and will always be placed in the save queue and the SaveSet. the value of depth simply gets passed on to its referenced objects.

method %ConstructClone(deep As %Integer = 0, ByRef cloned As %String, location As %String) as %RegisteredObject
Clone the current object to a new object. If deep is 1 then this does a deep copy which will also copy any subobjects and if deep is 0 then it will create another reference to any subobjects and increment the reference count appropriately. It returns the new cloned object.

Note that even if deep=0 when you clone a parent object in a parent child relationship or a one object of a one to many relationship then it will construct clones of all the child/many objects. This is because a child/many object can only point at a single parent and so if we did not create a clone of these then you would have a relationship with zero items in it. If you really just want to clone the object without these child/many objects then pass deep=-1 to this method.

After the clone is constructed it will call %OnConstructClone(object,deep,.cloned) on the clone if it is defined so that you can perform any additional steps e.g. taking out a lock. This works just the same way as %OnNew() does.

The object is the oref of the original object that was cloned. The cloned array is just used internally when doing a deep clone to prevent recursive loops, do not pass anything in at all for this parameter on the initial call. If you write a %OnConstructClone and from here you wish to call %ConstructClone on another object pass in the cloned array, e.g. 'Do oref.%ConstructClone(1,.cloned)' so that it can prevent recursive loops.

The location is used internally to pass the new location for stream objects.

method %IsModified() as %Integer
Returns true (1) if a property of this instance has been modified, otherwise false (0). A TRUE result does not necessarily mean that any property has actually been changed. If %IsModified() returns false then the object has not been modified. There are some situations where we simply cannot efficiently detect a change in value. In these cases we will set the modified status of the property.
method %NormalizeObject() as %Status
Normalizes all of an object's property values by invoking the data type Normalize methods. Many data types may allow many different representations of the same value. Normalization converts a value to its cannonical, or normalized, form.
method %ObjectModified() as %Integer
This method is somewhat similar to %IsModified but it also checks to see if swizzled references would cause the object to become modified should they be serialized. This works on the assumption that a reference to a persistent object will never be modified if the ID has already been assigned. For references to serial objects, a call to %ObjectModified indicates whether or not the serialized value is different. If the reference to a swizzled object is different from the initial object state then the $$$objModAll macro will already return true. Reference the Set code. Returns true (1) if this instance has been modified, otherwise false (0).
method %RemoveFromSaveSet() as %Status

This method removes the current object from the SaveSet. If this object is also in the save queue it is removed from there as well.

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, Validates, Normalizes, and serializes the object (with a save of the persistent image if persistent).
This method is not meant to be called directly. It is called by %Save and by %GetSwizzleObject.
method %ValidateObject(unused As %Integer = 0, checkserial As %Integer = 1) as %Status

This method validates an object.

The %Save() method of a persistent class calls this method before filing any objects in the database. The %ValidateObject() of a referencing object can call it. You can also call it explicitly at any time.

%ValidateObject() does the following:

  1. If present, it will call a user-supplied %OnValidateObject() method.
  2. It checks if any required property values are missing.
  3. If the PROPERTYVALIDATION class parameter is set to ValidateOnSave, it validates each non-null property value by calling the property method IsValid on each literal property and the %ValidateObject method for each object-valued embedded object property (properties whose type extend %SerialObject).
  4. If checkserial is 1, it forces the checking of any embedded object properties by calling their %ValidateObject method after swizzling this property.
  5. If checkserial is 2, it forces the checking of any collections of serial types by iterating over those collections and calling their %ValidateObject() method after swizzling this property, in addition to the validation that occurs when checkserial is 1.

%ValidateObject() returns a %Status indicating success or error. It is up to the caller to process the error value.

%ValidateObject() does not validate object-valued reference properties (properties whose type extends %Persistent) due to the possibility of circular dependencies between objects. The %Save() method of a persistent class automatically detects and handles circular references between objects. If you require the validation of reference properties, you can override this method in a subclass or call %Save() directly.

Inherited Members

Inherited Methods


FeedbackOpens in a new tab