@Retention(value=RUNTIME)
@Target(value=METHOD)
@Documented
public @interface OnChange

Annotation for methods that are to be invoked whenever a target field in some target object changes during a transaction, where the target object containing the changed field is found at the end of a path of references starting from the object to be notified. See ReferencePath for more information about reference paths.

Method Parameter Types

In all cases the annotated method must return void and take a single parameter, which is compatible with one or more of the FieldChange sub-types appropriate for the field being watched. The method may have any level of access, including private. The method parameter type can be used to restrict which notifications are delivered. For example, an annotated method taking a SetFieldChange will receive notifications about all changes to a set field, while a method taking a SetFieldAdd will receive notification only when an element is added to the set.

Multiple reference paths may be specified; if so, all of the specified paths are monitored together, and they all must emit FieldChanges compatible with the method's parameter type. Therefore, when mutiple fields are monitored, the method's parameter type may need to be widened (either in raw type, generic type parameters, or both).

As a special case, if zero fields are specified, then "wildcard" monitoring of every field in the local object occurs. However in this case, only fields that emit changes compatible with the method's parameter type will be monitored. So for example, a method taking a SetFieldChange would receive notifications about changes to all Set fields in the class, but not any other fields.

Instance vs. Static Methods

If the method is an instance method, then startType() must be left unset; if the instance is a static method, then startType() may be explicitly set, or if left unset it defaults to the class containing the annotated method.

For an instance method, the method will be invoked on each object for which the changed field is found at the end of the specified reference path starting from that object.

If the annotated method is a static method, the method is invoked once if any instance exists for which the changed field is found at the end of the specified reference path, no matter how many such instances there are. Otherwise the behavior is the same.

Notification Delivery

Notifications are delivered synchronously within the thread the made the change, after the change is made and just prior to returning to the original caller. Additional changes made within an @OnChange handler that themselves result in notifications are also handled prior to returning to the original caller. Therefore, infinite loops are possible if an @OnChange handler method modifies the field it's monitoring (directly, or indirectly via other @OnChange handler methods).

@OnChange functions within a single transaction; it does not notify about changes that may have occurred in a different transaction.

Other Notes

No notifications are delivered for "changes" that do not actually change anything (e.g., setting a simple field to the value already contained in that field, or adding an element to a set which is already contained in the set).

For any given field change and path, only one notification will be delivered per recipient object, even if the changed field is seen through the path in multiple ways (e.g., via reference path "mylist.element.myfield" where the changed object containing myfield appears multiple times in mylist).

See Transaction.addSimpleFieldChangeListener() for further information on other special corner cases.