使用 IBM SOAP 运行时环境创建 Web Service

此运行时环境是 WebSphere® Studio 的前发行版(版本 5.0 和更早版本)中支持的唯一 Web Service 运行时环境。此运行时环境支持 Apache SOAP 2.3。只应将它用于向后兼容性。

局限性

下面列示了将 IBM® SOAP 运行时环境与 Web Service 一起使用时的局限性。有关局限性的完整列表,请参阅局限性

  • IBM SOAP 运行时环境的互操作性
    • 如果按缺省情况不启用“启用基于元素的映射”首选项(可以在窗口 > 首选项 > Web Service > 代码生成中找到此首选项),则 Apache/IBM SOAP 运行时环境不会与其他供应商的 Web Service 运行时环境(该环境发送其元素没有“xsi:type”属性的消息)互操作。要了解更多信息,请参阅设置 Web Service 首选项
    • 当以返回“映射”数组或“散列表”数组的服务 bean 开始并启用了“基于元素的映射”选项时,生成的“SOAP 代理”将不正确地把返回类型映射至 java.lang.String[]。在运行时将发生 ClassCastException。要解决此问题,用最近创建的 WSDL 运行 Web Service 客户机向导并将 SOAP 代理重新生成到客户机项目中。
  • 自底向上的 Web Service 开发
    • 在使用 Web Service 向导从 Java™ 自底向上创建 IBM SOAP 2.2 Web Service 之后,可能会显示这样一条消息:Duplicate key value [...] declared for identity constraint of element "definitions".当 IBM SOAP 2.2 的工具生成具有相同 targetNamespace 的两个 WSDL 文件时(一个 WSDL 文件导入另一个 WSDL 文件),就会发生这种情况。
    • Java bean 属性必须同时具有 getter 和 setter,以便作为使用 IBM SOAP 运行时环境的 Web Service 正常工作。如果不具有所有 getter 和 setter,则属性可能不会生成到模式中,从而导致运行时序列化和客户机生成问题。确保所有属性都包含 getter 和 setter。
    • charjava.lang.Character 要求您输入定制映射,因为从 charjava.lang.Character 至 WSDL XSD 的缺省映射不存在。
    • 在服务 bean 的所有输入参数中,基本包装器类型 java.lang.Booleanjava.lang.Bytejava.lang.Shortjava.lang.Integerjava.lang.Longjava.lang.Floatjava.lang.Double 不能与它们相应的单个基本类型 booleanbyteshortintlongfloatdouble 共存。例如,将 java.lang.Integerint 同时作为输入参数类型的服务 bean 不能转换为完整的 Web Service。当尝试使用 Web Service 向导来从此类型的服务 bean 创建 Web Service 时,除非未在该向导的“Web Service Java Bean 方法”页面上选择包含基本类型或包装器类型的方法,否则将显示警告消息。但是,必须确保在第一次遇到“Web Service Java Bean 方法”页面时,未选择这些方法。在看到警告后返回到此页面并清除存在问题的方法可能会产生不完整的 Web Service。在这种情况下,应重新启动向导,以便可以在第一次遇到“Web Service Java Bean 方法”页面时进行正确的方法选择。
    • 不支持多维数组。Java 中的备用方法是在各维之间插入 Java bean。例如,模式 MyArray[](其中 MyArray 具有类型为 MyType[] 的属性)而不是 MyType[][] 将起作用。
    • 具有包含 DOM 元素和简单 bean 类型混合的输入参数列表的方法需要一个或多个定制映射的条目。“Web 服务定义语言”(WSDL)版本 1.1 规范对于所有输入部件(参数)都支持一种编码样式。“简单对象访问协议”(SOAP)版本 2.2 运行时环境不具有对带有文字 XML 编码的基本类型和 bean 的 SOAP 编码的“DOM 元素”的缺省映射支持。
    • 在配置定制映射时,如果尝试使用来自 SOAP 运行时环境的序列化器和反序列化器类(即,来自包 org.apache.soap.encoding.soapenc 的类)并接收到错误“不能从此项目装入选择的序列化器/反序列化器类”,则 soap.jar 很可能不在 Web 项目构建路径上。要更正该问题,取消向导,使用“Web 项目属性”对话框来将 WS_installdir\wstools\eclipse\plugins\com.ibm.etools.webservice\run-time environment\soap.jar 添加至 Web 项目的构建路径,然后重试 Web Service 向导。
    • 对于嵌套的复杂类型,不支持定制映射。尽管嵌套类型将出现在向导的映射页上,但是这些类型的定制映射将被忽略。
    • 当从 Java 类(其接口包含抽象 Java 类型)创建 Web Service 时,Web Service Java 至 XML 映射页可能会不正确地将该抽象类型的反序列化器字段设置为 org.apache.soap.encoding.soapenc.BeanSerializer。这在运行时环境中将会失败,因为 BeanSerializer 类中的反序列化器代码将不能构造该抽象类型的实例。为了避免此问题,必要时选择类型的“定制映射”选项并将反序列化器字段更改为用来编写反序列化抽象类型的类的名称。
    • Web Service 工具当前不支持从包含嵌套内部类(即,在顶级类内定义的内部类)的 Java Bean 创建 Web Service。要解决此问题,应将内部类移至单独的 Java 文件中的顶级类。
    • 当从 Java bean(它使用其它具有属性类型 Vector、Hashtable 或 Map 的 Java Bean)创建 Web Service 时,将从名称空间“http://xml.apache.org/xml-soap”生成具有包含类型“Vector”和“Map”的 complexTypes 的 XSD。因为此名称空间当前没有模式,所以“XSD 验证器”将生成错误和警告,如下所示:
      • src 解析错误:不能将名称“xsd2:Vector”解析为类型定义组件。
      • 警告 src-import.0:无法读取导入的模式文档“null”。
      这些错误和警告不会干扰 Web Service 向导对 WSDL 和 XSD 的正确处理。将把“Map”和“Vector”类型正确地映射至它们的 Java 对应项。注意,其它供应商在处理包含这些类型的 WSDL 或 XSD 时可能会遇到困难,因为 http://xml.apache.org/xml-soap 不是 WSDL 1.1 或 SOAP 1.1 规范可识别的名称空间。为了提高互操作性,考虑使 Java 收集类与数组和 bean 相适应,然后从适配器构建 Web Service。
  • 自顶向下的 Web Service 开发
    • 支持将限于每个 inputoutput 元素一个部件。不支持一个输入或输出消息中有多个逻辑部件。将处理第一个这样的部件并且将忽略其余的部件。
    • 当从使用类型 base64Binary(它来自 xsd(http://www.w3.org/2001/XMLSchema)名称空间)的 WSDL 生成 Web Service 框架或代理时,Web Service 运行时环境实际上将使用来自 soapenc(http://schemas.xmlsoap.org/soap/encoding/)名称空间的 xsi:type base64。通常,这两种类型可自由互换。但是,消息中的类型与模式中的类型之间的差别可能会导致某些 SOAP 协议运行时环境拒绝消息。如果出现这种情况,可以手工制作类似于 Apache SOAP 的 Base64Serializer 的序列化器,但是它将为 xsd:base64binary 而不是 soapenc:base64。
    • 如果 Java bean 框架是从包含不是有效 Java 标识的操作和部件名称的 WSDL 文档创建的,则不会编译它们。WSDL 操作和部件名称必须是有效的 Java 标识才能成功创建 Java bean 框架。
    • 缺省情况下,当生成 WSDL 时,Web Service 向导使用“http”URI,但是来自其它工具的一些 WSDL 文档可能偶然会使用一些使用除“http”之外的方案(例如,“urn”)的 Web Service、“SOAP 操作”或“目标名称空间”URI。当从包含非 http URI 的 WSDL 生成代理或框架时,Web Service 向导可能会将这些 URI 映射至 Java 包“com.example”而不是映射至更有意义的包。在某些情况下,Web Service 向导可能无法彻底处理这些 URI 并且将生成错误“IWAB0234E 发生了内部错误”。
    • 当从 WSDL 生成 Java 代理和 Java 框架时,可以选择将 XSD 本征类型 boolean、byte、short、int、long、float 和 double 映射至“java.lang”包装器类型(例如,java.lang.Integer),而不是映射至 Java 基本类型(例如,int)。缺省情况下,Web Service 向导将映射至 Java 基本类型。相反,要使向导映射至“java.lang”包装器类,打开窗口 > 首选项 > Web Service > 代码生成并选择“将简单 XML 数据类型映射至 java.lang 包装器类”。
    • 当从 Java bean 或 EJB 创建 Web Service 时,如果指定从 Java 类型至 XSD 类型的定制映射,则 Bean 类字段会被自动设置为 Java 类型的全名并且不能编辑它。当定制映射 Java 数组时,Bean 类名将使用数组格式,例如,“java.lang.String[]”,并且将以此格式发送到“.isd”和“dds.xml”部署描述符文件中。SOAP 运行时环境不能正确处理此格式的类名,从而将导致类似如下的错误:

      SOAP 服务 http://tempuri.org/webservice.AddressBook 中发生部署错误:类名 java.lang.String[] 未能解析:java.lang.String[]

      因此,不能定制服务端上 Java 数组的序列化器的映射。部分变通方法是对于定制映射,使序列化器类字段保持空白。这将消除将数组类名生成到部署描述符中,从而使服务能够起作用。注意,反序列化器类以及定制反序列化器的映射不受此问题和变通方法的影响。

  • 运行时注意事项
    • 如果选择 Web Service 代码生成首选项“启用基于元素的映射”并且选择了部署到 WebSphere Application Server V4,则在 ISD 文件和 dds.xml 中可能会有以下条目:

      <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:x="" qname="x:some-name" xml2JavaClassName="some-serializer"/>

      XML 编辑器可能会标记以下错误:

      The value of the attribute "xmlns:x" is invalid.  Prefixed namespace bindings may not be empty.

      此错误对于 WebSphere Application Server V4 是无害的。然而,不要尝试将此 dds.xml 部署到使用 Xerces 2.x (XML4J 4.x) 或更高版本(例如,WebSphere Application Server V5)的其它服务器。否则,在服务器装入 dds.xml 文件时将会产生类似的 Xerces 解析错误。应通过完成 Web Service 方案并选择正确的服务器类型来重新生成 dds.xml。这将为该服务器类型生成正确的 dds.xml。

      另外,当尝试从该 ISD 文件部署 Web Service 时也会产生类似的 Xerces 解析错误。变通方法是手工将该文件编辑为以下格式:

      <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" qname="some-name" xml2JavaClassName="some-serializer"/>

    • 当调用从 Java bean 或 EJB 创建的 Web Service 时,如果收到具有 targetException 的 SOAPException,如:“java.lang.IllegalArgumentException: 无法实例化 ...” 产生该问题的原因可能是:作为 Web Service 的方法包含不具有公用缺省构造函数作为参数和/或返回类型的 Java bean。需要公用缺省构造函数以便 SOAP 运行时环境将对象构造为反序列化过程的一部分。
    • 当前部署到 Web 项目中的安全性文件 cl-ver-config.xml 和 sv-ver-config.xml 是来自 WebSphere V4.0 的文件并且不与 DTD 精确匹配。但是这些文件在 WebSphere V4.0 和 WebSphere V5.0 上都能工作,尽管验证错误说明必须声明“xmlns:ds”或“xmlns:SOAP-SEC”。
    • 如果创建使用同一个包中两个不同的复杂类型的 bean,则在从此 bean 创建基于 SOAP 的 Web Service 时,将为每个复杂类型创建 XSD 文件并且将给予它们相同的名称空间。这会导致在“任务列表”和“Web Service 资源管理器”中产生验证错误。
  • ISD Web Service
    • 当创建 Java 或 EJB Web Service 时,在填写了定制映射后,将把定制映射信息(XSD 位置 URL 除外)存储在 ISD 文件中。当从该 ISD 文件创建 Web Service 时,就会检索该信息。因此,当从 ISD 文件创建 Web Service 时,在向导的 Web Service Java 至 XML 映射页中,需要手工填写 XSD 位置 URL。
使用条款 | 反馈
(C) Copyright IBM Corporation 1999, 2005. All Rights Reserved.