org.jsimpledb.annotation

Annotation Type OnChange

@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.

Overview

There several ways to control which changes are delivered to the annotated method:

• By specifying a path of object references, via value(), to the target object and field
• By widening or narrowing the type of the FieldChange method parameter (or omitting it algtogether)
• By declaring an instance method, to monitor changes from the perspective of the associated object, or a static method, to monitor changes from a global perspective
• By allowing or disallowing notifications that occur within snapshot transactions.

A class may have multiple @OnChange methods, each with a specific purpose.

Examples

   @JSimpleClass
   public abstract class Account implements JObject {

       public abstract boolean isEnabled();
       public abstract void setEnabled(boolean enabled);

       @NotNull
       public abstract String getName();
       public abstract void setName(String name);

       public abstract NavigableSet<AccessLevel> getAccessLevels();

       @OnChange      // equivalent to @OnChange("*")
       private void handleAnyChange1() {
           // Sees any change to ANY field of THIS account
       }

       @OnChange("*")
       private void handleAnyChange2(FieldChange<Account> change) {
           // Sees any change to ANY field of THIS account
       }

       @OnChange("*")
       private static void handleAnyChange3(FieldChange<Account> change) {
           // Sees any change to ANY field of ANY account (note static method)
       }

       @OnChange("accessLevels")
       private void handleAccessLevelsChange(SetFieldAdd<Account, AccessLevel> change) {
           // Sees any addition to THIS accounts access levels
       }

       @OnChange
       private void handleSimpleChange(SimpleFieldChange<Account, ?> change) {
           // Sees any change to any SIMPLE field of THIS account (e.g., enabled, name)
       }

       @OnChange(startType = User.class, value = "account")
       private static void handleMembershipChange(SimpleFieldChange<User, Account> change) {
           // Sees any change to which users are associated with ANY account
       }
   }

   @JSimpleClass
   public abstract class User implements JObject {

       @NotNull
       @JField(indexed = true, unique = true)
       public abstract String getUsername();
       public abstract void setUsername(String username);

       @NotNull
       public abstract Account getAccount();
       public abstract void setAccount(Account account);

       public abstract NavigableSet<User> getFriends();

       @OnChange("username")
       private void handleUsernameChange(SimpleFieldChange<User, String> change) {
           // Sees any change to THIS user's username
       }

       @OnChange("account.enabled")
       private void handleUsernameChange(SimpleFieldChange<Account, Boolean> change) {
           // Sees any change to THIS user's account's enabled status
       }

       @OnChange("friends.element.friends.element.account.*")
       private void handleFOFAccountNameChange(SimpleFieldChange<Account, ?> change) {
           // Sees any change to any non-collection field in any friend-of-a-friend's Account
       }
   }
 

Method Parameter Types

In all cases the annotated method must return void and take zero or one parameter; the parameter must be compatible with at least one of the FieldChange sub-types appropriate for the field being watched. 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.

A method with zero parameters is delivered all possible notifications, which is equivalent to having an ignored parameter of type FieldChange<?>.

The method may have any level of access, including private, and multiple independent @OnChange methods are allowed.

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 the last field is "*" (wildcard), then every field in the target object is matched. However, 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. Currently, due to type erasure, only the parameter's raw type is taken into consideration.

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.

See Also:

ReferencePath, org.jsimpledb.change

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	snapshotTransactions Determines whether this annotation should also be enabled for snapshot transaction objects.
Class<?>	startType Specifies the starting type for the ReferencePath specified by value().
String[]	value Specifies the path(s) to the target field(s) to watch for changes.

Element Detail

value

public abstract String[] value

Specifies the path(s) to the target field(s) to watch for changes. See ReferencePath for information on the proper syntax.

Multiple paths may be specified; if so, each path is handled as a separate independent listener registration, and the method's parameter type must be compatible with at least one of the FieldChange sub-types emitted by each field.

If zero paths are specified (the default), every field in the class (including superclasses) that emits FieldChanges compatible with the method parameter will be monitored for changes.

Returns:

reference path leading to the changed field

See Also:

ReferencePath

Default:

{}

startType

public abstract Class<?> startType

Specifies the starting type for the ReferencePath specified by value().

This property must be left unset for instance methods. For static methods, if this property is left unset, then then class containing the annotated method is assumed.

Returns:

Java type at which the reference path starts

See Also:

ReferencePath

Default:

void.class

snapshotTransactions

public abstract boolean snapshotTransactions

Determines whether this annotation should also be enabled for snapshot transaction objects. If unset, notifications will only be delivered to non-snapshot (i.e., normal) database instances.

Returns:

whether enabled for snapshot transactions

See Also:

SnapshotJTransaction

Default:

false