Home > Models

Constraints, Triggers and Functions

Facets allow you to define constraints on your Master Data in your schemas. EBX.Platform supports XML Schema facets and provides extended and programmatic facets for advanced data controls.

• XML Schema Supported facets
  • Uniqueness constraint
• Extended Facets
  • Foreign keys
  • Dynamic constraints
  • FacetOResource Constraint
  • excludeValue constraint
  • excludeSegment constraint
  • Enumeration facet filled by another node
• Programmatic Facets
  • Programmatic constraints
  • Programmatic enumeration constraints
  • Programmatic nomenclature constraints
  • Constraint on null value
  • Constraints on table
• Triggers and Functions
  • Computed values
  • Triggers
  • Auto incremented values
• User Input Control
  • Check null input
  • EBX.Platform whitespaces management for Data Types

XML Schema Supported facets

Notes:

• (1) The whiteSpace facet can be defined, but is not interpreted by EBX.Platform

• (2) In XML Schema, boundary facets are not allowed on the type String. Nevertheless, EBX.Platform allows those facets as extensions.

• (3) The resource type supports only one facet (required): FacetOResource (see EBX.Platform Extended Facets).

Example:

Uniqueness constraint

It is possible to define a uniqueness constraint, by using the standard XML Schema element xs:unique . This constraint indicates that a value has to be unique inside a table.

In the example below, a uniqueness constraint is defined on the publisher table, for the target field name (this means that two occurrences of the publisher table cannot have the same name):

A uniqueness constraint has to be defined inside a table and has the following properties:

Limitations:

1. The target of the xs:field element has to be in a table.

2. Uniqueness constraint cannot apply if the field is inside an aggregated list.

3. The definition of multiple xs:field elements is not supported.

Extended Facets

EBX.Platform provides additional constraints that are not specified in XML Schema, but that are useful for Master Data Management.

In order to guarantee conformance to XML Schema, those Extended Facets are defined under the element annotation/appinfo/otherFacets .

Foreign keys

A reference to a table is defined using the extended facet tableRef . The element must be of type xs:string.

The example below specifies a reference (foreign key) to an occurrence of catalog element.

Note: Multiple variants can be specified to the label of the tableRef. The priority of the tags is the following:

1. display tag with a programmatic label.

2. display tag with a localized expression.

3. display tag with a default expression.

At runtime, the extended facet tableRef is interpreted as an enumeration whose values are formatted foreign keys. Labels may be added to key value by using labelPaths element: each label is specified by the absolute path in the content of an occurrence.

See also:

• Extraction of foreign keys (XPath predicate syntax)

Dynamic constraints

Those facets retain the XML Schema semantics, but the value attribute is replaced by a path attribute that allows to get the value from another Master Data in the adaptation:

• length

• minLength

• maxLength

• maxInclusive

• maxExclusive

• minInclusive

• minExclusive

By means of these facets, the data model may be modified dynamically, in the adaptations.

Example:

In this example, the boundary of the facet minInclusive is not statically defined. The value of the boundary comes from the node /domain/Loan/Pricing/AmountMini/amount

FacetOResource Constraint

This facet must be defined for each resource type. It has the following attributes:

• moduleName : indicates with an alias which EBX.Platform module contains the resource. If it is the module itself that contains the resource, the alias must be preceded by "wbp". Otherwise, the alias must be one of the values defined in the element <dependencies> of the file‘module.xml’; 

• resourceType : represents the resource type that is one of the following values: "ext-images", "ext-jscripts", "ext-stylesheets", "ext-html";

• relativePath : represents the local directory where the resource is located, just under the resourceType directory. In the example below, it is the directory www/common/images/ . Hence, for this example, the resource is located at www/common/images/promotion/ where the www/ directory is at the same level as the WEB-INF/ directory.

  Furthermore, if a resource is defined in a localized directory ( www/en/ for instance), it will be considered only if another resource of the same name is defined in the directory www/common/ . 

This facet has the same behavior as an enumeration facet: the values are collected by recursively listing all the files in ‘local path’ from the specified directory ‘resource type’ in the specified ‘module’ .

Example:

An overview of directories structures in an EBX.Platform module (J2EE Web application) is detailed in the section Modules - Structure .

excludeValue constraint

This facet verifies that an instance is different from a specified value.

Example:

In this example, the empty string is excluded from the possible values.

excludeSegment constraint

This facet verifies that an instance is not included in a segment of values. Boundaries are excluded.

Example:

In this example, values between 20000 and 20999 are excluded.

Enumeration facet filled by another node

By default, an enumeration facet is described statically in XML Schema.

The content of an enumeration facet can be filled dynamically by another node of the adaptation model.

Filling by a list

With the following information, we indicate that the content of an enumeration facet comes from the node CountryList .

The node CountryList : 

• Must be of the same type as the node that has the enumeration facet

• Must be an aggregated list ( maxOccurs > 1).

Example:

Programmatic Facets

A programmatic constraint can be added on any XML element declaration that refers to a simple type.

In order to guarantee the conformance to XML Schema, those constraints are specified under the element annotation/appinfo/otherFacets .

Programmatic constraints

A programmatic constraint is defined by a Java class that implements the interface Constraint.

Additional parameters can be defined. Consequently, the implemented Java class must conform to the JavaBean protocol. In the example below, the Java class must define the methods: getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Example:

See also:

• JavaBeans Specifications

Programmatic enumeration constraints

An enumeration constraint adds to a basic programmatic constraint the definition of an ordered list of values. Such a constraint is defined by a Java class that implements the interface ConstraintEnumeration . This facet allows to select a value from a list.

Example:

Programmatic nomenclature constraints

A nomenclature constraint adds to a basic programmatic constraint the definition of an ordered list of value-labels (see Nomenclature). Such a constraint is defined by a Java class that implements the interface ConstraintNomenclature . This facet allows to select a value from a list.

Note that an enumeration constraint is more appropriate when display must be localized or when there are many values in the enumeration.

Example:

Constraint on null value

Sometimes, a value is mandatory only if some conditions are verified (for example if another field has some specific value). In this case, the standard XML Schema attribute minOccurs will not help because it is static.

For checking if a value is mandatory or not, according to its context:

1. a programmatic constraint must be defined by a Java class (see above);

2. this class must also implement the interface ConstraintOnNull ; 

3. XML Schema cardinality attributes must specify that the element is optional ( minOccurs="0" and maxOccurs="1" ).

Note: By default, constraint on null value is not checked on user input. In order to enable this check, the 'checkNullInput' property must be set and if the element is terminal, the adaptation instance must also be activated.

Example:

Constraints on table

A constraint on table is defined by a Java class that implements the interface ConstraintOnTable . 

A constraint on table can only be defined on a table node.

Additional parameters can be defined. Consequently, the implemented Java class must conform to the JavaBean protocol. In the example below, the Java class must define the methods: getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Example:

Important: Regarding the validation process, constraints on tables are only checked when calling a validation report of an adaptation instance/table. This means, for performance purposes, these constraints are not checked when updates (such as occurrence insertion, deletion or modification) on tables occur. However the internal incremental validation framework will optimize the validation cost of these constraints if dependencies are defined. For more information, see performance section.

See also:

• JavaBeans Specifications

Triggers and Functions

Computed values

By default, Master Data are read and persisted in the XML repository. Nevertheless, they may be the result of a specific computation and/or access an external database (a RDBMS, a central system...).

EBX.Platform even allows to take into account other Master Data in the current adaptation context.

This is made possible by defining functions .

A function is specified in the XML Schema document by using the osd:function element (see example below).

• The value of class attribute must be the qualified name of a Java class which implements the Java interface ValueFunction . 

• Additional parameters may be specified at schema level, in this case the JavaBeans convention is applied.

Example:

Triggers

Adaptation instances or table occurrences can be associated with methods that are automatically executed when some operations are performed: creation, update, delete, etc.

In the XML Schema document, these triggers must be declared under the annotation/appinfo element using the osd:trigger tag.

For adaptation instances triggers, we have to define, inside the osd:trigger tag, a Java class that extends the abstract class InstanceTrigger . 

Note that in the case of adaptation instance triggers, it is advised to define annotation/appinfo/osd:trigger tags just under the root element of the considered XML schema.

Example:

For the definition of tables occurrences triggers, we have to define, inside the osd:trigger tag, a Java class that extends the abstract class TableTrigger . 

In the case of table occurrences triggers, it is advised to define the annotation/appinfo/osd:trigger tags just under the element describing the considered table or table type.

Examples:

On a table element:

or on a table type element:

Note that additional parameters can be defined. Consequently, the Java class implemented must conform to the JavaBean protocol. In the example above, the Java class must define the methods: getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Auto incremented values

It is possible to define auto-incremented values. Auto-incremented values are only allowed inside a table, and they must be of type xs:int or xs:integer . 

An auto-increment is specified in the XML Schema document by using the osd:autoIncrement element under the annotation/appinfo element tag.

Example:

There are two optional elements start and step .

Example:

The start attribute specifies the first value for this auto-increment. If this attribute is not specified, then the value 1 is set by default.

The step attribute specifies the step for the next value to be generated by the auto-increment. If this attribute is not specified, then the value 1 is set by default.

A field specifying an osd:autoIncrement has the following behaviour:

• The computation and allocation of the field value are performed whenever a new record is inserted and the field value is still undefined.

• No allocation is performed if a programmatic insertion already specifies a non null value. For example, if an archive import or an XML import specifies the value, then it is preserved. Note also that, consequently, the allocation is not performed for a record insertion in occulting or overwriting modes.

• A newly allocated value is, whenever possible, unique in the scope of the repository. More precisely, the uniqueness of the allocation spans over all the instances of the schema, and it also spans over all the branches. The latter case allows to merge a branch to its parent with a reasonable guarantee that there will not be a conflict if the osd:autoIncrement is part of the records' primary key. This principle has a very specific limitation: when a massive update transaction specifying values is performed concurrently to a transaction allocating a value on the same field, it is possible that the latter transaction will allocate a value that will be set in the first transaction (there is no locking between several branches).

Internally, the auto-increment value is stored in 'Auto Increments' table of ebx-repository adaptation. This field is automatically updated, so that it defines the greatest value ever set on the associated osd:autoIncrement field, in any instance and any branch in the repository. This value is computed, taking into account the max value found in the table being updated.

In some particular case, for example when multiple environments have to be managed (development, test, production), each having different auto-increment ranges, it may be required to avoid this "max value" check. This particular behavior can be achieved, thanks to the disableMaxTableCheck property:

• locally, by setting a parameter element in auto increment declaration: <disableMaxTableCheck>true</disableMaxTableCheck> ,

• for the whole schema, by setting <osd:disableMaxTableCheck="true"> in xs:appinfo of schema declaration,

• or globally, by setting property ebx.autoIncrement.disableMaxTableCheck=true in main configuration file (ebx.properties).

Note that it is generally not recommended to enable this property, as this could generate conflicts in the auto-increment values.

User Input Control

Check null input

According to EBX.Manager default validation policy, in order to allow a temporary incomplete input, the control whether an element is defined when it is mandatory is not performed on user input, but on adaptation validation only. If the 'mandatory feature' must be checked immediately on user input, the element must additionally specify: osd:checkNullInput="true" .

Note: A value is mandatory if the schema specifies that the element is mandatory, either statically ( minOccurs="1") or dynamically (by means of a Constraint on null). For terminal elements mandatory values are checked only for an activated adaptation instance. For not terminal elements the adaptation instance does not need to be activated.

Example:

See also:

• constraint on null
• Whitespaces management

EBX.Platform whitespaces management for Data Types

According to XML Schema ( cf. http://www.w3.org/TR/xmlschema-2/#rf-whiteSpace ), whitespaces handling must follow one of preserve, replace or collapse procedures:

• preserve. No normalization is done, the value is not changed

• replace. All occurrences of #x9 (tab), #xA (line feed) and #xD (carriage return) are replaced with #x20 (space)

• collapse. After the processing implied by replace, contiguous sequences of #x20's are collapsed to a single #x20, and leading and trailing #x20's are removed

EBX.Platform general management

EBX.Platform complies with XML Schema recommendation:

• For nodes of type xs:string (whether primary key element or not), whitespaces are always preserved and an empty string is never converted to null . 

• For other nodes (non xs:string type), whitespaces are always collapsed and an empty string is converted to null .

Exceptions: For nodes of type osd:html or osd:password , whitespaces are always preserved and an empty string is converted to null . For nodes of type xs:string defining property osd:checkNullInput="true" an empty string is interpreted as null at user input in EBX.Manager.

Specific case for handling whitespaces on a primary key of type string

For primary key columns of type xs:string , a default EBX.Platform constraint is defined. This constraint forbids empty strings and non collapsed whitespaces values at validation level.

However, if the primary key node specifies its own xs:pattern facet, this last one overrides the default EBX.Platform constraint. For example, the specific pattern .* would accept any strings (note that we do not recommend this).

The default constraint allows to handle some ambiguities. For example, it would be difficult for a user to distinguish between the following strings: "12 34" and "12  34". For usual values, it does not create conflicts but for primary keys, it could create errors.

Note: EBX.Platform provides a complete Tables specification , that allows to organize and manage your Master Data as in relational databases.

Home > Models