RAR 模块中的 Bean 验证

WebSphere® Application Server 将验证符合 Java™ 连接器体系结构 (JCA) V1.6 规范的资源适配器归档 (RAR) JavaBeans 约束。

资源适配器可以通过资源适配器的源代码中的注释和/或资源适配器验证描述符中的约束规范来指定 Application Server 的配置属性的验证需求。指定这些约束时,资源适配器可以使用随 Application Server 一起提供的内置 Bean 验证约束、由应用程序开发者和/或第三方提供的定制 Bean 验证约束。资源适配器开发者可以对下列 JCA 类型的字段以及符合 JavaBeans 的属性应用约束。
  • ResourceAdapter
  • ManagedConnectionFactory
  • ActivationSpec
  • AdministeredObject
在运行时,应用程序服务器将创建由资源适配器声明的 Bean 类型的实例。将每个实例投入服务之前,设置其配置属性时都会立即验证该实例。

验证 RAR Bean 时,Application Server 将根据 Application Server 所发现的 Bean 验证部署描述符来创建来创建验证器工厂实例。然后,从工厂获取验证器实例,并用来验证 Bean 实例。

如果验证失败,那么 Application Server 会抛出约束违例异常,并在系统日志中报告所有违例。在“对 RAR 模块中的 Bean 验证进行故障诊断”主题中说明了每种 Bean 类型的异常的影响以及问题确定信息。
避免故障 避免故障: “Bean 验证”规范要求类路径中不能有多个 validation.xml 可视。每当两个或两个以上的独立 RAR 提供了验证描述符时,就会违反此要求。有关更多信息,请参阅本主题中的“RAR Bean 验证描述符”一节。当有多个 validation.xml 对于 Application Server 类装入器可视时,Application Server 或者应用程序模块可能无法获取缺省 ValidatorFactory,从而无法执行 Bean 验证。例如,每当嵌入的 RAR 缺少验证配置,并且两个或两个以上的独立 RAR 提供了配置时,服务器就无法验证嵌入在应用程序中的 RAR 的 Bean。为了避免引起麻烦,请尽可能单独安装用于提供 Bean 验证描述符的独立 RAR。gotcha

内置约束注释

最佳实践 最佳实践: 请使用内置约束注释来指定配置特性的范围和必需属性,而不针对同一目的提供定制注释。下列约束很有用,但是您可以使用所有 Bean 验证内置约束。有关约束的完整列表,请参阅 Bean 验证内置约束主题。bprac
  • @Min

    指定使用此注释来装饰的配置属性的最小值。值必须大于或等于所指定的最小值。

  • @Max

    指定使用此注释来装饰的配置属性的最大值。值必须小于或等于所指定的最大值。

  • @Size

    指定使用此注释来装饰的配置属性的值的范围。值必须大于或等于所指定的最小值,并且小于或等于所指定的最大值。

  • @NotNull

    指定使用此注释来装饰的配置属性的值不得为 null。即,此属性是必需属性。

以下示例是一个使用内置约束注释装饰的 RAR Bean 类。

当 Application Server 创建和配置 MyConnector 类的实例时,serverName 配置属性的值不得为 null,并且 instanceCount 属性的值必须至少为 1。否则,会发生约束验证异常,并且对于 ResourceAdapter Bean,资源适配器将无法启动。有关更多信息,请参阅“对 RAR 模块中的 Bean 验证进行故障诊断”主题。

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 验证描述符

可以通过 RAR 模块所提供的 XML 描述符来声明 Bean 验证约束。在最简单的情况下,RAR 验证描述符由 validation.xml 文件中声明的验证配置以及用于声明 RAR Bean 验证约束的零个或多个 XML 文件组成。在验证配置 (validation.xml) 的 constraint-mapping 元素中指定了其中包含约束声明的文件。

您必须将验证描述符打包在 RAR 模块的 META-INF 目录中。在验证描述符中声明的任何定制约束注释类也必须打包在 RAR 模块中。

以下示例是一个简单的 RAR 验证描述符,该验证描述符像“内置约束注释”一节中所显示的代码一样声明了约束元数据。

<?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>
约束 XML 文件也位于 META-INF 目录中,为如下所示:
<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>
已打包的 RAR 模块 MyResourceAdapter.rar 为如下所示:
my/
  company/
    MyConnector.class
. . .
META-INF
  /validation.xml
  /constraints.xml

第三方 Bean 验证

WebSphere Application Server 支持使用不同的 Bean 验证实现。如果资源适配器需要与该产品所提供的实现不相同的 Bean 验证实现,并且 RAR 提供了 Bean 验证实现,那么您必须将其中包含该 Bean 验证实现的 JAR 文件打包在 RAR 模块根目录中。

RAR 模块还必须包含单个验证配置描述符 (validation.xml),该验证配置描述符可以打包在 RAR 模块的 META-INF 目录中,或者打包在 Bean 验证 JAR 文件的 META-INF/services 目录中,但是不能同时打包在这两个目录中。

RAR Bean 验证配置发现

验证 RAR Bean 时,Application Server 将根据 RAR META-INF 目录中所提供的 Bean 验证描述符来引导特定于该 RAR 的 Bean 验证配置。如果该描述符不存在,那么服务器将使用在 RAR 类装入上下文中发现的第一个验证描述符(例如,打包在该 RAR 中的第三方 Bean 验证中所提供的验证描述符)来引导配置。最后,服务器将使用该产品所提供的缺省验证配置。

然后,服务器将创建特定于所发现的 Bean 验证配置的验证器工厂,并使用此工厂来创建验证器实例以验证 RAR Bean 实例。当您部署用于提供 Bean 验证描述符的 RAR 时,您必须执行其他步骤以确保用于装入 RAR 的类装入器装入该 Bean 验证描述符以及打包在 RAR 中的类。

对于嵌入的 RAR,在您已经部署了用于嵌入 RAR 的应用程序之后,必须将应用程序类装入器的委派方式设置为 Parent-Last (Child-First)。有关更多信息,请参阅“配置应用程序类装入器”主题。

对于独立 RAR,您必须将该 RAR 作为单独的资源提供者来安装。有关更多信息,请参阅“资源适配器设置”主题。


指示主题类型的图标 概念主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=cdat_rarbeabval
文件名:cdat_rarbeabval.html