Previous
Next


Additional Features  Locate

Message Validation  Locate

WSO2 SOA Enablement Server supports the validation of XML simple types in SOAP messages with document/literal binding. Simple types restrict the possible contents of an XML element or the value of an XML element's attribute. The definition of simple types is given in the XML schema contained within the WSDL file in the 'types' section. For further details, please see the XML schema specification.

[Note]Note

Validation of complex types is not supported by WSO2 SOA Enablement Server for Java.

In the following text we use the terms "validation of message" or just "validation" to refer to the validation of simple types comprising an XML message against the XML schema simple types defined in the service's WSDL.

Error Reporting When an error is detected in an incoming message, the request is not carried out and a fault message with org.systinet.xml.schema.validation.ValidationException and a detailed description is sent to the other party.

Enabling validation If the user did not choose validation on client and/or server side during installation (by checking the checkbox 'XML schema validation' during WSO2 SOA Enablement Server for Java installation), validation is not available. This is because of performance reasons. If you would like to enable validation after you have already installed WSO2 SOA Enablement Server for Java, you have to re-install it or modify the installation as described in the following sections. So if you configure the validation using the ways described below and it seems to you that validation does not work, it may be because it is not available (installed).

[Caution]Caution

Exercise great care when modifying configuration files.

You may configure validations at three levels:

  • System wide enablement using configuration files

  • Per service endpoint using deployment descriptor

  • At runtime using API

Whether and how to perform the validation is influenced by the content of several configuration files and/or runtime settings. If the developer has configured the validations using runtime API, then these settings take effect.

Otherwise the deployment descriptor is tried and if there is no validation-related section, the system-wide configuration is read. The order can be expressed as follows:

  1. See if the developer configured the validation using runtime API. If yes, stop. Else:

  2. See if the package has configured validations in it. If yes, stop. Else:

  3. Use the system-wide configuration of validations

In any of these three cases, the following two conditions must be met in order to make the validation work:

  1. The validator de/serializer must be in the de/serialization chain. This is configured in the deployment descriptor present in builtin_serialization.jar. The validating de/serializer should be the first de/serializer in the chain. To make this so, the processing element of the deployment descriptor needs to include the following section: 

    <dd:serialization name="XMLValidatingSerializerProxy"
    serializer-class="com.systinet.wasp.validator.serialization.ValidatingSerializerProxy"
    deserializer-class="com.systinet.wasp.validator.serialization.ValidatingDeserializerProxy"
    following-parts="tns:XMLSimpleSerializer" />

    If validations are not used at all, this section may be omitted for performance reasons. Please note that builtin_serialization.jar is also present in WASP_HOME/app/system and may be cached in WASP_HOME/app_classpath, and all of these files must contain the same deployment descritptor.

  2. The package validator.jar needs to be present on the classpath, meaning the WASP_HOME/lib directory. If it is not (because you did not choose this package when installing WSO2 SOA Enablement Server for Java) then either:

    • A relevant error message is printed out (provided that the first requirement is fullfilled), or

    • No message is printed out and it is silently ignored (provided that the first requirement is not fullfilled)

    and the processing continues with validation disabled. To make sure your validator.jar is in the classpath, check your WASP_HOME/lib directory.

If you have chosen client and/or server validation during installation, then both requirements are fullfilled automatically. If you would like to utilize validations after you have installed WSO2 SOA Enablement Server for Java without selecting the validation, you can modify your installation according to the requirements described above.

The following sections describe all three configuration scenarios for validation:

System-Wide Configuration  Locate

Whether validation is performed by default or not depends on what you chose at installation. Your selection is saved in the WASP_HOME/conf/serverconf.xml and WASP_HOME/conf/clientconf.xml files.

Consider the following excerpt from one of those files:

<config name="main">
    <preferences name="main">
	...
	<defaultValidation>
                  <server direction="in out"/>
                  <client direction="in"/>
	</defaultValidation>
	...
    </preferences>
...
</config>

This excerpt says that validation is enabled and where it is performed. If the above excerpt is not present in the config file, then validation is not performed by default. Validation is also suppressed if the direction is "none."

If validation is enabled, it may be performed by client, server or both, depending on whether server and/or client elements are included. In the excerpt above, both client and server validation are enabled.

The direction of messages to be validated is determined by the "direction" attribute in the server and client elements. In the excerpt above, server validation is enabled for both incoming and outgoing messages and client validation for incoming messages only.

The direction attribute may have following values:

  • in: incoming messages are validated

  • out: outgoing messages are validated

  • in out: both incoming and outgoing messages are validated

  • none: validation is disabled

[Caution]Caution

Exercise great care when modifying configuration files.

Validation per Service Endpoint or Service Client   Locate

The validation strategy may be specified in a package's deployment descriptor. Example 289 is an excerpt from a service deployment descriptor that enables validation:

Example 289. Service Deployment Descriptor Defining Validation

<package client-package="false"
		xmlns="http://wso2.com/wasp/package/1.2"
 		...>
	...
    <service-endpoint ...>
		...
		<validation xmlns="http://wso2.com/wasp/package/validation/1.0"
                        direction="in out"/>
    </service-endpoint>
	...
</package>

A client deployment descriptor that enables validation is given in Example 290

Example 290. Client Deployment Descriptor Defining Validation

<package client-package="true"
     xmlns="http://wso2.com/wasp/package/1.2"
	 	...>
	...
    <service-client ...>
        <validation xmlns="http://wso2.com/wasp/package/validation/1.0"
				direction="in"/>
    </service-client>
</package>

Validation through Runtime API  Locate

The method with the highest priority is to set up the validation using WSO2 SOA Enablement Server's API. If the validations are configured through API, neither the deployment descriptor nor the system wide configuration are checked. Example 291 is a snippet of code showing the API usage on the server side (dynamically published service with validations enabled):

Example 291. Runtime Configuration Enabling Validation

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.advanced.validation;

import org.idoox.config.Configurable;
import org.idoox.config.Configurator;

import org.systinet.wasp.Wasp;
import org.systinet.wasp.webservice.Registry;
import org.systinet.wasp.webservice.ServiceEndpoint;
import org.systinet.wasp.webservice.ServiceInstance;

import org.systinet.xml.schema.validation.ValidationConfig;

import java.util.HashMap;


public class RuntimeConfiguration {
    private static final String SERVICE_PATH = "/HelloService";

    public static final void main(String[] args) throws Exception {
        Class.forName("example.advanced.validation.HelloService");

        HashMap properties = new HashMap();
        properties.put("wasp.location", "/opt/karel/develop/wasp-test/wasp");
        Wasp.init(properties);
        Wasp.startServer("http://localhost:6060");
        System.out.println("Server started");

        // obtaining an instance of service endpoint
        ServiceEndpoint serviceEndpoint =
            ServiceEndpoint.create(SERVICE_PATH, HelloServiceImpl.class);

        // configuring server side validation against xml schema
        ValidationConfig config =
            (ValidationConfig) Configurator.newRuntimeConfigurable()
                                           .narrow(ValidationConfig.class);

        // set the direction of validations
        config.setDirection(ValidationConfig.DIRECTION_ALL);

        // set the type of validation
        config.setValidationType(ValidationConfig.VT_SIMPLE_TYPES);

        // applying validation configuration to endpoint that will be published
        serviceEndpoint.getContext()
                       .getContextData()
                       .put(ValidationConfig.CONTEXT_KEY, config);
        System.out.println("Configuration created and set");

        // now is service properly initialized and we can publish it
        Registry.publish(serviceEndpoint);
        System.out.println("Service published");

        //Wasp.destroy();
        System.out.println("Enjoy!");
    }
}

The code in Example 291 performs the following actions:

  1. Creates an instance of org.systinet.xml.schema.validation.ValidationConfig.

  2. Sets the desired configuration on the created object:

    • direction: in out - the same meaning as direction attribute in System-Wide Configuration

    • type: The only supported type of validations at this moment are simple types validations. This value is set, otherwise no validation will be performed. (VT_SIMPLE_TYPES is not the default value.)

  3. Puts the configured instance into the service endpoint context under a dedicated key (ValidationConfig.CONTEXT_KEY)

[Note]Note

Setting the type was not necessary with the other configuration scenarios because in those cases simple type was the default.

The situation differs slightly on the client side. The code in Example 292 performs the same functions as that in Example 291, except that it also places a value into the context.

Example 292. Runtime Configuration Enabling Validation

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.advanced.validation;

import org.idoox.config.Configurator;

import org.systinet.wasp.webservice.Registry;
import org.systinet.wasp.webservice.ServiceClient;

import org.systinet.xml.schema.validation.ValidationConfig;


public class HelloClient {
    private static final String WSDL_URL =
        "http://localhost:6060/HelloService/wsdl";

    // create instance of service client
    public static void main(String[] args) throws Exception { 

        serviceClient client = ServiceClient.create(WSDL_URL);

        if ((args.length == 1) && args[0].equals("-rtvalidate")) {
            // put the validation configuration into the context
            ValidationConfig config =
                (ValidationConfig) Configurator.newRuntimeConfigurable()
                                               .narrow(ValidationConfig.class);

            // set the direction of validations
            config.setDirection(ValidationConfig.DIRECTION_IN);

            // set the type of validation
            config.setValidationType(ValidationConfig.VT_SIMPLE_TYPES);

            // applying validation configuration for the client
            client.getContext()
                  .getContextData()
                  .put(ValidationConfig.CONTEXT_KEY, config);
        }

        // obtain the interface
        HelloService proxy =
            (HelloService) client.createProxy(HelloService.class);
        System.out.println(proxy.hello("world"));
    }
}

Now you are ready to invoke actions on the referenced service, while validating the incoming messages.



Previous
Next