Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 12. Validators

12.1. What is a Validator

A Validator provides message content checking functionality. SwitchYard allows you to declare the validation logic outside the service logic and inject it into the mediation layer at runtime.
Report a bug

12.2. Message Validation

Here is a sample that depicts message validation.
Message Content: 
<MyBook xmlns="example">
  <Chapter1/>
  <Chapter2/>
</MyBook>
This is the associated XML Schema definition: 
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="example"
        xmlns:orders="example">
        <element name="MyBook" type="example:MyBook"/>
        <complexType name="MyBook">
            <sequence>
                <element name="Chapter1" type="string"/>
            </sequence>
        </complexType>
</schema>
The XML content is still well-formed, but it has a Chapter2 element that is not declared as the child of MyBook element in the XML schema. Hence the content cannot be validated against the schema.
Report a bug

12.3. Add Validation to Your Application

Procedure 12.1. Add Validation to Your Application

  • Specify message validation in the descriptor of your SwitchYard application by editing the switchyard.xml file using the JBoss Developer Studio SwitchYard Editor.
    The qualified name of the type being validated is defined along with the validator implementation. This allows validation to be a declarative aspect of a SwitchYard application, as the runtime will automatically register and execute validators in the course of a message exchange. 
     
<validates>
   <validate.xml schemaType="XML_SCHEMA"
                   name="{urn:example}MyBook">
      <schemaFiles><entry file="/xsd/orders.xsd"/></schemaFiles>
   </validate.xml>
</validates>
Report a bug

12.4. Supported Validators

12.4.1. Java

12.4.1.1. Use a Java Validator

Procedure 12.2. Create a Java Validator

  1. Implement the org.switchyard.validate.Validator interface.
  2. Add a <validate.java> definition to your switchyard.xml file.
  3. Alternatively, annotate one or more methods to your Java class with @Validator: 
    		
@Named("MyValidatorBean")
public class MyValidator {
    @Validator(name = "{urn:switchyard-quickstart-demo:orders:1.0}submitOrder")
    public ValidationResult validate(Element from) {
       // handle validation here
    }
}
    When using the @Validator annotation, the SwitchYard Maven plug-in automatically generates the <validate.java> definitions for you and add them to the switchyard.xml file packaged in your application.
    The Java class above produces this <validate.java> definition: 
    	
<validate.java bean="MyValidatorBean"
               name="{urn:switchyard-quickstart-demo:orders:1.0}submitOrder"/>
Report a bug

12.4.1.2. Java Validator Reference

The optional name element of the @Validator annotation can be used to specify the qualified type name used during validator registration. If not supplied, the full class name of the method parameter is used as the type.
The CDI bean name specified by @Named annotation is used to resolve validator class. If you fail to specify it, then the validator's class name is used instead: 
<validates>
   <validate.java class="org.switchyard.quickstarts.demos.orders.MyValidator"
                   name="{urn:switchyard-quickstart-demo:orders:1.0}submitOrder"/>
</transforms>

Note

Each of the <validate.java> definitions have either a bean attribute or a class attribute. These two attributes are mutually exclusive.
Report a bug

12.4.1.3. ValidationResult

ValidationResult is a simple interface which represents the result of validation. It has two methods, isValid() and getDetail().
Report a bug

12.4.1.4. Java Validation Failure

If Java validation fails, the message exchange process stops immediately and a HandlerException is thrown along with a validation failure message which is returned by ValidationResult.getDetail(). Make sure that you return a ValidationResult with failure detail message when you want to indicate a validation failure in your Java Validator, instead of throwing a RuntimeException.

12.4.1.5. ValidationResult Properties

isValid() returns whether the validation succeeded or not. _getDetail() returns an error message if validation fails. 
package org.switchyard.validate;
public interface ValidationResult {
    boolean isValid();
    String getDetail();
}
There are three convenience methods available for org.switchyard.validate.BaseValidator. These are validResult(), invalidResult() and invalidResult(String) Use them to generate ValidationResult objects.
Report a bug

12.4.2. XML

12.4.2.1. Use an XML Validator

The XML validator allows you to perform a validation against its schema definition. It support DTD, XML_SCHEMA, and RELAX_NG schema types. You can configure an XML validator by specifying the schema Type, the name QName, and the path to the schema file. Here is an example: 
<validate.xml schemaType="XML_SCHEMA" name="{urn:switchyard-quickstart:validate-xml:0.1.0}order" failOnWarning="true" namespaceAware="true">
   <schemaFiles>
      <entry file="/xsd/orders.xsd"/>
   </schemaFiles>
   <schemaCatalogs>
      <entry file="/xsd/catalog.xml"/>
   </schemaCatalogs>
</validate.xml>
If you specify the failOnWarning attribute as true, the validation fails if any warning is detected during validation. If the XML content to be validated has namespace prefix, then you need to specify namespaceAware as true.
Report a bug

12.4.2.2. XML Catalog

You can use XML catalog to decouple the schema file location from schema definition itself. This schema is orders.xsd which has a import element. It refers to logical name orders.base by the schemaLocation attribute: 
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="urn:switchyard-quickstart:validate-xml:0.1.0"
        xmlns:base="urn:switchyard-quickstart:validate-xml-base:0.1.0"
        xmlns:orders="urn:switchyard-quickstart:validate-xml:0.1.0">
        <import namespace="urn:switchyard-quickstart:validate-xml-base:0.1.0" schemaLocation="orders.base"/>
...
Here is the catalog.xml file that resolves actual schema location from logical name orders.base: 
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <system systemId="orders.base" uri="orders-base.xsd"/>
</catalog>
Report a bug

12.4.2.3. XML Validation Failure

If XML validation fails, the message exchange process stops immediately and a HandlerException is thrown along with a validation failure message. XMLValidator collects a set of validation failures through the SAX ErrorHandler, and uses the getMessage() of each received SAXParseException as a failure detail with extracting root cause, if exists.