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:
  - `Constraint`
  - `ConstraintOnTableWithRecordLevelCheck`
  - `JavaBeanVersion.getBeanVersion()`

- ## Method Summary

  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 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:
      - `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.

    See Also:
      - `DependenciesDefinitionContext.addDependencyToInsertAndDelete(SchemaNode)`
      - `DependenciesDefinitionContext.addDependencyToInsertDeleteAndModify(SchemaNode)`

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