com.orchestranetworks.schema
Interface Constraint

All Known Subinterfaces:

ConstraintEnumeration, ConstraintNomenclature

public interface Constraint

Specifies a constraint that may be contextual and dynamic. Regarding XML Schema, it may be considered as a programmatic extended facet.

Schema definition

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

Life cycle

1. 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(ConstraintContext) is called on the new instance.
2. In 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

Method Summary

void	checkOccurrence(Object aValue, ValueContextForValidation aValidationContext) This method checks the specified value and must add an error message if it is not valid.
void	setup(ConstraintContext 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

checkOccurrence

public void checkOccurrence(Object aValue,
                            ValueContextForValidation aValidationContext)
                     throws InvalidSchemaException

This method checks the specified value and must add an error message if it is not valid.

The value passed as an argument by the container is an occurrence. It 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 element.

Performance considerations

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

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

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(ConstraintContext 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.

See Also:

ConstraintContext.addValueDependencyToNode(SchemaNode), ConstraintContext.setDependencyToLocalNode()

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.