Custom Rules

Custom rules become necessary for cases that are too complex to be handled by means of a declarative rule. The process is as follows:

  • Create a class that extends AbstractCustomValidation. Implement one or more of the abstract methods corresponding to various events that may occur with respect to the underlying entity.
  • Within any change handler requiring this rule, instantiate a CustomRule passing in the class created above.

    For details on the events that can be processed by the custom validation, please refer to the JavaDocs.

    When coding a CustomValidation that will be used by a CustomRule, it is important to understand when these events fire.

  • Eager Validations fire immediately, when the underlying entity is changed (either via delete, setDTO(), or createEntity()).
    • validateAdd() fires only on an add.
    • validateChange() fires only when an existing entity is changed.
    • validateAddOrChange fires in addition to either validateAdd() or validateChange().
    • validateDelete fires when the entity is being deleted.
    • validateRegisteredChange() fires when some other object is changed (like a child). This can be any random entity instance that feels like notifying you regarding a change of state or, more commonly, the framework automatically registers a change when a child collection is manipulated. Your custom code can determine if a change has been made to a child it is interested in by calling the getChangeToList() method on the change detail passed in. You just pass in the class of your child collection, and it passes back changes, if any.
  • Lazy Validations fire when a coherent set of changes is complete.
    • validateSave() can be used to implement validations that needs to be performed at the end of some set of changes. By default, a set of changes is both started and saved within individual calls to setDTO, createBusinessEntity, and so on. However, this can be controlled programmatically by calling the startChanges() and saveChanges() methods that are available from within all business objects (change handlers, entities, components, and so on). Any type of change (add, change, deleted, register change) will trigger validateSave().