Beginning a Notification

Use the Object class beginClassNotification method to register the receiver to be notified when a nominated event occurs on instances of a class and its subclasses. An object that subscribes to a class notification is notified when the nominated event occurs for any instance of the specified class or its subclasses. The signature of the beginClassNotification method is:

beginClassNotification(theClass:     Class;
                       transients:   Boolean;
                       eventType:    Integer;
                       responseType: Integer;
                       eventTag:     Integer);

Use the Object class beginClassesNotification method to register the receiver to be notified when a nominated event occurs on instances of a class and optionally its subclasses, without any additional searches for subschema copies in the current schema. An object that subscribes to a class notification is notified when the nominated event occurs for any instance of the specified class or its subclasses. The signature of the beginClassesNotification method is:

beginClassesNotification(theClass:          Class;
                         includeSubclasses: Boolean;
                         transients:        Boolean;
                         eventType:         Integer;
                         responseType:      Integer;
                         eventTag:          Integer);

Use the Object class beginNotification method to register the receiver to be notified when a nominated event occurs on a specified object. An object that subscribes to an object notification is notified when the specified event occurs for the notification target. The signature of the beginNotification method is:

beginNotification(theObj:       Object;
                  eventType:    Integer;
                  responseType: Integer;
                  eventTag:     Integer);

Use the Object class beginClassNotificationForIF, beginClassesNotificationForIF, and beginNotificationForIF method variations to register a request to be notified of events that occur in a specified interface whose event methods are implemented in a class instance.

The parameters for methods that begin notifications are listed in the following table.

Parameter	Description
eventTag	Identifies a specific notification when you have multiple subscriptions for the same event type.
eventType	Specifies the type of event for which the notification is registered.
responseType	Specifies the frequency with which the event is notified.
theClass	For the beginClassNotification, beginClassesNotification, beginClassNotificationForIF, and beginClassesNotificationForIF methods, specifies the class for which the notification is to be registered.
includeSubclasses	For the beginClassesNotification and beginClassesNotificationForIF methods, specifies whether subclasses are included or excluded in the notification registration
theObj	For the beginNotification and beginNotificationForIF methods, specifies the object for which the notification is to be registered. Note that if this object is transient, only user notifications can be received.
transients	For the beginClassNotification, beginClassesNotification, beginClassNotificationForIF, and beginClassesNotificationForIF methods, specifies if the user notification is to be registered for events that occur to transient instances (true), or persistent instances (false) of the class. You can subscribe to system notifications only for persistent objects; that is, the transient parameter must be false.
theInterface	The interface that defines the appropriate userNotification or sysNotification method implemented by the class instance.

Global constants in the NotificationResponses category, listed in the following table, provide the valid values for the responseType parameter.

Global Constant	Integer Value	Description
Response_Cancel	1	Sends a notification when the target notification object receives a matching event and then cancels the notification
Response_Continuous	0	Sends a notification whenever the target notification object receives a matching event
Response_Suspend	2	Sends a notification when the target notification object receives a matching event and then suspends notification until users refresh their local copy of the target object from the database

Global constants in the SystemEvents category provide the valid values, listed in the following table, for system event types that can be subscribed to in the eventType parameter.

Global Constant	Integer Value	Description
Any_System_Event	0	Object has been created, deleted, or updated
Object_Update_Event	3	Object has been updated
Object_Create_Event	4	Object has been created
Object_Delete_Event	6	Object has been deleted

Event types in the range 16 through Max_Integer, or #7FFFFFFF (2,147,483,647), are user-definable events. User notifications are sent for any event with an event type in this range.

Global constants in the UserEvents category provide the valid values, listed in the following table, for user event types that can be subscribed to in the eventType parameter are.

Global Constant	Integer Value
Any_User_Event	-1 (to subscribe to all user events)
User_Base_Event	16
User_Max_Event	Max_Integer (#7FFFFFFF, equating to 2147483647)

The beginClassesNotification and beginClassesNotificationForIF methods make no attempt to re-interpret the value of the theClass parameter, so that the calls do not look for a subschema copy class in the current schema with which to register the call and they optionally allow only the class without any of its subclasses to be registered for the notification.

For example, a beginClassNotification(MemberKeyDictionary, false, Any_System_Event, Response_Continuous, 1) call looks for a subschema copy class in the current schema to register and a beginClassesNotification(MemberKeyDictionary, false, false, Any_System_Event, Response_Continuous, 1) call registers the root MemberKeyDictionary class in the RootSchema.

If you want to specify your MemberKeyDictionary subschema copy class and allow both the class and its subclasses to be registered for the notification, call beginClassesNotification as follows.

beginClassesNotification(currentSchema.getClass('MemberKeyDictionary'),
                     true, false, Any_System_Event, Response_Continuous, 1);

The following table lists the methods that begin and end matching notification types.

Method that Registers a Request for an Event Notification	Method that Terminates the Notification
beginClassNotification	endClassNotification
beginClassesNotification	endClassesNotification
beginNotification	endNotification
beginClassNotificationForIF	endClassNotificationForIF
beginClassesNotificationForIF	endClassesNotificationForIF
beginNotificationForIF	endNotificationForIF

Alternatively, you can use the endNotificationForSubscriber method to terminate all notifications for a specified subscriber.

For more details, see the appropriate class under "Object Class", in Chapter 1 of the JADE Encyclopaedia of Classes. See also "Example", in the following section.