com.orchestranetworks.schema

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 the Constraint 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 same code value has a sum of their portion 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 and portion, 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 an XPath 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 same code value contains overlapping time periods, as defined by the fields beginDate and endDate.

Node containing the constraint:

Table node T2.

Dependencies to declare at setup:

This constraint depends on the values of the nodes code, beginDate and endDate, 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 a list 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 and T4, contain records with the same primary keys. Specifically, T3 is considered to be the "master" table, against which T4 is compared. T4 has an error if it does not define a record that exists in T3, or if it defines a record that does not exist in T3.

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 and T4. Consequently, dependencies on insertion and deletion events in both tables must be declared in T4's table node (see addDependencyToInsertAndDelete).

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 an XPath predicate. In this case, the subject of the message will be a ValidationReportItemSubjectForAdaptation.

Definition in the data model

The constraint must be declared under the element xs:annotation/xs:appinfo/osd:otherFacets, in an element that defines an osd:table:

 <osd:constraint class="com.foo.MyTableConstraint" />
 

where 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>
 

where 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:

1. the specified class is instantiated using its default constructor and the JavaBean property setters are called (in the example above, setParam1(...) and setParam2(...));
2. the method setup(ConstraintContextOnTable) is called on the new instance.
3. 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 the setup method and on any changes specified by defining a new version 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-interface ConstraintOnTableWithRecordLevelCheck must be used instead.

See Also:

Constraint, ConstraintOnTableWithRecordLevelCheck, JavaBeanVersion.getBeanVersion()