JeeWiz Architect's Guide - Constraint Object


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 14. 'Business Object' Reference

14.15 Constraint Object

Used on

baseViewField

field

internalClass

method

parameter

Description A constraint constrains a single value held by the 'parent', such as an entity attribute, data-view field or a method parameter.

The constraint is specified by one or more of the following:

the expression property or
regular expression (pattern-matching) property or
a list of valid choices or
min/max-value attributes (for numeric parents) or
min/max-length attributes (for String parents)
If the parent's value fails the validation then an exception is thrown.

The exception can be specified in the constraint-exception-type attribute, and the message in the message attribute.

The constraint-exception-type is a delegated property, so the eventual default is the constraintExceptionType value specified in system.properties.

Multiple constraints can be specified in the following combinations:

an expression or a regular expression can be specified, but not both, plus
a list of choices for String or numeric data types, plus
min/max-values for numeric or Date data types, plus
min/max-length for strings.
At least one of the checks must be specified.

Contained
Lists

1

Name   choice

Type   String

Description   Specifies a set of valid values. The choice list can only be specified on String or numeric data types.

Unique   false

Validation 1.   One or more of these must be specified: expression, regular expression, min/max value, min/max length or choices
2.   You can specify an expression or a regular expression but not both
3.   If you specify an expression or regular expression, you must also specify the message

Inherited
properties

template (base property)

text (base property)

jwpattern (base property)

14.15.1	Property 'name'
14.15.2	Property 'description'
14.15.3	Property 'expression'
14.15.4	Property 'regularExpression'
14.15.5	Property 'message'
14.15.6	Property 'minValue'
14.15.7	Property 'maxValue'
14.15.8	Property 'minLength'
14.15.9	Property 'maxLength'
14.15.10	Property 'constraintExceptionType'
14.15.11	Property 'generateLogLevel'
14.15.12	Property 'uid'

14.15.1 Property 'name'

*Description*	The name of the constraint is not used in the code, but is provided in case you want to give the constraint an identifier. This is useful if you are tracking from requirements through to implementation: particular business requirements can be identified in the constraints.
*Type*	String

14.15.2 Property 'description'

*Description*	This can be used to describe the business reasons behind, or specification for, a constraint.
*Type*	String

14.15.3 Property 'expression'

*Description*	'expression' defines the constraint: if true, the value is acceptable. The constraint expression is evaluated in the context of its containing object. This means that you can - and should - refer to the items being constrained by their names. This is possible because the standard patterns create Java fields using the name exactly as specified. You should reference items by name because constraints on entity attributes are propagated to fields on screens by the standard patterns, and the value is referenced by the same name. For example, to ensure that a required string value (say in a data-view field 'dvf') contain '-' you would say dvf != null && dvf.indexOf( '-' ) >= 0 You do not need to enclose the expression in () parens - this will be done by the generation patterns if necessary.
*Type*	String
*Support Element Inputs*	true

14.15.4 Property 'regularExpression'

Description

Specifies the validation rule as a regular expression. This is only available on strings.

There are no special surround characters you need to specify on the expression (we mention this in case you are used to writing language expressions by enclosing REs in '/', for example in AWK or Perl).

A very quick reference of the most used regular expression features is given below.

Atoms:

. Matches any character other than newline
a Matches 'a' (any non-atom special character) anywhere in the string
[0-9] Character class (i.e. a numeric character)
[a-zA-Z] Character class with ranges
[^abc] Negated character class
\s Matches a whitespace character
\S Matches a non-whitespace character
\d Matches a digit character
\D Matches a non-digit character
\t Matches an ASCII tab character
\n Matches an ASCII newline character
\r Matches an ASCII return character
\f Matches an ASCII form feed character

Expressions (where 'A' is an atom)

^A Anchors the expression to the beginning of the string
A$ Matches beginning (^), 'a', and ending ($).
A* Matches A 0 or more times
A+ Matches A 1 or more times
A? Matches A 1 or 0 times
A{n} Matches A exactly n times
AB Matches A followed by B
A|B Matches either A or B
(A) Used for subexpression grouping

For Java code, JeeWiz uses the 'RegExp' package, version 1.2, to evaluate regular expressions - see the Apache Web site for details. Using regular expresions creates a dependency on the jakarta-regexp-1.2.jar, but this is included automatically in builds generated by JeeWiz. (For instance the jar file will be automatically included in an EjbJar's manifest classpath and the parent EAR file).

Type

String

14.15.5 Property 'message'

*Description*	Message is the text that will be returned the 'expression' or 'regular-expression' validation fails. The mechanism by which this will be returned will be defined by the template scripts, but will commonly be throwing a business exception. When the message is used at runtime, the code generation template will normally give context around your message. For example, if you say message="Must enter 'yes' or 'no'" then the generated code could look like this: String errmsg = "Constraint violated in class Account.yn: '" + "Must enter 'yes' or 'no', actual value = " + yn; The message is required when an expression or regular expression is specified. It is not used when min-value, max-value, min-length or max-length are specified; an appropriate error message will be constructed by the template.
*Type*	String
*Support Element Inputs*	true

14.15.6 Property 'minValue'

*Description*	Specifies the minimum value for numeric type - defaults to smallest value that can be held by that type.
*Type*	String

14.15.7 Property 'maxValue'

*Description*	Specifies maximum value for numeric type - defaults to largest value that can be held by that type.
*Type*	String

14.15.8 Property 'minLength'

*Description*	Specifies minimum length for a string attribute.
*Type*	String

14.15.9 Property 'maxLength'

*Description*	Specifies maximum length for a string attribute.
*Type*	String

14.15.10 Property 'constraintExceptionType'

*Description*	The constraintExceptionType is the type of the exception which is thrown if the constraint fails. It can be any valid class name - probably defined by a 'jwclass'. It could be, for example, a specific class of business exception which should be thrown for this constraint. If this is not in the same package as the build module (e.g. in the EJB Jar or Ear), then the name should be qualified by the package name. The constraintExceptionType is available on constraints, objects and assemblies, and can also be set in the top level properties build file (e.g. build.jwp). Because this is a delegated property, the actual value used is whichever instance is encountered first, working up from the validation object. This means it is very easy to specialise the exceptions thrown in part of the specification tree (e.g. one session EJB), leaving the rest unchanged. Failing any value at all, 'RuntimeException' is used ... but clearly this should not be used in production systems.
*Type*	String
*Delegates*	true

14.15.11 Property 'generateLogLevel'

*Description*	Should be a number for the trace level priority to generate code. Any lower priority traces will be filtered out at generate time. Most tracing mechanisms, such as log4j, can also filter traces at run-time. The priorities are 1 = Fatal 2 = Error 4 = Warning 6 - Info 8 - Debug (Fine) 9 - DetailedDebug (Finest) This is a delegated property. The default can be set for builds by setting generateLogLevel in the build properties.
*Type*	String
*Delegates*	true

14.15.12 Property 'uid'

*Description*	The 'uid' is a Unique IDentifier for a methods in the business object model (and derivatives like J2EE). The 'uid' uniquely identifies the method, even if the name or signature of the method changes. This will normally be generated by the modelling tool; if not, it can be entered manually (but make sure it is unique!).
*Type*	String