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

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

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

      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.