Package com.orchestranetworks.schema

# Interface Constraint<T>

All Superinterfaces:
  `JavaBeanVersion`

All Known Subinterfaces:
  `ConstraintEnumeration<T>`, `ConstraintNomenclature`

public interface Constraint<T> extends JavaBeanVersion
Specifies a constraint that may be contextual and dynamic. In terms of XML Schema, it may be considered as a programmatic extended facet.

### Definition in the data model

The constraint must be declared under the element `xs:annotation/xs:appinfo/osd:otherFacets`:

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

where `com.foo.MyConstraint` 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.MyConstraint">
>              <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

1. When the data model is loaded:
   1. the specified class is instantiated through its default constructor, and the setters of the JavaBean properties are called (in the example above, `setParam1(...)` and `setParam2(...)`);
   2. the method `setup(ConstraintContext)` is called for 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 then must be revalidated during the next explicit validation of the container dataset or table.
2. During the operational phase: the method `checkOccurrence(Object, ValueContextForValidation)` is called each time an associated element or attribute has to be validated.

### Performance considerations

See `checkOccurrence(Object, ValueContextForValidation)`.

See Also:
  - `ConstraintOnNull`
  - `ConstraintOnTable`
  - `JavaBeanVersion.getBeanVersion()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `checkOccurrence(T aValue, ValueContextForValidation aValidationContext)`
  Checks the specified value, and adds an error message if invalid.
  `void`
  `setup(ConstraintContext aContext)`
  Checks and prepares this instance if called while the data model is being loaded.
  `String`
  `toUserDocumentation(Locale userLocale, ValueContext aContext)`
  Returns the end-user documentation for this constraint.

  ### Methods inherited from interface com.orchestranetworks.schema.JavaBeanVersion

  `getBeanVersion`

- ## Method Details

  - ### checkOccurrence

    void checkOccurrence(T aValue, ValueContextForValidation aValidationContext) throws InvalidSchemaException
    Checks the specified value, and adds an error message if invalid.

    The value passed as an argument by the container is a type occurrence. This means that if the associated node is a simple type with an aggregated list declaration (that is, `maxOccurs > 1`), this method is called for each occurrence of the list. This value is never `null`. If under certain circumstances, a check on a `null` value is necessary, then the interface `ConstraintOnNull` should be used.

    ##### Performance considerations

    If this constraint is attached to a table with N records, a full validation will call this method N times.

    To avoid re-validating this constraint on each request for updating the validation report, it is recommended to declare `dependencies`.

    For a table with many records, it may be necessary to optimize the implementation. A good solution may be to implement the interface `ConstraintOnTable` instead of this interface.

    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.

  - ### setup

    void setup(ConstraintContext aContext)
    Checks and prepares this instance if called while the data model is being loaded.

    Do note that during this step, all models may not be properly loaded. 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.

    See Also:
      - `ConstraintContext.setDependencyToLocalNode()`

  - ### toUserDocumentation

    String toUserDocumentation(Locale userLocale, ValueContext aContext) throws InvalidSchemaException
    Returns the 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 data model's dynamic condition prevents the execution of this method.
    See Also:
      - `SchemaFacet.getDocumentation(Locale, ValueContext)`