com.orchestranetworks.schema
Interface ConstraintOnTable

public interface ConstraintOnTable

Specifies a constraint that is able to perform the validation of a table as a whole. Compared to the Constraint interface that performs the validation per individual record, this allows to optimize the validation algorithm as a set-level operation.

Examples

The following examples present how to define constraints for some complex validation requirements. For each example, we define:

• the node which holds the constraint;
• the kind of dependencies to register, in the setup method;
• the kind of validation messages to be created if errors are detected in the method checkTable.

Case 1:

We want to ensure, inside a table T1, that for any group of records having the same code value, the sum of the values of the portion field is less than a fixed threshold.

Node holding the constraint:

The table node T1.

Dependencies to declare at setup:

This constraint depends on the values of the code and portion nodes, hence dependencies to both nodes must be declared on insert, delete and modify events.

Validation messages:

If this constraint is not satisfied by a group of records, a specific error message can be added to the node holding this constraint and associated with this group, by using an XPath predicate. The XPath predicate defined within the validation message represents the set of records violating the constraint.

Case 2:

We want to ensure, inside a table T2 defining a beginDate and endDate, that for any group of records that have the same code their time periods do not overlap.

Node holding the constraint:

The table node T2.

Dependencies to declare at setup:

This constraint depends on the values of the code, beginDate and endDate nodes, then dependencies to these three nodes must be declared.

Validation messages:

If this constraint is not satisfied by a set of records within a group, a specific error message can be added to the node holding this constraint and associated with this set, by specifying a list of records.

Case 3:

We want to ensure that two tables T3 and T4 contain records with the same primary keys. More precisely, we will consider here that the table T3 is the "master" table; consequently, the table T4 holds an error if it does not define a record existing in T3, or if it defines a record that does not exist in T3.

Node holding the constraint:

The table node T4 (the one holding the validation messages).

Dependencies to declare at setup:

This constraint depends on the records inside T3 and T4; consequently, dependencies to insertion and deletion events in both tables must be declared (see addDependencyToInsertAndDelete).

Validation messages:

A specific error message can be added for each missing or extra record, by specifying an XPath predicate. In this case, the subject of the message will be a ValidationReportItemSubjectForAdaptation.

Schema definition

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

 <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, read JavaBeans specification.

Life cycle

When the schema is loaded:

1. the specified class is instantiated through its default constructor and the JavaBean properties' setters are called (in the example above, setParam1(...) and setParam2(...));
2. the method setup(ConstraintContextOnTable) is called on the new instance.

In operational phase, the method checkTable(ValueContextForValidationOnTable) is called each time the validation report about the table is requested, and the table's validation state is not up-to-date (the up-to-date state depends on the dependencies that have been specified in setup(ConstraintContextOnTable);

See Also:

Constraint

Method Summary

void	checkTable(ValueContextForValidationOnTable aContext) This method must perform a check of the whole table specified by the context, and adds error messages as long as errors are detected.
void	setup(ConstraintContextOnTable aContext) This method is called when the schema is loaded, for checking and preparing this instance.
String	toUserDocumentation(Locale userLocale, ValueContext aContext) Returns a final user documentation about this constraint.

Method Detail

checkTable

public void checkTable(ValueContextForValidationOnTable aContext)

This method must perform a check of the whole table specified by the context, and adds error messages as long as errors are detected.

Performance considerations

As the whole table is checked, this provides the opportunity to implement an adequate "set-level" algorithm, for example by handling the records in a given order. For tables with large volumes of records, this can even be a requirement for getting a reasonable validation time.

Multi-threading

For a single instance of this interface, this method may be called concurrently by several threads.

Throws:

InvalidSchemaException - if some schema's dynamic condition prevents the execution of this method.

setup

public void setup(ConstraintContextOnTable aContext)

This method is called when the schema is loaded, for checking and preparing this instance.

This method must also declare the dependencies of the constraint, if any, so that validation is notified when a value is updated. If no dependencies are declared, they are considered as unknown.

See Also:

ConstraintContext.addDependencyToInsertAndDelete(SchemaNode), ConstraintContext.addDependencyToInsertDeleteAndModify(SchemaNode)

toUserDocumentation

public String toUserDocumentation(Locale userLocale,
                                  ValueContext aContext)
                           throws InvalidSchemaException

Returns a final user documentation about this constraint.

Internationalization strategy

The method can return null if the specified locale is not handled by the current implementation. Indeed, the container is able to try several locales for 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.Platform. In such cases, locales are tried in the following order:

1. user's preferred locale for schema (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 some schema's dynamic condition prevents the execution of this method.