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

        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)