Default XML Configuration DTD

<!-- To allow for XML validation of your rules configuration file, include the following DOCTYPE element at the beginning (after the "xml" declaration): <!DOCTYPE validation-root PUBLIC "-//iScreen//DTD iScreen 2.0.0//EN" "http://i-screen.org/docs/iscreen.dtd"> --> <!-- This is the root node of the XML configuration file. Note that the 'namespace' attribute is required. This should be unique across configuration files. The 'default-resource' is applied ONLY to this file and ONLY to those elements where a resource-id could be set and isn't (and is overridden by more local default-resource attributes). --> <!ELEMENT validation-root (include | validation-set | validator | resource)*> <!ATTLIST validation-root namespace CDATA #REQUIRED> <!ATTLIST validation-root default-resource CDATA #IMPLIED> <!-- Includes another XML configuration file. Validators, sets, resources, etc. that are referenced must include the namespace. The file attribute is a classpath-based relative path to the configuration file (for example, to use the embedded validators that come with iScreen, file would be 'org/iscreen/validators.xml'). --> <!ELEMENT include EMPTY> <!ATTLIST include file CDATA #REQUIRED> <!-- Defines a ValidationSet, which is a set of configured validators that can be used to validate a single Java object (this element maps one-to-one with an instance of the org.iscreen.ValidationService interface). Note the id is required and must be unique across all ids within this file (and the defined namespace). This element can contain any number, in any order, of the use-validator and use-validation-set elements. Validations are performed in order as they are defined in the XML instance (config file). The 'default-resource' defines the resource to use when one is not configured. It is ONLY applied to the specific validation-set. --> <!ELEMENT validation-set (use-validator | use-validation-set | meta)*> <!ATTLIST validation-set id CDATA #REQUIRED> <!ATTLIST validation-set default-resource CDATA #IMPLIED> <!-- This defines a named Validator (and possible configuration). At least one of these MUST be defined for any given org.iscreen.Validator implementation (that is, if it's to be referenced within the configuration file). Validator definitions can reference other Validator definitions in a configuration chain (meaning, the referenced Validator provides configuration that may be overridden by the Validator Definition that references it). At some point along that chain, the class name (using the 'class' attribute) MUST be defined (it's technically okay to have the root Validator Definition omit the class, as long as that Validator is never directly referenced within a ValidationSet, since its Validator class is not known and can't be instantiated). The class can be overridden in subsequent (child definitions) definitions (in fact, all configurations can be overridden). Only one label can be defined, though it can be overridden in subsequent (child definitions) definitions. There are can be any number of mappings, constraints, and failures (or none). Constraints and failures are keyed off their 'property' attributes, which means that to override one, use the IDENTICAL property (the whole OGNL expression must be identical, not what it resolves to). Mappings are keyed off the 'to' attribute (the whole OGNL expression must be identical). Only one doc (documentation item) can be defined, though it can be overridden in subsequent (child definitions) definitions. The 'ref' attribute is the fully qualified (meaning, the namespace and id) of the defined Validator that is to act as 'parent' to the one being defined. The 'default-resource' acts as the resource when no resource-id is used by any contained elements. However, this resource is NOT used by other Validator definitions (whether by the 'ref' or by other definitions referencing the one being defined). The default resource is meant as a local, temporary shortcut to defining the resource to use for messages. --> <!ELEMENT validator (mapping*, label?, constraint*, failure*, doc?)> <!ATTLIST validator id CDATA #REQUIRED> <!ATTLIST validator ref CDATA #IMPLIED> <!ATTLIST validator class CDATA #IMPLIED> <!ATTLIST validator default-resource CDATA #IMPLIED> <!-- A resource defines a set of messages, resource bundles, and possibly another resource as a set of key/value pairs, where the key and value are both Strings. Resources are used to store messages that can be referenced by elements requiring them, such as a label, a failure message, etc. Resources are given a unique id in order to reference them. The ref attribute allows a resource to refer to another resource: this means that the resource will represent both sets of resource (itself, and the one referenced). Any overlap (those keys defined in both) is handled by the "child" resource (not the one referenced, which is the "parent"). --> <!ELEMENT resource (message | resource-file)*> <!ATTLIST resource id CDATA #REQUIRED> <!ATTLIST resource ref CDATA #IMPLIED> <!-- Within a ValidationSet, the use-validator element is used to reference and configure the use of a single Validator. The ref attribute is required and must point to a defined validator (the validator's id). If it's within the same configuration file, the fully-qualified id (meaning, with the namespace attached) is not necessary. Only one label element is allowed, though any number (including zero) of mapping, constraint, or failure are possible. The fail-fast attribute is either true or false, and dictates that if a failure occurs during validation, the rest of the ValidationSet's validators (or sub-validation sets) are ignored (not executed). The name attribute is optional, but may be used to link the use of the validator to the failure(s) it produced. This is useful when that linkage is important at the presentation layer. The if attribute is optional, but may be used as a conditional of executing the validation. For example, you can use the attribute to ensure that an object is not null. It works the same was as the if attribute on the validation-set element. --> <!ELEMENT use-validator (mapping*, label?, constraint*, failure*, doc?)> <!ATTLIST use-validator ref CDATA #REQUIRED> <!ATTLIST use-validator fail-fast (true|false) "false"> <!ATTLIST use-validator name CDATA #IMPLIED> <!ATTLIST use-validator if CDATA #IMPLIED> <!-- Within a ValidationSet, another ValidationSet can be "called" or added as part of the validations to execute. This is done by using the use-validation-set element. This element has no sub-elements, and only takes the appropriate attributes. The ref attribute is required and refers to the ValidationSet that is being included into the containing ValidationSet. The fail-fast attribute acts the same as the fail-fast attribute of the use-validator element. Any failures that are reports (if this flag is set to true) will cause no more validation of the containing ValidationSet. The if attribute is an OGNL expression (using the OgnlRoot) that if it results in true, then the included ValidationSet is called. If it is false, then the ValidationSet is skipped (if it's not specified, it implies true). The iterate attribute can be either true or false, and defaults to false. If true, the object being validated (the entire bean, unless the map attribute is set) is assumed to be a Collection or an array, and will be iterated over, with each item in the iteration being validated independently. If the object being iterated over isn't a Collection or an array, then it is assumed to be an array of one (the object, itself). The map attribute defines the mapping of the object being validated to another object. It is an OGNL expression with the OGNL root being the object being validated. It defaults to the OGNL expression of #root, which represents the OGNL root, itself (that is, the object being validated). The attribute is not required. The name attribute is optional, but may be used to link the use of the entire validation set to the failures it produced. This is useful when that linkage is important at the presentation layer. --> <!ELEMENT use-validation-set EMPTY> <!ATTLIST use-validation-set ref CDATA #REQUIRED> <!ATTLIST use-validation-set fail-fast (true|false) "false"> <!ATTLIST use-validation-set if CDATA #IMPLIED> <!ATTLIST use-validation-set iterate (true|false) "false"> <!ATTLIST use-validation-set map CDATA "#root"> <!ATTLIST use-validation-set name CDATA #IMPLIED> <!-- Meta data represents information about a validation set that can be used to retrieve a validation service from a validation factory via the meta data's property name and value. If not property attribute is used, then the property name is assumed to be "className". A simple example is to link a JavaBean's class name with the validation set that validates it. For example, leaving off the property attribute (or using "className" which means the same thing), and putting the fully-qualified class name of the JavaBean inside the tag will allow you to pull the validation service this way: validationFactory.getValidationService( "className", "org.some.javaBean" ); Multiple meta tags can be associated with a validation set, allowing the association of multiple classes or other meta data with the validation service. Note that the returned validation service using the above code returns a ValidationServiceGroup (which implements the ValidationService interface), and may contain zero or more actual validation services. Calling validate on it will call the validate() method against all contained validation services (no fail fast). --> <!ELEMENT meta (#PCDATA)> <!ATTLIST meta property CDATA "className"> <!-- The mapping element is a sub-element of the use-validator and validator elements. It's used to map properties from the incoming object being validated to the "beanToValidate" bean, that the Validator actually validates. The from attribute represents the OGNL expression on the incoming object being validated; whereas the to attribute is an OGNL expression on the "beanToValidate" bean. The from attribute defaults to the #root expression, which means the entire object is to be validated. The default OGNL expression on the to attribute is the value property, and is meant to be used against the org.iscreen.SimpleBean, which has a single value property. Multiple mapping elements can be used for those Validators that support multi-field validation. --> <!ELEMENT mapping EMPTY> <!ATTLIST mapping from CDATA "#root"> <!ATTLIST mapping to CDATA "value"> <!-- The label element is a sub-element of the use-validator and validator elements. Only one label element can be contained by any given validator or use-validator, though it can be over-ridden by a "child" configuration (i.e. a use-validator's label over-rides the label defined in the validator that it references). The label is typically used for two purposes: first, it's made available via the OgnlRoot so that failure messages can use it when generating the message to display to the user. Second, when a failure occurs, the label is associated with the particular ValidationFailure object (which represents an individual failure message). This allows the client of the ValidationService to link the message with a particular label (for example, it can use that label to associate the message with a particular field in the user interface). The label's text is defined one of two ways: first, by hard-coding the message as the contents of the element. Second, it can be defined by referencing a resource and the resource key. Hence, the resource-id and key attributes can be used to reference a particular configured Resource and a message within it. Note that the resource-id can be ignored if the containing element (up to the root element) defines a default resource id. --> <!ELEMENT label (#PCDATA)> <!ATTLIST label resource-id CDATA #IMPLIED> <!ATTLIST label key CDATA #IMPLIED> <!-- The constraint element is a sub-element of the use-validator and validator elements. It represents a static property on the Validator that is set prior to any validation (and is only set once per lifecycle of the Validator). The constraint may be a simple property, where the value of the property is defined by the contents of this element. Or, it may be an externally defined service, where the service-id attribute is used to refer to the service defined and provided to the ValidationFactory. In either case, the property attribute is required, and is an OGNL expression on the Validator object, itself. --> <!ELEMENT constraint (#PCDATA)> <!ATTLIST constraint property CDATA #REQUIRED> <!ATTLIST constraint service-id CDATA #IMPLIED> <!-- The failure element is a sub-element of the use-validator and validator elements. It represents a failure message that the Validator can use to report a particular failure. Validators can have one or more failure properties (and, hence, one or more possible types of failures). The actual message can be defined one of two ways: first, the message can be embedded as the content of this element. It can contain embedded OGNL/MVEL expressions via the use of ${} or @{} (for example, the following message puts the label in the message: "This is the label: ${label}"). Second, the message may be defined via a resource-id and key (the same way that's done for the label). Again, if the containing element (up to the root) defines a default resource id, then the resource-id is optional (if using that approach). In addition, a failure has a severity, such as an error or warning. The 'severity' attribute defines this severity. By default, the severity is 'FAILURE'. Possible values are FAILURE (value of 5), CRITICAL (value of 10) and WARNING (value of 3). In addition, a raw integer can be used, with the higher the number meaning a greater severity of failure. A failure can have multiple messages associated with it. The message defined as part of the resource-id/key (or contained element text) is the default failure message. Additional messages can be defined by adding 'msg' sub-elements. Each of these sub-elements have a name that is used to retrieve the message from the ValidationFailure instance. --> <!ENTITY % messages "#PCDATA | msg"> <!ELEMENT failure (%messages;)*> <!ATTLIST failure property CDATA #REQUIRED> <!ATTLIST failure resource-id CDATA #IMPLIED> <!ATTLIST failure key CDATA #IMPLIED> <!ATTLIST failure severity CDATA "FAILURE"> <!-- The msg element represents an individual message that can be associated with a failure. A failure can have zero or more msg sub-elements. Each msg element represents a named message that can be retrieved when a failure occurs. If the msg element contains text, that text is used as the message. Otherwise, if a key (and a resource-id, if over-riding the resource being used) is specified, then it is used to define the message. The name attribute is required, and is used to retrieve the message from the API (ValidationFailure object). --> <!ELEMENT msg (#PCDATA)> <!ATTLIST msg resource-id CDATA #IMPLIED> <!ATTLIST msg key CDATA #IMPLIED> <!ATTLIST msg name CDATA #REQUIRED> <!-- The message element is a sub-element of the resource element, and defines a non-internationalizable message (i.e. it's hard-coded in the config) that can be referenced by those elements using messages (such as label and failure). The key attribute is required and is a unique id (no namespace) used to reference the key. The value of the message is contained within the contents of this element. A resource may have any number of messages, as long as the keys are unique. --> <!ELEMENT message (#PCDATA)> <!ATTLIST message key CDATA #REQUIRED> <!-- The resource-file element is a sub-element of the resource element, and is used to reference a Java resource bundle (that's what the file attribute is for). The file should refer to the classpath-aware location of the resource bundle using the appropriate notation (see the ResourceBundle class for details). Any number of these elements can be contained by the resource element. --> <!ELEMENT resource-file EMPTY> <!ATTLIST resource-file file CDATA #REQUIRED> <!-- Documentation for the Validator - can contain MVEL or OGNL expressions using @{} or ${} --> <!ELEMENT doc (#PCDATA)>