Interface ConstraintOnTable
-
- All Superinterfaces:
JavaBeanVersion
- All Known Subinterfaces:
ConstraintOnTableWithRecordLevelCheck
public interface ConstraintOnTable extends JavaBeanVersion
Specifies a constraint that is able to perform the validation of an entire table. Compared to theConstraint
interface, which performs the validation of each individual record, this interface allows optimizing the validation algorithm as a set-based operation.Examples
The following examples illustrate how to define constraints for certain complex validation requirements. Each example defines:
- the node that contains the constraint;
- the dependencies to register in the
setup
method; - the validation messages to be created if errors are detected
in the method
checkTable
.
Example 1: Comparing the sum of field values for groups of records against a threshold
This example ensures that, in a table
T1
, no group of records with the samecode
value has a sum of theirportion
values greater than a fixed threshold.- Node containing the constraint:
- Table node
T1
. - Dependencies to declare at setup:
- This constraint depends on the values of the nodes
code
andportion
, thus the insert, delete and modify events must declare dependencies on both these nodes. - Validation messages:
- A custom error message can be added to the node containing this
constraint and be associated with a group of fields. This message would then
be displayed in the event that this constraint is not satisfied by the records of
that group of fields. This error message can be added using a
ValueContextForValidationOnTable.addMessage
method, for example using anXPath predicate
that represents the set of records that have violated the constraint.
Example 2: Verifying non-overlapping time periods for groups of records
This example ensures that, in a table
T2
, no group of records with the samecode
value contains overlapping time periods, as defined by the fieldsbeginDate
andendDate
.- Node containing the constraint:
- Table node
T2
. - Dependencies to declare at setup:
- This constraint depends on the values of the nodes
code
,beginDate
andendDate
, thus the insert, delete and modify events must declare dependencies on all three nodes. - Validation messages:
- If this constraint is not satisfied by a group of records,
a custom error message can be added to the node containing
this constraint and associated with that group. This error message can be added using a
ValueContextForValidationOnTable.addMessage
method, for example using by specifying alist of records
that represents the set of records that have violated the constraint.
Example 3: Verifying that two tables have the same primary keys
This example ensures that two tables,
T3
andT4
, contain records with the same primary keys. Specifically,T3
is considered to be the "master" table, against whichT4
is compared.T4
has an error if it does not define a record that exists inT3
, or if it defines a record that does not exist inT3
.- Node containing the constraint:
- Table node
T4
, which contains the validation messages. - Dependencies to declare at setup:
- This constraint depends on the records within
T3
andT4
. Consequently, dependencies on insertion and deletion events in both tables must be declared inT4
's table node (seeaddDependencyToInsertAndDelete
). - Validation messages:
- A custom error message can be added for each missing or extra record,
using a
ValueContextForValidationOnTable.addMessage
method, for example using by specifying anXPath predicate
. In this case, the subject of the message will be aValidationReportItemSubjectForAdaptation
.
Definition in the data model
The constraint must be declared under the element
xs:annotation/xs:appinfo/osd:otherFacets
, in an element that defines anosd:table
:<osd:constraint class="com.foo.MyTableConstraint" />
com.foo.MyTableConstraint
is the fully qualified name of the class implementing this interface. It is also possible to set additional JavaBean properties:<osd:constraint class="com.foo.MyTableConstraint"> <param1>...</param1> <param2>...</param2> </osd:constraint>
param1
andparam2
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 using its default constructor and the JavaBean property
setters are called (in the example above,
setParam1(...)
andsetParam2(...)
); - the method
setup(ConstraintContextOnTable)
is called on the new instance. - the method
JavaBeanVersion.getBeanVersion()
is called for the new instance for checking if its implementation has been modified since the last time the data model has been compiled. That is, since validation reports are persisted into EBX® repository it is important to update the version to indicate that this constraint has been modified and must be revalidated during the next explicit validation of the container dataset or table.
During the operational phase, the method
checkTable(ValueContextForValidationOnTable)
is called whenever the validation report for the table is requested, but the table's validation state is not up-to-date (the "up-to-date" state depends on the dependencies specified in thesetup
method and on any changes specified by defining a newversion number
.Unlike with other constraints, no check is performed automatically when a record creation or update is submitted in the user interface. If the end-user introduces a validation error, form submission is not be blocked by the
checkTable
method. If blocking behavior is necessary, the sub-interfaceConstraintOnTableWithRecordLevelCheck
must be used instead.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
checkTable(ValueContextForValidationOnTable aContext)
Performs a check on the entirety of the table specified by the context, and adds error messages whenever errors are detected.void
setup(ConstraintContextOnTable aContext)
Checks and prepares this instance when the data model is loaded.String
toUserDocumentation(Locale userLocale, ValueContext aContext)
Returns end-user documentation for this constraint.-
Methods inherited from interface com.orchestranetworks.schema.JavaBeanVersion
getBeanVersion
-
-
-
-
Method Detail
-
checkTable
void checkTable(ValueContextForValidationOnTable aContext)
Performs a check on the entirety of the table specified by the context, and adds error messages whenever errors are detected.Performance considerations
As the whole table is being checked at once, this provides the opportunity to use SQL queries or XPath predicates.
To avoid re-validating this constraint on each request for updating the validation report, it is necessary to declare
dependencies
.See also performance and tuning.
Multi-threading
For a single instance of this interface, this method may be called concurrently by several threads.
- Throws:
InvalidSchemaException
- if a dynamic condition in the data model prevents the execution of this method.- See Also:
ConstraintOnTableWithRecordLevelCheck.checkRecord(ValueContextForValidationOnRecord)
-
setup
void setup(ConstraintContextOnTable aContext)
Checks and prepares this instance when the data model is loaded.Do note that during this step, all models may not be properly compiled. Thus, the repository should not be accessed during this step.
This method must also declare any dependencies of the constraint, so that validation is notified when a value is updated. If no dependencies are declared, the dependencies are considered to be unknown.
-
toUserDocumentation
String toUserDocumentation(Locale userLocale, ValueContext aContext) throws InvalidSchemaException
Returns end-user documentation for this constraint.Internationalization strategy
This method returns
null
if the specified locale is not handled by the current implementation. The container tries several locales when handling a partial internationalization of this method's implementation and/or a mismatch between the locales declared by the associated module and the locales supported by EBX®. In such cases, locales are tried in the following order:- User's preferred locale for the data model
(see
Session.getLocaleForSchemaNode(SchemaNode)
); - Session's current locale;
- Default locale declared in file
module.xml
;
Multi-threading
For a single instance of this interface, this method may be called concurrently by several threads.
- Throws:
InvalidSchemaException
- if a dynamic condition in the data model prevents the execution of this method.
- User's preferred locale for the data model
(see
-
-