Package com.orchestranetworks.schema.trigger

# Class InstanceTrigger

java.lang.Object
com.orchestranetworks.schema.trigger.InstanceTrigger

public abstract class InstanceTrigger extends Object
Specifies methods that are automatically executed when certain operations are performed on a dataset.

### Definition in the data model

The trigger must be declared under the element `xs:annotation/xs:appinfo`:

>      <osd:trigger class="com.foo.MyDataSetTrigger" />

where `com.foo.MyDataSetTrigger` is the fully qualified name of the class implementing this interface. It is also possible to set additional JavaBean properties:

>      <osd:trigger class="com.foo.MyDataSetTrigger">
>              <param1>...</param1>
>              <param2>...</param2>
>      </osd:trigger>

where `param1` and `param2` are JavaBean properties of the specified class.

For more information, see the JavaBean specification.

### Life cycle

1. When the data model is loaded:
   1. the specified class is instantiated through its default constructor and the JavaBean property setters are called (in the example above, `setParam1(...)` and `setParam2(...)`);
   2. the method `setup(TriggerSetupContext)` is called on the new instance.
2. During the operational phase: the methods `handle...` are called each time the associated operation is executed.

If several operations are defined for the same dataset, they are not executed in any particular order.

### Restrictions

Dataset triggers are not invoked in the following contexts:

- If triggers have been explicitly deactivated using the method `ProcedureContext.setTriggerActivation(false)`.
- In the context of a merge operation (see `ProcedureContext.doMergeToParent(com.onwbp.adaptation.AdaptationHome)`).
- In the context of an archive import (see `ProcedureContext.doImportArchive(ArchiveImportSpec)`).
- In the context of a dataset copy (see `ProcedureContext.doCopy(com.onwbp.adaptation.Adaptation)`).

### Functional guard and exceptions

In the context of a method `handleBefore...`, it is possible to implement a guard by throwing an `OperationException` if some functional conditions on the data are not satisfied. This will cancel the current transaction.

Throwing an `OperationException` instead of a `RuntimeException` provides the end-user with the benefit of a well-localizable and a more user-friendly error message, when the error happens in the context of the user interface. In all cases, the current transaction is aborted.

Note: In further detail, if a `ProcedureContext` raises an exception, any preceding updates made on the repository during nested update executions are first cancelled before the corresponding update method catches the exception. This additional feature is for ensuring that the repository and cache remain consistent, even if the corresponding update method catches the exception.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `InstanceTrigger()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `handleAfterCreate(AfterCreateInstanceContext aContext)`
  This method is called after the creation of a dataset.
  `void`
  `handleAfterDelete(AfterDeleteInstanceContext aContext)`
  This method is called after the deletion of a dataset.
  `void`
  `handleAfterDuplicate(AfterDuplicateInstanceContext aContext)`
  This method is called after the duplication of a dataset This method is invoked even if `ProcedureContext.setTriggerActivation(boolean)` has been set to `false`.
  `void`
  `handleAfterModify(AfterModifyInstanceContext aContext)`
  This method is called after the modification of a field outside a table.
  `void`
  `handleBeforeCreate(BeforeCreateInstanceContext aContext)`
  This method is called before the creation of a dataset.
  `void`
  `handleBeforeDelete(BeforeDeleteInstanceContext aContext)`
  This method is called before the deletion of a dataset.
  `void`
  `handleBeforeModify(BeforeModifyInstanceContext aContext)`
  This method is called before the modification of a field outside a table.
  `abstract void`
  `setup(TriggerSetupContext aContext)`
  Checks and prepares this instance when the data model is loaded.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### InstanceTrigger

    public InstanceTrigger()

- ## Method Details

  - ### setup

    public abstract void setup(TriggerSetupContext aContext)
    Checks and prepares this instance when the data model is loaded.

    Do note that during this step, all models may not be properly loaded. Thus, the repository should not be accessed during this step.

  - ### handleBeforeCreate

    public void handleBeforeCreate(BeforeCreateInstanceContext aContext) throws OperationException
    This method is called before the creation of a dataset.

    Default implementation does nothing.

    Throws:
      `OperationException` - when an exception occurs or to prevent the execution of the subsequent creation (guard role). Warning: in the case of a mass update, the whole transaction is aborted.

  - ### handleAfterCreate

    public void handleAfterCreate(AfterCreateInstanceContext aContext) throws OperationException
    This method is called after the creation of a dataset.

    Default implementation does nothing.

    Throws:
      `OperationException` - when an exception occurs. Warning: in the case of a mass update the whole transaction is aborted.

  - ### handleBeforeDelete

    public void handleBeforeDelete(BeforeDeleteInstanceContext aContext) throws OperationException
    This method is called before the deletion of a dataset.

    Default implementation does nothing.

    Throws:
      `OperationException` - when an exception occurs or to prevent the execution of the subsequent deletion (guard role). Warning: in the case of a mass update the whole transaction is aborted.

  - ### handleAfterDelete

    public void handleAfterDelete(AfterDeleteInstanceContext aContext) throws OperationException
    This method is called after the deletion of a dataset.

    Default implementation does nothing.

    Throws:
      `OperationException` - when an exception occurs. Warning: in the case of a mass update the whole transaction is aborted.

  - ### handleBeforeModify

    public void handleBeforeModify(BeforeModifyInstanceContext aContext) throws OperationException
    This method is called before the modification of a field outside a table.

    This method will not be called if `ProcedureContext.setTriggerActivation(boolean)` has been set to `false`.

    If no modification to the initial dataset content takes place, this trigger will not be executed.

    The default implementation does nothing.

    Throws:
      `OperationException` - to be thrown as a functional guard, or when an unexpected exception occurs. As a consequence, the whole transaction is always aborted.
    Since:
      6.0.0
    See Also:
      - `handleAfterModify(AfterModifyInstanceContext)`

  - ### handleAfterModify

    public void handleAfterModify(AfterModifyInstanceContext aContext) throws OperationException
    This method is called after the modification of a field outside a table. It gives the opportunity to notify a third-party system.

    This method will not be called if `ProcedureContext.setTriggerActivation(boolean)` has been set to `false`.

    If no modification to the initial dataset content takes place, this trigger will not be executed.

    The default implementation does nothing.

    Throws:
      `OperationException` - to be thrown only when an unexpected exception occurs. As a consequence, the whole transaction is always aborted. For a functional guard, it is strongly recommended to implement it in `handleBeforeModify`.
    Since:
      6.0.0
    See Also:
      - `handleBeforeModify(BeforeModifyInstanceContext)`

  - ### handleAfterDuplicate

    public void handleAfterDuplicate(AfterDuplicateInstanceContext aContext) throws OperationException
    This method is called after the duplication of a dataset This method is invoked even if `ProcedureContext.setTriggerActivation(boolean)` has been set to `false`.

    Default implementation does nothing.

    Throws:
      `OperationException` - when an exception occurs.
    Since:
      6.0.0