Class InstanceTrigger
Definition in the data model
The trigger must be declared under the element
xs:annotation/xs:appinfo
:
where<osd:trigger class="com.foo.MyDataSetTrigger" />
com.foo.MyDataSetTrigger
is
the fully qualified name of the class implementing this interface.
It is also possible to set additional JavaBean properties:
where<osd:trigger class="com.foo.MyDataSetTrigger"> <param1>...</param1> <param2>...</param2> </osd:trigger>
param1
and param2
are JavaBean properties of the specified class.
For more information, see the JavaBean specification.
Life cycle
- When the data model is loaded:
- the specified class is instantiated through its default constructor and the JavaBean property
setters are called (in the example above,
setParam1(...)
andsetParam2(...)
); - the method
setup(TriggerSetupContext)
is called on the new instance.
- the specified class is instantiated through its default constructor and the JavaBean property
setters are called (in the example above,
- 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 -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
This method is called after the duplication of a dataset This method is invoked even ifProcedureContext.setTriggerActivation(boolean)
has been set tofalse
.void
handleAfterModify
(AfterModifyInstanceContext aContext) This method is called after the modification of a field outside a table.void
This method is called before the creation of a dataset.void
This method is called before the deletion of a dataset.void
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.
-
Constructor Details
-
InstanceTrigger
public InstanceTrigger()
-
-
Method Details
-
setup
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
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
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
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
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
This method is called before the modification of a field outside a table.This method will not be called if
If no modification to the initial dataset content takes place, this trigger will not be executed.ProcedureContext.setTriggerActivation(boolean)
has been set tofalse
.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
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
If no modification to the initial dataset content takes place, this trigger will not be executed.ProcedureContext.setTriggerActivation(boolean)
has been set tofalse
.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 inhandleBeforeModify
.- Since:
- 6.0.0
- See Also:
-
handleAfterDuplicate
This method is called after the duplication of a dataset This method is invoked even ifProcedureContext.setTriggerActivation(boolean)
has been set tofalse
.Default implementation does nothing.
- Throws:
OperationException
- when an exception occurs.- Since:
- 6.0.0
-