Package com.orchestranetworks.schema

Interface ConstraintOnTable

All Known Subinterfaces:
ConstraintOnTableWithRecordLevelCheck
public interface ConstraintOnTable
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.

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.

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:

  • Method Details

    • 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 implement a "set-based" algorithm, such as handling the records in a specific order. For tables with a large volume of records, using this method may be necessary in order to complete validation in a reasonable amount of time.

      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:

    • setup

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

      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.

      See Also:

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

      1. User's preferred locale for the data model (see Session.getLocaleForSchemaNode(SchemaNode));
      2. Session's current locale;
      3. 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.