+

Search Tips   |   Advanced Search

Bean validation in RAR modules

WebSphere Application Server validates resource adapter archive (RAR) JavaBeans constraints in compliance with the Java Connector Architecture (JCA) version 1.6 specification.

Resource adapters can specify the validation requirements of configuration properties to the Application Server through annotations in the source code of the resource adapter, constraint specifications in a resource adapter validation descriptor, or a mixture of both. In specifying these constraints, resource adapters can use the built-in bean validation constraints supplied with the Application Server, custom bean validation constraints supplied either by the application developer or a third party, or a mixture of both. Resource adapter developers can apply constraints to the fields and JavaBeans-compliant properties of the following JCA types:

At run time, the application server creates instances of bean types declared by the resource adapter. Each instance is validated immediately upon setting its configuration properties, before placing the instance into service.

When validating a RAR bean, the Application Server creates an instance of a validator factory according to the bean validation deployment descriptor discovered by the Application Server. A validator instance is then obtained from the factory and used to validate the bean instance.

If validation fails, the Application Server throws a constraint violation exception and reports all violations to the system log. The effects of the exception for each RAR bean type and problem determination information are documented in the topic, Troubleshooting bean validation in RAR modules.

The Bean Validation specification requires that no more than one validation.xml is visible on the class path. This requirement is violated whenever two or more stand-alone RARs provide a validation descriptor. See the section, "RAR bean validation descriptor" in this topic, for more information. When more than one validation.xml is visible to the Application Server class loaders, the Application Server or application modules might fail to acquire the default ValidatorFactory and subsequently cannot perform bean validation. For example, the server cannot validate beans of a RAR embedded in an application whenever the embedded RAR lacks a validation configuration, and two or more stand-alone RARs provide configurations. To avoid trouble, install stand-alone RARs that provide a bean validation descriptor as isolated whenever possible.


Built-in constraint annotations

Use built-in constraint annotations to specify the range and mandatory attributes of configuration properties rather than provide custom annotations for the same purpose. The following constraints are useful, but we can use all bean validation built-in constraints. See the topic Bean validation built-in constraints for a complete list of the constraints.bprac

The following example is a RAR bean class that is decorated with built-in constraint annotations.

The value of the serverName configuration property must not be null, and the value of the instanceCount property must be at least 1 when the Application Server creates and configures an instance of the MyConnector class. Otherwise, a constraint validation exception occurs and, in the case of ResourceAdapter bean, the resource adapter fails to start. See the topic Troubleshooting bean validation in RAR modules for more information.

package com.my.company;

@Connector(…)
public class MyConnector implements ResourceAdapter, Serializable 
{
	@ConfigProperty(type=java.lang.String.class,defaultValue="WAS")
	private String serverName;

	@NotNull() 
	public String getServerName() {return serverName;}

	private Integer instanceCount = 0;

	@Min(value=1)
	public Integer getInstanceCount() {return instanceCount;}
	…


RAR bean validation descriptor

Bean validation constraints can be declared through an XML descriptor supplied by a RAR module. In the simplest case, a RAR validation descriptor consists of the validation configuration declared in the validation.xml file and zero or more XML files that declare RAR bean validation constraints. Files containing constraint declarations are specified in the constraint-mapping elements of the validation configuration (validation.xml).

We must package the validation descriptor in the META-INF directory of a RAR module. Any custom constraint annotation classes that are declared in the validation descriptor must also be packaged in the RAR module.

The following example is a simple RAR validation descriptor that declares constraint metadata like the code shown in the section, "Built-in constraint annotations."

<?xml version="1.0" encoding="UTF-8"?>
<validation-config
		xmlns=http://jboss.org/xml/ns/javax/validation/configuration
 		xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
 		xsi:schemaLocation=http://jboss.org/xml/ns/javax/validation/configuration validation-configuration-1.0.xsd>
<constraint-mapping>META-INF/constraints.xml</constraint-mapping>
</validation-config>

The constraints XML file is also located in the META-INF directory and looks like the following: 

<constraint-mappings
	xmlns=http://jboss.org/xml/ns/javax/validation/mapping
	xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
	xsi:schemaLocation=http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.0.xsd>
<default-package>com.my.company</default-package>
<bean class="MyConnector" ignore-annotations="true">
	<field name="serverName">
		<valid/>
		<!-- @NotNull() -->
		<constraint annotation="javax.validation.constraints.NotNull">
			<message>Value is not null</message>
		</constraint>
	</field>
	<field name="instanceCount">
		<valid/>
		<!-- @Min(1) -->
		<constraint annotation="javax.validation.constraints.Min">
				<message>Minimum possible value is 1</message>
				<element name="value">1</element>
			</constraint>
		</field>
	</bean>
<constraint-mapping>
The packaged RAR module, MyResourceAdapter.rar, looks like the following: 
my/
  company/
    MyConnector.class
. . .
ETA-INF
  /validation.xml
  /constraints.xml


Third-party bean validation

WAS supports using different bean validation implementations. If a resource adapter requires a bean validation implementation different from the implementation provided by the product, and the RAR provides the bean validation implementation, we must package the JAR file containing the bean validation implementation in the RAR module root directory.

The RAR module must also contain a single validation configuration descriptor (validation.xml), which can be packaged in the META-INF directory of the RAR module, or in the META-INF/services directory of the bean validation JAR file, but not both.


RAR bean validation configuration discovery

When validating RAR beans, the Application Server bootstraps the bean validation configuration, specific to the RAR, according to the bean validation descriptor supplied in the RAR META-INF directory. If the descriptor does not exist, the server bootstraps the configuration using the first validation descriptor discovered in the RAR class loading context, such as that supplied in a third-party bean validation that is packaged in the RAR. Finally, the server uses the default validation configuration provided by the product.

The server then creates a validator factory specific to the discovered bean validation configuration and uses this factory to create validator instances for validating the RAR bean instances. When we deploy a RAR that supplies a bean validation descriptor, we must take additional steps to ensure that the class loader that loads the RAR loads the bean validation descriptor and classes packaged in the RAR.

For an embedded RAR, after we have deployed the application that embeds the RAR, set the delegation mode of the application class loader to Parent-Last (Child-First). See the topic Configuring application class loaders for more information.

For a stand-alone RAR, install the RAR as an isolated resource provider. See the topic Resource Adapter settings for more information.


Related:

  • JCA 1.6 support for annotations in RAR modules
  • Bean Validation
  • Use bean validation in the product
  • Configure application class loaders
  • Troubleshoot bean validation in RAR modules
  • Bean validation built-in constraints
  • Bean validation troubleshooting tips
  • Resource adapter settings