在基于 SEI 的 JAX-WS Web Service 中公开方法

可以在服务端点实现上使用 @WebService 和 @WebMethod 注释来指定要公开为 Java™ API for XML-Based Web Services (JAX-WS) Web Service 的 Java 方法。

开始之前

JAX-WS 技术基于标准服务端点接口和 Provider 接口来启用 Web Service 的实现。如果从现有 Java 类开始开发 JAX-WS Web Service(称为自底向上方法),那么必须使用 @WebService 或 @WebServiceProvider 注释来对类进行注释,以便在最初将类定义为 Web Service。

使用 Provider 接口是定义 JAX-WS 服务的动态方法。类必须实现 javax.xml.ws.Provider 接口且包含 @WebServiceProvider 注释,才能使用 Provider 接口。Provider 接口具有一种方法(即 invoke 方法),在处理各种消息或消息有效内容时,该方法使用 Java 编程语言中的泛型来控制输入和输出类型。

相反,您可使用 Java 注释通过服务端点接口 (SEI) 方法来描述 Web Service。

关于此任务

要在最初定义 Web Service,请使用 @WebService 注释来对 Java 类进行注释。您还可以选择性地使用 @WebMethod 注释来对各种方法进行注释,从而控制公开为 Web Service 操作这一过程。

由于多个 Web Service 规范之间在如何将方法公开为操作方面存在不确定性,因此请使用下列准则来帮助确保不论使用何种 JAX-WS 实现,行为都是一致的。

  • 要定义基本的 Web Service,请使用 @WebService 注释来对实现类进行注释。
  • 要使用显式 SEI 来定义 Web Service,请使用 @WebService 注释的 endpointInterface 属性来显式地引用 Java 接口类。
  • 在 @WebService 注释的 wsdlLocation 属性中,提供对 WSDL 文件的引用。通过指定预定义的 WSDL 文件,可以提高性能。此外,运行时环境会向您报告 WSDL 文件和注释之间的差异。
    避免故障 避免故障: 按照 JAX-WS 2.2 规范,如果将 SOAP 1.2 声明为绑定类型,并且 wsdlLocation 属性是空字符串(这是缺省值),那么容器无法自动生成 WSDL。因此,如果您使用 ?wsdl 来请求 WSDL 文件,那么将显示以下异常消息:
    CWWKW0037E: The WSDL that is compliant with the JAX-WS 2.2 specification cannot be generated.
    如果您要显示 WSDL 文件,那么必须手动生成 WSDL 文件,将其放置在应用程序中并指定具有正确位置的 wsdlLocation 属性。gotcha
  • 使用显式 SEI 时,总是会公开 SEI 与继承类中的所有公用方法。仅当您想要进一步定制已公开的方法时,才需要添加 @WebMethod 注释。
  • 在 @WebService 注释中提供对显式 SEI 或现有 WSDL 文件的引用,有助于消除公开方法时可能存在的不确定性。
  • 如果未使用显式 SEI,请遵循下列规则来确保对方法进行一致公开:
    • 将 @WebService 注释添加至实现类及其所有包含您想要公开的方法的超类。将 @WebService 注释添加至类时,会公开那个类中不是 static 或 final 的所有公用方法。
    • 如果您想要更细粒度的控制,以便仅公开某些方法,请在所选方法上使用 @WebMethod 注释。要确保公开方法,请使用 @WebMethod 注释来对方法进行注释。如果要确保不公开方法,请使用 @WebMethod(exclude=true) 注释对方法进行注释。
支持的配置 支持的配置: sptcfg
用于公开未附注释的方法的行为更改:

有关将方法公开为 Web Service 操作的 JAX-WS 行为已更改。这符合最近的 JAX-WS 规范说明。

从先前版本迁移且不含显式 SEI 或 WSDL 的应用程序可能会表现如下所示的其他操作。可以设置属性以便 JAX-WS 运行时环境使用旧行为。如果迁移不含 WSDL 或 SEI 的应用程序,那么可能需要这样做,以免公开其他方法。

@WebService
public class Foo {
	@WebMethod
	public void a() {}	// exposed now, exposed before
	public void b() {}	// exposed now, not exposed before
}
使用新解释时,实现类及其超类中的公用方法只有在下列情况下才公开:
  • 包含类具有 @WebService 注释。
  • 方法没有 @WebMethod(exclude=true) 注释。
使用旧解释时,实现类及其超类中的方法只有在下列情况下才公开:
  • 包含类具有 @WebService 注释。
  • 方法没有 @WebMethod 注释,并且任何其他方法都没有 @WebMethod 注释。
  • 方法具有 @WebMethod 或 @WebMethod(exclude=false) 注释。

要指定 JAX-WS 运行时环境使用旧 @WebMethod 行为,请配置 jaxws.runtime.legacyWebMethod=true 属性。可以将此属性配置为 Java 虚拟机 (JVM) 系统属性,或者配置为 Web 应用程序归档 (WAR) 文件的 META-INF/MANIFEST.MF 文件中的属性。缺省情况下,此属性设置为 false,并且应用程序服务器使用新行为。

如果下列所有条件都成立,那么您可能会遇到 WSWS7054E 错误消息:
  • Web Service 应用程序由未附注释的方法组成。
  • 这些方法并不会映射到 Web Service 操作。
  • 应用程序没有引用 SEI,也没有将 WSDL 文件打包。
错误消息包含类似以下文本的信息:
javax.xml.ws.WebServiceException: WSWS7054E:
 The Web Services Description Language (WSDL) file could not be generated for the XXXX Web service implementation
 class because of the following error: javax.xml.ws.WebServiceException: Unable to create JAXBContext
JAX-WS 工具在 @WebMethod 映射原理方面符合 JAX-WS 规范。此更改可能会影响依赖于先前不符合缺省行为的应用程序。如果应用程序对 WSDL 或 SEI 进行打包和引用,并且在 SEI 实现中使用 @WebMethod exclude 标志来对所有方法进行了正确的注释,那么此更改对您没有影响。但是,如果您受到影响,请在方法中添加显式注释以确保将方法排除在 WSDL 生成之外。例如:@WebMethod(exclude=true)。此外,您还可以将 WSDL 与应用程序一起打包,这样就不需要运行时代表您生成 WSDL。
用于公开 static 和 final 方法的行为更改:

服务中没有显式 SEI 的 static 或 final 方法不再公开为 Web Service 操作。要将这些方法公开,请将 WSDL 与应用程序一起打包,并设置 jaxws.runtime.legacyWebMethod=true

过程

  1. 确定要公开为 Web Service 操作的方法。
  2. 查看将方法公开为类(使用 @WebService 注释进行注释)上的操作的规则。
  3. 使用在没有 SEI 的应用程序中应用 @WebMethod 和 @WebService 注释的最佳实践,将方法相应地公开为 Web Service 中的操作。

结果

已使用 @WebMethod 注释来指定要公开为 Web Service 操作的方法。

避免故障 避免故障:

如果已升级应用程序服务器环境,但遇到问题,请复审下列故障诊断信息。

使用 JAX-WS 工具 V2.1.6 或更高版本环境时客户机错误指示 WSDL 文件和 portType 不匹配
可能会收到类似如下消息的客户端错误消息:
javax.xml.ws.WebServiceException: The Endpoint validation failed to validate due to the following errors:
:: Invalid Endpoint Interface ::
:: The number of operations in the WSDL portType does not match the number of methods in the SEI or web service
 implementation class.  wsdl operations = [...] dispatch operations = [....]

要更正此问题,必须重新生成客户机工件以匹配 WSDL 文件。

最佳实践 最佳实践: 确保只要收到已更新的 WSDL 文件,就重新生成客户端工件。bprac
对 Web Service 执行 ?WSDL 操作的客户机具有不可分派的操作
在执行 ?WSDL 操作之后,您可能会收到包含的操作多于 JAX-WS 运行时环境可以分派的操作的 WSDL 文件。如果客户机尝试调用任何不可分派的操作,那么客户机会收到类似如下消息的错误:
The endpoint reference (EPR) for the Operation not found is http://localhost:9086/example/BeanImpl2Service and the WSA 
Action = <WSA_action_from_server>. If this EPR was previously reachable, contact the server administrator.
客户机只能访问 Web Service 要公开的操作。可以通过下列其中一种方法来更正此问题:
  • 修改 Web Service 应用程序中的 @WebMethod 注释,以便产生的 WSDL 文件公开正确的操作集。
  • jaxws.runtime.legacyWebMethod 属性设置为 false 以确保会分派 WSDL 中的所有操作。
gotcha

指示主题类型的图标 任务主题



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