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 and 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 Detail

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.

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)