|
|
|
The Model-Driven System Builder
|
|
JeeWiz Architect's Guide
|
|
|
|
Contents >
16. 'JeeWiz' Reference
|
|
|
16.12 MetaValidator Object
| Used on |
|
| Description | Defines validation of a meta-class.
Validators can be attached to (nested within) meta-classes or meta-factors. In the latter case, the validator is actioned in each meta-class that uses the sucker.
Note that validators are automatically generated for lists and properties of the meta-class in the following situations and need not be specified in separate meta-class validators:
- properties
- required
- has a pattern
- has choices
- supportElementInputs and elementRequired are both false
- lists
- unique
- occurs
- minOccurs
- maxOccurs
- when a base object has validation (validation sequences are daisy-chained, base objects being validated before the current object).
Validators are only recognised on meta-factors and meta-classes; they should not be put on properties, lists or contained-elements.
The interrelation of the various properties defined on the validator is shown by the example.
The properties are enclosed in chevrons:
<<variable-definition>>
if( extraPhase ) { // e.g. extra-phase = true
<<setup>>
if( <<if>> ) {
if( !( <<expression>> ) ) {
al.add( "<<message>>" );
// for each affected field
al.add( "Affected field '<<affected-field'=" + getAffectedField() );
return true; // assuming 'quit-on-false'
}
}
}
if( !validationFailure ) {
<<on-success>>
}
|
Inherited
properties |
| name |
(base property)
| |
| template |
(base property)
| |
| text |
(base property)
| |
| jwpattern |
(base property)
| |
|
16.12.1 Property 'variableDefinition'
|
| Alias | variable |
| Description | The variable-definition (e.g. 'boolean gotAnX') is a variable that will be defined outside the current phase's 'if' block.
This means that this variable definition will be available to other parts of the validation sequence.
The variable-definition must have an initialiser on the definition, otherwise Java gives a "variable might not have been initialized" error.
The real initialisation (setting to a non-empty value) can happen:
- in the variable-definition ('boolean gotAnX = getX() != null'). This makes it available to all following validators, regardless of phase
- in a 'set-up' or 'on-success' clause, which makes the variable dependent on the phase (pre/extra/main) of the owning validator.
In that case, the variable should only be referenced in the particular phase for the validator holding the 'set-up' or 'on-success'.
|
| Type | String |
16.12.2 Property 'prePhase'
|
| Description | Defines whether, or not, the validation is to be done during the preparation phase (the 'prePhase') or after.
If you need to validate information as it was originally specified in the model,
or amended in a preIncludeSpec pattern, pre-phase should be true.
The other alternatives are extra-phase, or neither of pre-phase and extra-phase being set true.
If you need to validate information before the last (includeSpec) pattern phase,
then pre-phase and extra-phase should both be false.
|
| Type | boolean |
| Default | true |
16.12.3 Property 'extraPhase'
|
| Description | Defines whether, or not, the validation is to be done during the extra preparation phase.
The difference between the pre-phase and the extra-phase is that
- pre-phase is run before children have had their pre-phase run (involving preIncludeSpec and pre-phase validation)
- extra-phase is run after this, but before 'extraIncludeSpec is run.
The extra-phase validation should verify the contents of the objects related to the current one, particularly its children.
You can also think of it as preparing the stage for the extraIncludeSpec to be run,
which is done immediately after the extra-phase validation succeeds.
If you need to validate information before the last (includeSpec) pattern phase,
then pre-phase and extra-phase should both be false.
|
| Type | boolean |
| Default | true |
16.12.4 Property 'if'
|
| Description | An expression indicating that the validator should only be checked if the expression is true.
This is done after the 'pre-phase' check, so it gets evaluated at most once.
The 'if' expression follows the 'setup' code, so variables defined there can be used in the 'if' expression.
|
| Type | String |
16.12.5 Property 'setup'
|
| Description | This is code that will be included just before the validation expression is evaluated.
It can be used to set up variables for use in the validator.
To allow validators to be used in meta-factors and to define variables that may be useful for later validators, this code is included outside of the check for pre-phase, which means it will be executed during both pre-phase and later checks.
|
| Type | String |
16.12.6 Property 'expression'
|
| Description | The expression to validate. This should be true to validate the property. If this is false, validation fails.
The expression can be put in as
- a property (expression='...'), or failing that...
- a nested element ('...'), or failing that...
- the text (or embedded CDATA in the element).
|
| Type | String |
16.12.7 Property 'pattern'
|
| Description | The pattern is used as a validation item for the property. This is in addition to any nested elements that may be present on the object object.
Pattern validation should only be used on String properties. If a pattern is specified on any properties with any other type, a compiler error will occur during the build.
The pattern must be a valid regular expression. During validation of the meta-class, the property will need to match this pattern if a value has been specified; the pattern is ignore for un-specified properties.
Note that, as with normal regular expression usage, a pattern is considered to match a string if the pattern occurs anywhere within the string. If what you really intend is the match the complete string, use the '^' (start anchor) and '$' (end anchor) around the pattern.
This is a shorthand for a pre-phase validator object using the same pattern.
|
| Type | String |
16.12.8 Property 'onSuccess'
|
| Description | This is code that will be executed if the validation succeeds.
It can be used to set up variables or trigger events in the validator for later use.
'on-success' is executed within the context of the 'if prephase...' code. This means its operates differently from the 'setup' code:
(a) variables defined in on-success are not available to other properties' 'setup' or 'on-success' code;
(b) the code is executed immediately after a successful evaluation of the validation expression or pattern.
This means that 'on-success' is more suitable to setting other properties in the meta-class or elsewhere, rather than creating local state within the validation routine.
If you really need to create state within the validation routine
- create the variable to be set in the 'setup' code
- set it in the 'on-success' code
- ensure that any other 'setup' or 'on-success' code that uses it has the same 'pre-phase' value.
|
| Type | String |
16.12.9 Property 'message'
|
| Description | 'message' is the text that will be returned when the validation expression fails (i.e. is false).
The message can be specified as an XML attribute (message=...) or nested element (...).
|
| Type | String |
16.12.10 Property 'description'
|
| Description | If the description is given it will be added to the code before the validation expression is evaluated.
|
| Type | String |
16.12.11 Property 'affectedField'
|
| Description | This is a comma-separated list of property names, which must be properties on the meta-class containing the validator, whose value will be logged if the validation fails.
|
| Type | String |
16.12.12 Property 'additionalInfo'
|
| Description | This is the same idea as 'affected-field', but the comma-separated list contains expressions, rather than property names. If the validation fails, the expressions are evaluated and the values attached to the error log.
|
| Type | String |
16.12.13 Property 'quitOnFailure'
|
| Description | If this is set, immediately an error is encountered, validation and any further processing is immediately halted.
To continue doing more validation, set this false - this will make sense for failures that won't cause a crash during the build process.
In either case, a validation failure will prevent generation of any output.
|
| Type | boolean |
| Default | true |
Copyright (c) 2001-2008 New Technology/enterprise Ltd.
| |
