![]() | China![]() |
|
IBM 主页 | 产品与服务 | 支持与下载 | 个性化服务 |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
|
![]() | ||||
![]() | Web Services for J2EE,版本 1.0 | ![]() | ![]() | |
![]() | ||||
![]() |
![]() |
草案版本 0.91 — 2002 年 8 月 19 日
Copyright© 2002 International Business Machines Corporation Copyright© 声明 Copyright© 本规范受版权法保护,此处描述的信息可能受一项或多项美国专利权、外国专利权或正在申请的专利权的保护。除按照以下许可证提供的方式外,未经 Specification Lead 及其许可证颁发者(如果有的话)事先书面授权,本规范的任何部分均不得通过任何手段以任何形式复制。对本规范和此处描述的信息的任何使用均受本许可证中的条款和条件、Specification Lead web 站点中陈述的法律术语以及任何适用的出口控制法律和条例的制约。一旦查看、下载或以其它形式复制本规范,即表示您已经阅读过并理解了此处陈述的条款和条件,并同意遵守这些条款和条件。 Copyright© 受本许可证中的条款和条件的制约,Specification Lead 按此方式颁发给您付讫的、非独占的、不可转让的、世界范围内的、有限的许可证(没有颁发从属许可证的权利),您可以行使 Specification Lead 知识产权权利,出于评估的目的在内部审阅本规范。除本有限的许可证外,您不享有对本规范或 Specification Lead 的任何其它知识产权的任何权利、所有权或权益。本规范包含 Specification Lead 的专利和证书信息,使用这些信息时必须遵守此处陈述的许可证条款。本许可证将自上面列出的发布日期起九十(90)天后过期,并且如果您未遵守本许可证的任何条款,许可证将立即终止而无须 Specification Lead 的通知。一旦终止,您就必须停止使用或销毁本规范。 Copyright© 商标 Copyright© 按照此许可证,您未被授予对 Sun 或 Sun 的许可证颁发者、Specification Lead 或 Specification Lead 许可证颁发者的任何商标、服务标志或商标名的任何权利、所有权或权益。Sun、Sun Microsystems、Sun 徽标、Java 和 Java 咖啡杯徽标是 Sun Microsystems, Inc. 在美国和其它国家或地区的商标或注册商标。IBM 和 IBM 八横条徽标是国际商业机器公司在美国和/或其它国家或地区的商标或注册商标。其它公司、产品和服务名称可能是其它公司的商标或服务标志。 Copyright© 免责声明 Copyright© 本规范以“按现状”的基础提供,是试验性的,并且可能包含有 SPECIFICATION LEAD 无法纠正或将不进行纠正的不足或缺点。SPECIFICATION LEAD 不作任何表示或保证(无论是明示的还是默示的),包括(但不限于)适销性保证、适用于某特定用途、对本规范的内容适用于任何用途的非侵权性、或对这些内容的任何实践或实现不会侵犯任何第三方的专利权、版权、商业秘密或其它权利的非侵权性。本文档不代表对在任何产品中发行或实现本规范中的任何部分的任何承诺。 Copyright© 本规范中可能包含技术方面不够准确的地方或印刷错误。此处的信息将定期更改;这些更改将编入本规范的新版本(如果有的话)中。SPECIFICATION LEAD 可以随时对本规范中描述的产品和/或程序进行改进和/或更改。对本规范中的这些更改的任何使用将受本规范的适用版本的当时和现在的许可证的制约。 Copyright© 豁免条款 Copyright© 对于法律未禁止的内容,在任何情况下,SPECIFICATION LEAD 或它的许可证颁发者都不对任何损害负责,包括不加限制、收入损失、利润损失、数据丢失、或者特殊的、间接的、有连带关系的、意外的或惩罚性的损害,不管这类损害是如何引起的,不管根据什么责任理论,也不管这类损害是由提供、实践、修改或以任何方式使用本规范造成的或与此有关,即使 SPECIFICATION LEAD 和/或它的许可证颁发者已经提醒过可能发生这类损害也不负责。 Copyright© 在将本规范用于内部评估之外的其它任何用途时,您将保护、不损害 Specification Lead 和它的许可证颁发者的权益,并赔偿根据您的使用提出的任何索赔,任何规范的以后版本或发行版向您提出的与据此许可证提供的本规范所提出的任何不同索赔,您也要赔偿。 Copyright© 限制权利说明 Copyright© 如果美国政府或代表美国政府的方面、或美国政府的主承包方或分包方(任何层次的)要获得本软件,则政府对本软件及其附属文档的权利应是本许可证唯一陈述的;这符合 48 C.F.R. 227.7201 至 227.7202-4(针对国防部(Department of Defense,DoD)先决权)和 48 C.F.R. 2.101 至 12.212(针对非国防部(non-DoD)先决权)的规定。 Copyright© 报告 Copyright© 您可能希望报告您可能会发现的与您对本规范的评估有关的任何岐义、不一致或不准确问题(“反馈”)。在您给 Specification Lead 提供任何反馈时,您作以下保证:(i)同意以非专利和非机密的基础提供这些反馈,(ii)颁发给 Specification Lead 无限期的、非独占的、世界范围内的、付讫的、不可收回的许可证,Specification Lead 有权向多级别的从属许可证方颁发从属许可证,可以出于与本规范及其未来版本、实现和测试套件有关的任何目的将您的反馈编入、公开和无限制地使用。 摘要JSR109,即 Web Services for J2EE 定义了在 J2EE 1.3 或 J2EE 1.4 应用程序服务器中如何支持 Web 服务。具体地说,Web Services for J2EE 定义了客户机模型、部署模型和运行时模型,从而使 Web 服务客户机和实现可以从一个 J2EE 供应商实现移植到另一个 J2EE 供应商实现。Web Services for J2EE 基于 JAX-RPC(JSR101)进行构建,以提供客户机编程模型。该客户机模型允许 Web 服务客户机(Java 的或非 Java 的,在 J2EE 之中或在 J2EE 之外)访问部署在支持 JSR109 的 J2EE 应用程序服务器中的 Web 服务。它还允许 J2EE 组件通过使用 J2EE 编程模型调用 Web 服务(Java 的或非 Java 的,在 J2EE 之中或在 J2EE 之外)。WebServices for J2EE 部署模型定义了 WSDL 文档的处理方法和 WSDL 文档的服务和 XML 信息模型到 J2EE 组件的映射,包括 EJB 容器中的无状态会话 Bean 和 Servlet 容器中的 Servlet 和 JAX-RPC 端点。它还定义了对 JAX-RPC 处理程序的部署和运行时支持。Web Services for J2EE 还通过定义 J2EE 应用程序服务器应如何使 WSDL 文档可以通过 URL 获得定义了对服务发布的支持。为您的 Web 服务支持与 J2EE 应用程序服务器一起使用 JSR109 能确保您 Web 服务实现和客户机的可移植性。 本文档的状态提议的最终草案 本文档是 JSR 109 的公开最终草案版本。它处于 JSR 规范在 Java 社区过程(Java Community Process)中的倒数第二个阶段。这表明 specification lead 和专家组认为该草案已经完成。对提议的最终草案的修订根据在创建参考实现(Reference Implementation)和技术兼容性工具(Technology Compatibility Kit,TCK)时出现的问题进行。本文档不是 JSR 109 规范的最终发行版。当本文档、参考实现和技术兼容性工具都完成时,本规范才会成为最终发行版。 目录1. 前言 1. 前言本规范定义了 Web Services for J2EE 体系结构。这个服务体系结构利用 J2EE 组件体系结构提供了一种客户机和服务器编程模式(可在应用程序服务器之间移植,并可在服务器间进行互操作),从而提供了一种可伸缩的安全环境,但仍然为 J2EE 开发者所熟知。 1.1. 目标读者此规范旨在由以下读者使用:
此规范假定其读者熟悉 J2EE 平台和规范。它还假定读者熟悉 Web 服务,尤其是 [JAX-RPC] 规范和 WSDL 文档。 1.2. 致谢此规范的原始思想建立在 IBM 成员 Donald F. Ferguson 的设想之上。它经过了业界范围内的专家小组的修正。专家小组的成员包括来自以下公司的积极的代表:IBM、Sun、Oracle、BEA、Sonic Software、SAP、HP、Silverstream 和 IONA。我们要感谢这些公司以及 JSR 109 专家小组的其它成员:EDS、Macromedia、Interwoven、Rational Software、Developmentor、interKeel、Borland、Cisco Systems、ATG、WebGain、Sybase、Motorola 和 WebMethods。 JSR 109 专家小组必须与其它 JSR 专家小组达成一致,从而为 Web Service for J2EE 定义一个一致的编程模型。我们特别要感谢 Rahul Sharma 和 JSR 101(JAX-RPC)专家小组、Farukh Najmi 和 JSR 093(JAX-R)专家小组,还有 Linda G. DeMichiel 和 JSR 153(EJB 2.1)专家小组。 1.3. 规范结构此规范的下面两章内容概括了 J2EE 环境中的 Web 服务支持的需求及概念性体系结构。J2EE 中的 Web 服务的每个主要的集成点,如客户机模型、服务器模型、部署模型、WSDL 绑定以及安全,都有自己的章节。其中每一章都由两个主题构成:概念和规范。概念部分将讨论如何使用 Web 服务、相关问题、注意事项以及支持的情况。规范部分具有标准的形式,定义了该规范的实现者必须支持什么。 1.4. 文档约定为了一致起见,此规范将沿用由 [EJB] 规范所使用的文档约定。 此规范中的说明性信息将用非固定字体表示。 包含描述性信息的段落(如描述典型应用的注释,或文本内容需要与说明性规范区分开来的注释)将使用这种表示强调的字体。 代码示例将使用这种固定字体。 本文当中的关键词“必须(MUST)”、“绝不可以(MUST NOT)”、“需要的(REQUIRED)”、“将(SHALL)”、“将不(SHALL NOT)”、“应该(SHOULD)”、“不应该(SHOULD NOT)”、“推荐(RECOMMENDED)”、“可以(MAY)”及“可选的(OPTIONAL)”的解释应依照 RFC 2119 中的描述。 2. 目标这一部分列出了此规范的高级目标。
本规范与 J2EE 1.4 之间的关系在 10.1. 附录 A. 与其它 Java 标准的关系中有所定义。 2.1. 客户机模型目标客户机编程模型应该与 JAX-RPC 所定义的客户机编程模型一致并兼容。 客户机编程模型的其它目标是要确保:
2.2. 服务开发目标服务开发模型定义了如何开发 Web 服务实现并将其部署到已有的 J2EE 容器中,包括下面几个特定的目标:
2.3. 服务部署目标
3. 概述3.1. Web 服务体系结构概述Web 服务是一种面向服务的体系结构,它能够创建服务的抽象定义、提供服务的具体实现、发布并查找服务、实现服务实例选择,并实现可互操作服务的使用。一般来讲,Web 服务实现以及客户机的使用可以按多种方式区分。客户机和服务器实现可以按编程模式区分。具体的实现可以按逻辑和传输区分。 服务提供者使用 Web 服务描述语言(Web Services Description Language,WSDL)来定义抽象的服务描述。然后,抽象的服务描述将用 WSDL 生成具体的服务描述,从而创建出具体的服务。接下来,具体的服务描述可以被发布到类似统一描述、发现和集成(Universal Description,Discovery and Integration,UDDI)这样的注册中心。服务请求者可以使用注册中心来找到服务描述,并根据服务描述选择和使用服务的具体实现。 抽象服务描述在 WSDL 文档中被定义为端口类型(PortType)。具体的服务实例是由端口类型、传输和编码绑定以及作为 WSDL 端口的地址共同定义的。多组端口聚集成一个 WSDL 服务。 3.2. Web 服务对于 Web 服务还没有被广泛接受的定义。由于撰写此规范的需要,我们将 Web 服务定义为具有以下特征的组件:
JAX-RPC 定义了从 WSDL 文档到 Java 的编程模型映射,该映射提供了一个工厂(服务)用来选择客户机希望使用哪个聚集的端口。请参阅图 2 的逻辑图表。一般来讲,传输、编码和端口的地址在客户机看来都是可见的。客户机只需在服务器端点接口(Service Endpoint Interface)上按照 JAX-RPC 定义的方式(也就是端口类型)调用方法来访问服务即可。请参阅第 4 章 客户机编程模型了解更多细节。 3.3. Web Services for J2EE 概述Web Services for J2EE 规范定义了所需的体系结构关系,如图 3 所示。它是一种逻辑关系,对容器提供者结构化容器和过程没有任何需求。添加到 J2EE 平台的内容包括依赖于由 Web 和 EJB 容器提供的容器功能的端口组件,还有 SOAP/HTTP 传输。 Web Services for J2EE 需要端口能够从客户机、Web 和 EJB 容器引用。本规范不需要端口能够从 applet 容器进行访问。 本规范给那些由 JAX-RPC 定义的、用来实现 Web 服务容器添加了额外的构件:基于角色的开发方法学、可移植的打包和 J2EE 容器服务对 Web 服务的体系结构。这些将在后面的章节中描述。 3.4. 平台角色本规范定义了已有的 J2EE 平台角色的职责。本规范没有定义新的角色。对于本规范中使用的 Web Services for J2EE 来说有两个特定的角色,不过它们可以被映射到已有的 J2EE 平台角色上。Web Services for J2EE 产品提供者角色可以被映射到 J2EE 产品提供者角色上,Web 服务容器提供者角色可以被映射到 J2EE 规范中的容器提供者角色上。 一般来讲,开发者角色负责服务定义、实现以及 J2EE 模块中的打包。装配者角色负责将模块装配成应用程序,部署者角色负责发布部署后的服务并将客户机引用解析为服务。您可以在后面的章节中找到更多有关角色职责的细节描述。 3.5. 可移植性标准的打包格式、声明性的部署模型以及标准的运行时服务为使用 Web 服务开发的应用程序提供了可移植性。标准的 J2EE 模块中所包含的特定于 Web 服务的部署描述符定义了针对这种模块的 Web 服务应用。您可以在后面的章节中找到关于 Web 服务部署描述符的更多细节描述。根据本规范,为了能够部署打包后的应用程序,您需要支持 Web Services for J2EE 的部署工具。 Web 服务容器提供者可以在牺牲一定的应用程序可移植性的前提下,为其它服务实现以及其它传输和编码绑定提供支持。 3.7. 互操作性本规范定义了在 J2EE(TM)之上实现本规范的产品的互操作性需求,从而扩展 J2EE 平台的互操作性需求。互操作性需求依赖于本规范所依据的已有标准的互操作性。 本规范建立在以下 JSR 和规范的不断发展基础之上:
3.8. 作用域3.9. Web 服务客户机视图Web 服务客户机视图与 Enterprise JavaBean 的客户机视图非常相似。Web 服务的客户机可以是另一个 Web 服务、一个 J2EE 组件(包括 J2EE 应用程序客户机),或任意的 Java 应用程序。非 Java 应用程序或非 Web Services for J2EE 应用程序也可以充当 Web 服务客户机,但这种应用程序的客户机视图不在本规范的讨论之列。 Web 服务客户机视图可以是远程的,它提供了本地-远程(local-remote)的透明性。 端口(Port)提供者和容器共同提供了 Web 服务客户机视图。它包括以下两种接口:
JAX-RPC 处理程序接口被认为是容器 SPI,因此不是客户机视图的一部分。 服务接口(Service Interface)定义了客户机可以用来访问 Web 服务的端口的方法。客户机并不创建或删除端口。它使用服务接口来获取对端口的访问权。服务接口由 [JAX-RPC] 规范定义,但其行为由 Web 服务提供者所提供的 WSDL 文档来定义。容器的部署工具提供服务接口或 JAX-RPC 生成的服务接口的方法的实现。 客户机通过使用 JNDI API 来查找服务接口。这在第 4 章 客户机编程模型中有进一步的解释。Web 服务是由客户机通过使用服务端点接口来访问的。服务端点接口由服务提供者指定。部署工具和容器运行时提供服务器端类,它将向 Web 服务实现分派一个 SOAP 请求,后者将实现服务端点接口的方法。服务端点接口将扩展 端口在客户机视图中没有任何标识,它可以被认为是无状态对象。 3.10. Web 服务服务器视图第 5 章 服务器编程模型定义了服务器编程模型的细节问题。这一部分定义了服务提供者的一般需求。 服务提供者定义了 WSDL 端口类型、WSDL 绑定,以及 Web 服务的服务端点接口。端口类型和服务端点接口必须遵循 JAX-RPC 中的规则,才能进行从 WSDL 到 Java 以及从 Java 到 WSDL 的映射。 服务提供者在 WSDL 文档中定义了 WSDL 服务和端口聚集。 服务提供者用下面两种方式之一实现 Web 服务的业务逻辑:
Web 服务生命周期管理与服务实现方法有关。 服务提供者实现特定于所使用的服务实现方法的容器回调方法。请参阅 [JAX-RPC] 规范和 Enterprise JavaBean 规范以了解关于容器回调方法的详细内容。 容器管理 Web 服务所需的运行时服务,如安全性服务。Web 服务不会在全局事务上下文中执行。如果客户机用事务上下文访问端口,那么在端口被访问前上下文就会被暂挂。 服务提供者必须避免妨碍容器操作的编程习惯。这些限制是由 J2EE 1.3、Servlet 2.3 和 [EJB] 规范定义的。 打包 J2EE 模块中的 Web 服务与服务实现方法有关,但遵循 J2EE 对 EJB-JAR 文件或 WAR 文件的需求。它包含服务端点接口的 Java 类文件以及 Web 服务的 WSDL 文档。另外,它包含一个 XML 部署描述符,用来定义 Web 服务端口和它们的结构。打包需求在第 5.4 节 打包中描述。 4. 客户机编程模型本章描述了 Web Services for J2EE 的客户机编程模型。一般来说,客户机编程模型在 [JAX-RPC] 规范中有详细的描述。本规范讨论了 J2EE 环境中 JAX-RPC 客户机编程模型的使用。 本规范和 [JAX-RPC] 规范之间的区别将用这形式指出。 4.1. 概念Web 服务客户机不局限在本规范所定义的客户机,然而本规范并没有特别强调非 Web Services for J2EE 客户机的客户机编程模型。一般来说,Web 服务的 WSDL 定义为非 Web Services for J2EE 客户机的构建和运行提供了足够的信息,但并没有定义它的编程模型。本章的其它部分讨论了 Web Services for J2EE 客户机的编程模型。它并不假定客户机调用的 Web 服务实现是由 Web Services for J2EE 运行时还是某个外部运行时托管的。 客户机使用 Web Services for J2EE 运行时来访问并调用 Web 服务的方法。客户机可以是以下任意一种:J2EE 应用程序客户机、Web 组件、EJB 组件和另外的 Web 服务。 Web 服务的客户机视图是代表客户机执行业务逻辑一组方法。客户机无法区分方法是本地执行还是远程执行的,也不能确定服务是如何实现的。最后,客户机必须假定 Web 服务的方法在多次 Web 服务方法调用中不具有持久的状态。客户机可以认为 Web 服务实现是无状态的。 按照 [JAX-RPC] 规范中所定义,客户机使用服务端点接口来访问 Web 服务。对 Web 服务实现的引用决不应传递到另一个对象上。客户机决不应直接访问 Web 服务实现。这样做将跳过可能会打开安全漏洞或导致反常行为的容器的请求处理。 按照 [JAX-RPC] 所定义,客户机使用 JNDI 查找来访问实现服务接口的服务(Service)对象。服务对象是由客户机用来获取实现服务端点接口的存根(stub)或代理的一个工厂。存根是 Web 服务实例的客户机表示。 按照 JAX-RPC 所定义,服务接口可以是普通的 客户机不能控制服务器上 Web 服务实现的生命周期。客户机并不创建或销毁 Web 服务实例(也就是我们所说的端口)。客户机只访问端口。端口的生命周期或者 Web 服务实现的实例是由托管 Web 服务的运行时管理的。端口没有标识。这就意味着,客户机不能将端口与其它端口相比较来确定它们是否相同或相符,客户机也不能访问特定的端口实例。如果在 Web 服务访问的过程中发生了崩溃或者重新启动,客户机无法确定服务器是否崩溃或者重新启动。 客户机开发者从服务端点接口和服务接口开始。开发者如何获得这些不在我们讨论之列,但我们要讨论 Web 服务提供者如何提供它们,或者如何使用工具从 Web 服务提供者提供的 WSDL 定义生成它们。这些工具根据 JAX-RPC 规则操作,以进行 WSDL 到 Java 的映射。客户机开发者不需要在开发期间生成存根,我们也不鼓励他们这样做。客户机应该使用接口,而不是存根。存根将在开发期间生成,特定于客户机运行所处的供应商运行时。 Web 服务的每个客户机 JNDI 查找都是通过一个逻辑名称进行的。客户机开发者选择客户机代码中要使用的逻辑名称,并将它在 Web 服务客户机部署描述符中随所需的服务接口一起声明。客户机应该使用接口,而不是存根。 服务接口方法可以分为两类:存根/代理和 DII。存根/代理方法提供了两种对端口进行访问的方法,一种是特定于服务(客户机需要 WSDL 信息)的,另一种是与服务无关的(不需 WSDL 信息)。DII 方法在客户机需要与 Web 服务进行动态的、不基于存根的通信时使用。 客户机可以使用服务接口的存根/代理方法来获取端口存根或动态代理。特定于 WSDL 的方法可以在客户机开发者能够得到服务的完整 WSDL 定义时使用。与 WSDL 无关的方法必须在客户机开发者只有部分 WSDL 定义(只包含端口类型和绑定)的情况下使用。 4.2. 规范4.2.1. 服务查找客户机开发者需要为 Web 服务定义一个逻辑的 JNDI 名称,这被称为服务引用。该名称在客户机的部署描述符中指定。我们推荐在一个 JNDI 名称空间的服务子上下文中对所有服务引用逻辑名称进行组织,但这不是必需的。容器必须使用服务引用的逻辑名称在客户机环境上下文 容器充当代表客户机的媒介,用来确保能够通过 JNDI 查找的方式得到服务接口。更明确的是,容器必须确保所需的服务接口的实现必须按照 Web 服务客户机部署描述符中的服务引用所规定的方式绑定到客户机所选择的 JNDI 名称空间中的一个位置。下面的代码片段可以更好地说明这一点: InitialContext ic = new InitialContext (); Service abf = (Service)ic.lookup( "java:comp/env/service/AddressBookService"); 在上面的示例中,容器必须确保一般的服务接口实现 javax.xml.rpc.Service 在 JNDI 名称空间中被绑定到开发者指定的位置。类似代码片段被用于访问实现生成的服务接口(如 AddressBookService)的对象。 InitialContext ic = new InitialContext (); AddressBookService abf = (AddressBookService)ic.lookup( "java:comp/env/service/AddressBookService"); J2EE 产品提供者需要在 Web、EJB 和应用程序客户机容器中提供服务查找支持。 4.2.2. 服务接口服务接口被客户机用来获取端口的存根或动态代理,或者DII Call 对象。容器提供者需要支持服务接口的所有方法(除了第 4.2.2.7 节和第 4.2.2.8 节中描述的 getHandlerRegistry() 和 getTypeMappingRegistry() 方法之外)。 客户机开发者必须在客户机部署描述符中说明应用程序使用的服务接口类型。 客户机可以使用下面的服务接口方法来获取 Web 服务的静态存根或动态代理: java.rmi.Remote getPort(QName portName, Class serviceEndpointInterface) throws ServiceException; java.rmi.Remote getPort(java.lang.Class serviceEndpointInterface) throws ServiceException; 客户机还可以使用生成的服务接口的其它方法来获取 Web 服务的静态存根或动态代理。 按照第 4.2.3 节 端口存根和动态代理中所描述,容器必须为这些方法提供至少一个静态存根或动态代理。容器必须确保存根或动态代理在返回到客户机之前被完全配置为由客户机使用。存根或动态代理由 容器提供者必须提供 客户机可以使用下面几种由客户机环境的 JNDI 查找找到的服务接口的 DII 方法来获取 Call 对象: Call createCall() throws ServiceException; Call createCall(QName portName) throws ServiceException; Call createCall(QName portName, String operationName) throws ServiceException; Call createCall(QName portName, QName operationName) throws ServiceException; Call[] getCalls(QName portName) throws ServiceException; DII Call 对象不一定能够根据用来获取它的方法被预先配置。请参阅 [JAX-RPC] 规范以了解详细内容。 Web Services for J2EE 产品中不支持 JAX-RPC 如果客户机部署描述符中给出了完整的 WSDL 描述以及 JAX-RPC 映射文件,那么客户机开发者就可以使用服务接口的所有方法(除了第 4.2.2.7 节和第 4.2.2.8 节中描述的情况之外)。WSDL 中可能没有端口地址属性,也可能是虚值。 如果客户机部署描述符中给出了部分 WSDL 定义,那么客户机开发者就可以使用下面服务接口方法。 Call createCall() throws ServiceException; java.rmi.Remote getPort(java.lang.Class serviceEndpointInterface) throws ServiceException; java.net.URL getWSDLDocumentLocation() 这里定义了一个不完整的 WSDL 定义,作为完全指定的 WSDL 文档,它不包括服务或端口元素。开发者所指定的 JAX-RPC 映射文件在这种情况下将不包括 如果服务接口的其它方法被调用,而开发者指定了部分的 WSDL 定义,那么容器就必须抛出 如果客户机部署描述符中没有指定 WSDL 定义,那么客户机开发者就可以使用下面的服务接口方法: Call createCall() throws ServiceException; 如果部署描述符中没有指定 如果服务接口的其它方法被调用,而开发者没有指定 WSDL 定义,那么容器就必须抛出 组件不应使用 组件不应使用 4.2.3. 端口存根和动态代理端口存根和动态代理是客户机的 Web 服务表示。与存根或代理进行通信的端口在客户机视图中没有标识。 尽管我们认为存根和动态类是远程(Remote)对象,但客户机并不需要使用 4.2.4. JAX_RPC 属性J2EE 容器环境改变了 JAX-RPC 中定义的支持存根/代理属性所需的条件。 容器提供者不需要支持下面 USERNAME_PROPERTY 以及 PASSWORD_PROPERTY — 客户机管理的凭证传播属性。 容器提供者不需要支持存根实现上的 USERNAME_PROPERTY 和 PASSWORD_PROPERTY 属性。容器提供者负责获取凭证信息并根据给定请求的认证需求将其传送到服务器。举例来说,当提交一条 HTTP 请求以访问 Web 服务,而服务器被配置为需要 HTTP Basic 认证时,那么容器就必须获取用户标识和密码,并将 HTTP 授权(Authorization)头添加到 HTTP 请求。在 HTTP 请求需要客户机证书的情况下,容器负责用共用的 SSL 建立 HTTPS 连接,方法是让底层 SSL 层能够访问客户机证书。 J2EE 1.3 规范的第 9.2 节描述了客户机能够用来以编程方式通过实现 SESSION_MAINTAIN_PROPERTY — 会话管理配置。 容器提供者不需要支持存根实现上的 SESSION_MAINTAIN_PROPERTY 属性。参与 HTTP 会话的容器管理和配置是特定于容器实现以及最终用户需求的。容器一般会为最终用户提供一种方法来选择是否希望参与 HTTP 会话,但对定义这一点没有标准要求。 参与 HTTP 会话特定于 JAX-RPC 服务端点模型,并不一定适合实现 Web 服务的会话 EJB 模型。如果客户机调用了需要参与 HTTP 会话的 Web 服务,而客户机被配置为不参与 HTTP 会话,那么它就会接收到错误。 ENDPOINT_ADDRESS_PROPERTY — 动态端点地址分配。 容器提供者需要支持 ENDPOINT_ADDRESS_PROPERTY,从而使组件能够动态地将存根/代理重定向至不同的 URI。 5. 服务器编程模型本章定义了 Web Services for J2EE 的服务器编程模型。WSDL 文档定义了 Web 服务的互操作性,其中包括传输和有线格式需求的规范。一般来讲,WSDL 对客户机或服务器的编程模型没有什么需求。Web Services for J2EE 定义了两种实现 Web 服务的方法。它需要基于 JAX-RPC Servlet 容器的 Java 类编程模型来实现在 Web 容器中运行的 Web 服务,还需要无状态会话 EJB 编程模型来实现在 EJB 容器中运行的 Web 服务。这两种实现方法提供了定义端口组件,从而将可移植应用程序引入 Web 服务编程范型的方法。本规范还要求开发者能够从简单做起,慢慢发展成为能够使用更复杂的服务质量。下面几节定义了端口组件的要求。 5.1. 目标端口组件旨在达到以下目标:
5.2. 概念端口组件(有时称为端口)定义了 Web 服务的服务器视图。每个端口都充当 WSDL 端口地址定义的一个位置。端口组件充当 WSDL 端口类型定义的操作请求。每个端口组件都有一个服务端点接口和一个服务实现 Bean。服务端点接口是 WSDL 端口类型的 Java 映射和与 WSDL 端口相关联的绑定。服务实现 Bean 根据端口部署所在的容器可能会有所不同,但一般来讲,它是实现服务端点接口定义的方法的 Java 类。WSDL 端口只在地址上有区别,被映射为单独的端口组件,每个都带有可能是唯一的但也许是共享的服务实现 Bean。图 5 在下面说明了这一点。 端口的生命周期与容器有关,而且完全由容器控制,但大体上与容器本身的生命周期相同。端口在 WSDL 端口地址接收到的第一个请求可以使用之前由容器创建并初始化。端口在容器认为必要的时候被容器销毁,比如在容器关闭的时候销毁。 端口的实现和它运行所在的容器是紧密相关的。JAX-RPC 服务实现 Bean 总是在 Web 容器中运行。EJB 服务实现类总是在 EJB 容器中运行。 端口组件将服务实现 Bean 与 WSDL 端口关联。一般来讲,端口组件将服务需求定义委托给 J2EE 组件的部署描述符。第 6.3 节 打包和第 7.3 节 JAX-RPC 映射部署描述符中将进一步讨论这个问题。容器为 WSDL 端口地址提供侦听器,并提供一种将请求分派到服务实现的方法。容器还向用于引用分布式对象和资源的物理映射提供运行时服务,如安全性约束和逻辑。 5.3. 端口组件模型规范端口组件定义了将 Web 服务变为可移植服务器应用程序的编程模型构件。端口组件与 WSDL 端口的关联提供了互操作性。编程模型构件包括:
开发者在 Web 服务部署描述符中声明端口组件。部署描述符包括描述端口类型和 Web 服务绑定的 WSDL 文档。部署者和部署工具将处理从端口到容器的映射。 5.3.1. 服务端点接口服务端点接口(Service Endpoint Interface,SEI)必须遵循 WSDL 和 Java 互映射的 JAX-RPC 规则。根据这些规则,SEI 与 WSDL 端口类型以及 WSDL 绑定有关。SEI 是部署工具和并行客户机开发需要使用的。端口组件开发者负责提供带有所定义的最少端口类型和绑定的 WSDL 文档以及 SEI,并负责保持两者之间的同步。 JAX-RPC 将 Holder 定义为不能序列化的类,它不能由 Enterprise JavaBean 的远程接口实现。因此,在 EJB 容器中部署的端口组件并不需要支持为了参数而使用 Holder 的 SEI。 5.3.2. 服务实现 Bean有两种方法可以实现服务实现 Bean。按照 [JAX-RPC] 规范的第 10 章所定义,其中包括无状态会话 EJB 和 JAX-RPC 服务端点。这两种编程模型在第 5.3.2.1 节和第 5.3.2.2 节中有完整的定义。 容器可以使用任何 bean 实例为请求提供服务。 无状态会话 Bean,如 [EJB] 规范的第 7.8 到 7.10 节中所定义,可以用来实现将在 EJB 容器中部署的 Web 服务。 无状态会话 Bean 不必担心多线程访问。EJB 容器需要通过服务实现 Bean 的任意实例来对请求流进行序列化。 这里将部分重复对创建服务实现 Bean 作为无状态会话 EJB 的要求。
目前,无状态会话 Bean 必须直接或间接地实现 该接口使容器能够在其状态中通知服务实现 Bean 即将发生的错误。Enterprise JavaBean 规范 2.0 的第 7.5.1 节中定义了该接口的全部需要。 [EJB] 规范的第 7.8.2 节定义了允许的容器服务访问要求。 已有的 Enterprise JavaBean 如果符合下面的要求,就可以作为服务实现 Bean 使用:
开发者必须按照第 5.4 节 打包中描述的方式打包 Web 服务,而且必须指定从 Web 服务部署描述符中的端口到已有 EJB 的 [JAX-RPC] 规范中使用的 JAX-RPC 服务端点一词有点令人迷惑,因为服务实现 Bean 都需要使用 JAX-RPC 运行时。然而,在这种情况下它指的是用来创建在 Web 容器中运行的 Web 服务的 [JAX-RPC] 规范中定义的编程模型。我们在这里重复这个要求,并加以澄清。对 JAX-RPC 定义的编程模型的改变是在 J2EE 容器管理的环境中运行所需要的。 JAX-RPC 服务端点可以是单线程,也可以是多线程的。我们在这里说明并发性要求是作为编程模型的一部分。如果组件需要单线程访问,JAX-RPC 服务端点就必须实现 服务实现 Bean 必须遵循 [JAX-RPC] 规范中概述的服务开发者要求,除非另行指出,否则以下面列出的为准。
5.3.2.2.1 可选的 ServiceLifecycle 接口 Web 容器的服务实现 Bean 可以实现 package javax.xml.rpc.server; public interface ServiceLifecycle { void init(Object context) throws ServiceException; void destroy(); }
容器在开始将请求分派到 bean 的 SEI 方法之前,必须调用 init 方法。容器所提供的 init 方法参数值由 [JAX-RPC] 规范描述。bean 可以使用容器通知来使其中间状态准备好接收请求。 容器必须让 bean 知道它将通过调用 容器根据服务实现 Bean 的生命周期状态提供特定服务。下表描述了可以在 bean 的各种方法中访问的服务。如果 bean 试图访问不允许访问的容器服务,就会抛出
5.3.3. 服务实现 Bean 生命周期服务实现 Bean 的生命周期由容器控制,如图 6 所示。容器调用的方法与容器/bean 有关,但一般来说是非常相似的。图 6 说明了 Web 容器中的生命周期。EJB 容器生命周期的描述可以在 [EJB] 规范的第 7.8.1 节中找到。 容器向 WSDL 端口所定义的请求提供服务。它通过为 WSDL 端口地址创建侦听器、接受请求并将请求分派到服务实现 Bean 上实现这一点。在能够服务于请求之前,容器必须实例化一个服务实现 Bean 并使之准备好接受方法请求。 容器准备 bean 实例的方法是:首先调用服务实现 Bean 类上的 newInstance 来创建实例。容器然后调用与容器有关的服务实现 Bean 上的生命周期方法。对 Web 容器来说,如果服务实现 Bean 类实现 服务实现 Bean 实例没有标识。 容器可以对服务实现 Bean 的方法就绪(method ready)的实例进行池化,并将方法请求分派到处于方法就绪状态的任何实例上。 容器通过调用实例上特定于容器/bean 的生命周期方法来通知服务实现 Bean 实例它将被从方法就绪状态删除。对于 Web 容器来说将调用 5.4. 打包端口组件可以被打包为 WAR 文件或者 EJB JAR 文件。打包成 WAR 文件的端口组件必须使用服务实现 Bean 的 JAX-RPC 服务端点。打包成 EJB-JAR 文件的端口组件必须使用服务实现 Bean 的无状态会话 Bean。 开发者要负责通过容器或引用的方式,对 WSDL 文件、服务端点接口类、生成的服务实现类(如果使用了该类)、它们相关的类、JAX-RPC 映射文件以及 J2EE 模块中的 Web 服务客户机部署描述符进行打包。模块中 Web 服务客户机部署描述符的位置与特定模块有关。WSDL 文件位于模块根结构的相对位置,而且一般与模块的部署描述符位于同一位置。映射(Mapping)文件位于模块根结构的相对位置,而且一般与模块的部署描述符位于同一位置。 5.4.1. EJB 模块打包无状态会话 EJB 服务实现 Bean 打包成包含类文件和 WSDL 文件的 EJB-JAR。打包规则遵循那些由 Enterprise JavaBean 规范定义的规则。另外,Web 服务部署描述符在 EJB-JAR 文件中的位置是 5.5. 事务服务实现 Bean 的方法在特定于容器的事务上下文中运行。Web 容器在未指定的事务上下文中运行方法。EJB 容器在 EJB 部署描述符的 6. 处理程序本章定义了 Web Services for J2EE 的处理程序编程模型。处理程序定义了应用程序用以访问请求的原始 SOAP 消息的方法。这种访问在客户机和服务器上都有提供。处理程序不是 WSDL 规范的一部分,因此并不在其讨论范围之内。请参阅第 6.3 节 打包以了解部署描述符中的处理程序的说明。[JAX-RPC] 规范在第 12 章定义了处理程序 API。该规范定义了 J2EE 环境中的处理程序应用。 6.1. 概念处理程序会让人联想到 Servlet 过滤程序,因为它是一种能够在 Web 服务组件处理请求之前检查并可能修改请求的业务逻辑。它还可以在组件处理请求之后,检查并可能修改响应。在请求被发送到远程主机之前和客户机收到响应之后,处理程序还可以在客户机上运行。 JAX-RPC 处理程序只特定于 SOAP 请求,不能被其它非 SOAP Web 服务使用。处理程序可以被独立传送。举例来说,JAX-RPC 定义的处理程序除了可以用于 SOAP/HTTP 之外,如果提供了 JMS 协议绑定,还可以用于 SOAP/JMS。非 SOAP 编码的处理程序还没有被定义。 处理程序是特定于服务的,因此与服务接口的特定 Port 组件或端口相关联。这种关联在第 7.1节 Web 服务部署描述符和第 7.2 节 Web服务客户机部署描述符中分别描述。它们以一种称为 HandlerChain 的有序方式进行,这种方式由部署描述符定义。 您可以在几种情况下考虑使用处理程序。其中包括特定于应用程序的 SOAP 头处理、日志纪录和高速缓存。还可能使用一种有限的加密形势。对特定于应用程序的 SOAP 头处理来说,客户机和服务器必须在不需要说明语义需求的 WSDL 定义的帮助下在头处理语义上达成一致,这非常重要。加密仅限于文档/文字绑定,其中 SOAP 消息部分将映射到 SOAPElement。在种情况下,只要对值的加密不会改变 SOAPElement 的结构,SOAPElement 中的值就可以被加密。 本规范不支持 [JAX-RPC] 规范中描述的某些处理程序情况。举例来说,审计就无法被完全支持,因为没有办法让处理程序获取 Principal。安全股票报价示例就无法按规定支持,因为对主体加密将使容器不能决定请求应该被定向到哪个 Port 组件,也就不能决定哪个处理程序应该对主体加密。 处理程序总是在应用程序逻辑的执行上下文中运行。在客户机端,存根/代理控制处理程序执行。客户机端处理程序在存根/代理组织消息后运行,不过要在容器服务和传输绑定发生之前运行。服务器端处理程序在容器服务(包括方法级别授权)运行之后运行,但要在分解 SOAP 消息并将 SOAP 消息分派到端点之前运行。处理程序可以访问 java:comp/env 上下文,以访问与处理程序关联的 Port 组件定义的资源和环境条目。 处理程序受 J2EE 受管环境的约束。处理程序不能将请求重新定位到不同的组件上。处理程序不能改变 WSDL 操作,也不能改变消息部件类型和部件数。在服务器上,处理程序只能与使用 MessageContext 的组件的业务逻辑通信。在客户机上,处理程序无法与客户机的业务逻辑通信。处理程序没有标准的方法能够访问与请求关联的安全标识,因此处理程序不能可移植地根据安全标识执行处理。 处理程序的生命周期由容器控制。 处理程序与服务器上的 Port 组件相关联,因此在 Web 和 EJB 容器两者中运行。本规范将 EJB 容器中的处理程序支持定义为可选的是因为所需的 EJB 容器发生了变化,而它是实现处理程序支持所必需的。希望将来的 J2EE 规范能够将 EJB 处理程序支持定义为必需的。 6.2. 规范这一节将定义在 Web Services for J2E 中运行的 JAX-RPC 处理程序的要求。[JAX-RPC] 规范的第 12 章定义了编程模型需要。本规范与 [JAX-RPC]规范之间的区别将在专门的段落中指出。 6.2.1. 适用情况处理程序必须能够支持以下几种情况: 第 1 种情况:处理程序必须能够转换 SOAP 头。一个例子是用处理程序添加特定于应用程序的信息(如 customerID)的 SOAP 头。 第 2 种情况:处理程序必须能够只转换主体的部件。这可能包括改变 SOAP 主体中的部件值。这种情况的例子是对某些参数值的加密。 第 3 种情况:处理程序必须能够只读取消息,而不对消息进行添加、转换或修改。常用的情况有日志纪录、测量和记帐。 6.2.2. 编程模型Web Services for J2EE 提供者需要提供下面的 javax.xml.rpc.handler 包的接口和类。
不需要提供 HandlerChain 接口。HandlerChain 的功能以特定于容器的方式提供。它不被应用程序代码使用。容器提供者不需要使用 HandlerChain 接口来实现链功能。
Web Services for J2EE 提供者需要提供 Web Services for J2EE 提供者需要提供 Web Services for J2EE 提供者需要提供 按照第 5.3.2.1 节 EJB 容器编程模型和第 5.3.2.2 节 Web 容器编程模型中所定义,Port 组件的编程模型可以是单线程的,也可以是多线程的。JAX-RPC 处理程序的并发性必须符合与其关联的业务逻辑的并发性。根据访问 Port 的不同业务逻辑,客户机处理程序可能需要支持多线程执行。 处理程序必须使用装入应用程序代码所使用的相同的类装入器来装入。类装入规则遵循为处理程序运行所在的容器定义的规则。 处理程序的生命周期由容器控制,图 7 中说明了它。 处理程序接口的 容器必须先调用 init 方法,然后才能够开始将请求分派给处理程序的 容器必须通知处理程序它想调用 正如 JAX-RPC 所定义的,从处理程序的任何方法抛出的 RuntimeException(不是 池化处理程序实例是允许的,但不是必须的。如果处理程序实例被池化,那么用端口组件池化它们。这是因为处理程序可以跨方法调用(这些方法调用特定于端口组件)保持特定于非客户机的状态。举例来说,处理程序可能会用特定于端口组件的环境变量值来初始化内部数据成员。当单个处理程序类型与多个端口组件关联时,这些值可能会不一致。端口组件的处理程序的任何处于方法就绪状态的池化后的实例都可以用来为 与一个端口组件关联的多个处理程序在授权之后,服务实现 bean 的业务逻辑方法被分派出去之前运行。对于 JAX-RPC 服务端点,处理程序在容器执行完与定义端口组件的 servlet 元素相关联的安全性约束检查之后运行。对于基于 EJB 的服务实现,处理程序在发生了方法级的授权之后运行。 处理器绝对不可以以任何会导致先前执行过的授权检查以不同方式执行的方式更改消息。 如果授权仅仅基于 MessageContext 和组件的环境变量值,那么处理程序可能会执行编程式授权检查。处理程序既不能执行基于角色的编程式授权检查,也不能访问与请求相关联的 Principal。 处理程序的 Java 2 安全性权限与运行该处理程序的容器所定义的权限相同。应用程序客户机、Web 和 EJB 容器可能具有不同的权限。如果提供者允许按每应用程序对权限进行定义,那么授予处理程序的权限由授予应用程序代码(该处理程序与这些代码包装在一起)的权限定义。请参阅 J2EE 1.3 规范的 J2EE.6.2.3 一节了解更多详情。 处理程序在未特别指定的事务上下文中运行。 处理程序通常和与事务有关的 Servlet 过滤器满足相同的要求。处理程序绝对不可以使用 6.2.3. 开发者职责不要求开发者实现处理程序。处理程序是编写与处理 Web 服务请求有关的业务逻辑的另一种手段。一个开发者可以实现零个或多个与 Port 组件和/或服务引用相关联的处理程序。如果一个开发者实现了一个处理程序,则它们都必须满足本节所概述的要求。 处理程序作为无状态实例实现。在处理(handle)方法的多个调用之间,处理程序不在它的实例变量中维护任何与消息处理(特定于客户机的)有关的状态。 处理程序类必须实现 java.xml.rpc.handler.Handler 接口。 Handler.handleXXX() 方法可以使用“java:comp/env”上下文的 JNDI 查找,并且可以通过执行 JNDI 查找访问部署描述符中定义的 Handler.init() 方法必须保持 HandlerInfo.getHeaders() 所定义的信息。 处理程序实现必须实现 getHeaders() 方法以返回 HandlerInfo.getHeaders() 方法的结果。处理程序声明它将处理的头(即那些由 Handler.getHeaders() 方法返回的东西)必须在服务的 WSDL 定义中进行定义。 处理程序实现应该测试传递到处理程序的在 handle<action>() 方法中传递到处理程序的 MessageContext 的类型。尽管本规范只要求支持 SOAP 消息,并且容器在这种情况下将传递 SOAPMessageContext,但有些提供者可能会提供一些使其它消息类型和 MessageContext 类型可以被使用的扩展。处理程序实现应该为接受并忽略它不理解的消息类型做好准备。 处理程序实现必须使用 MessageContext 来把信息传递到同一条处理程序链中的其它处理程序实现,对于 JAX-RPC 服务端点的情况,则传递到服务实现 Bean。不要求容器使用同一个线程来调用每一个处理程序或调用 Service Implementation Bean。 处理程序可以访问完整的 SOAP 消息,并且如果 handle<action>() 方法传递了 SOAPMessageContext,则处理程序也可以处理 SOAP 头块和主体。 SOAPMessageContext 处理程序可以添加或删除 SOAP 消息的头。如果 SOAP 消息的头未被映射到参数上,或者如果 SOAP 消息的头被映射到了参数上,而所作的修改没有更改参数的值类型,那么 SOAPMessageContext 处理程序就会修改 SOAP 消息的头。如果所作的修改没有更改值类型,那么处理程序就会修改消息的部件值。 处理程序可以以本地事务模式访问事务资源。 定义特定于应用程序的头的处理程序应该在这些头所关联的组件的 WSDL 文档中声明头模式,但并不是必须这样做。 6.2.4. 容器提供者职责处理程序链根据 [JAX-RPC] 规范的第 12.2.2 节进行处理。缺省的处理顺序为处理程序在部署描述符中定义的顺序,并符合 [JAX-RPC] 规范的第 12.1.4 节中的处理顺序。 要求容器提供 容器必须在端口组件的环境的上下文中调用 容器必须提供请求类型独有的 容器必须跨所有处理程序实例和在单个请求和响应或在特定节点上进行的故障处理期间被调用的目标端点共享同一个 容器在调用处理程序链的 不要求容器提供者支持在 EJB 容器中运行的端口组件的处理程序。人们期望当本规范被包含到 J2EE 1.4 中时,会要求这一点。 7. 部署描述符本章描述各种用于 Web Services for J2EE 的部署描述符以及负责定义部署描述符中的信息的角色。 7.1. Web 服务部署描述符这一节定义 webservices.xml 文件的内容、模块内的位置、角色和职责以及格式。 7.1.1. 概述
7.1.2. 开发者职责开发者不但要负责 Web 服务的实现,还要负责声明其部署特征。部署特征在特定于模块的部署描述符以及 webservices.xml 部署描述符两者中定义。使用无状态会话 bean 的服务实现必须使用 开发者负责在
请注意,如果 WSDL 在端口中指定了地址语句,它的 URI 地址就会被忽略。这个地址是在部署期间在部署的 WSDL 中生成并被取代的。 还是请参阅第 7.2.2 节 开发者职责中定义的开发者要求。 7.1.3. 装配者职责Web Services for J2EE 的装配者的职责是在 [EJB]、Servlet 2.3 和 J2EE 1.3 规范定义的装配者职责上进行了扩展。装配者通过组成多个模块、分析模块间的依赖性并生成 EAR 文件,从而创建一个可部署的构件。 装配者可以修改下面由开发者在
还请参阅第 7.1.3 节 装配者职责中定义的装配者职责。 7.1.4. 部署者职责部署者的职责是由 J2EE 1.3、[EJB] 以及 Servlet 2.3 规范所定义的。 另外,部署者必须分析下面的信息:
7.1.5. Web 服务部署描述符 DTD下面是 Web 服务部署描述符的 DTD: <!-- Last updated: 08/21/2002 11:30 All Web service deployment descriptors must use the following delcaration: <!DOCTYPE webservices PUBLIC "-//IBM Corporation, Inc.//DTD J2EE Web services 1.0//EN" "http://www.ibm.com/standards/xml/webservices/j2ee/j2ee_Web_services_1_0.dtd"> --> <!-- The webservices element is the root element for the Web services deployment descriptor. It specifies the set of Web service descriptions that are to be deployed into the J2EE Application Server and the dependencies they have on container resources and services. Used in: webservices.xml --> <!ELEMENT webservices (description?, display-name?, small-icon?, large-icon?, webservice-description+) > <!-- The description element is used by the module producer to provide text describing the parent element. The description element should include any information that the module producer wants to provide to the consumer of the module (i.e. to the Deployer). Typically, the tools used by the module consumer will display the description when processing the parent element that contains the description. Used in: port-component, webservice-description, webservices --> <!ELEMENT description (#PCDATA)> <!-- The display-name element contains a short name that is intended to be displayed by tools. The display name need not be unique. Used in: port-component, webservice-description and webservices Example: <display-name>Employee Self Service</display-name> --> <!ELEMENT display-name (#PCDATA)> <!-- The ejb-link element is used in the service-impl-bean element to specify that a Service Implementation Bean is defined as a Web Service Endpoint. The value of the ejb-link element must be the ejb-name of an enterprise bean in the same ejb-jar file. Used in: service-impl-bean Examples: <ejb-link>EmployeeRecord</ejb-link> <ejb-link>../products/product.jar#ProductEJB</ejb-link> --> <!ELEMENT ejb-link (#PCDATA)> <!-- Declares the handler for a port-component. Handlers can access the init-param name/value pairs using the HandlerInfo interface. Used in: port-component --> <!ELEMENT handler (description?, display-name?, small-icon?, large-icon?, handler-name, handler-class, init-param*, soap-header*, soap-role*)> <!-- Defines the name of the handler. The name must be unique within the module. --> <!ELEMENT handler-name (#PCDATA)> <!-- Defines a fully qualified class name for the handler implementation. --> <!ELEMENT handler-class (#PCDATA)> <!-- The init-param element contains a name/value pair as an initialization param of the servlet Used in: filter, servlet --> <!ELEMENT init-param (param-name, param-value, description?)> <!-- The jaxrpc-mapping-file element contains the name of a file that describes the JAX-RPC mapping between the Java interaces used by the application and the WSDL description in the wsdl-file. The file name is a relative path within the module. Used in: webservice-description --> <!ELEMENT jaxrpc-mapping-file (#PCDATA)> <!-- The localpart element indicates the local part of a QNAME. Used in: soap-header, wsdl-port --> <!ELEMENT localpart (#PCDATA)> <!-- The namespaceURI element indicates a URI. Used in: soap-header, wsdl-port --> <!ELEMENT namespaceURI (#PCDATA)> <!-- The param-name element contains the name of a parameter. Each parameter name must be unique in the Web application. Used in: context-param, init-param --> <!ELEMENT param-name (#PCDATA)> <!-- The param-value element contains the value of a parameter. Used in: context-param, init-param --> <!ELEMENT param-value (#PCDATA)> <!-- The large-icon element contains the name of a file containing a large (32 x 32) icon image. The file name is relative path within the ejb-jar file. The image must be either in the JPEG or GIF format. The icon can be used by tools. Example: <large-icon>employee-service-icon32x32.jpg</large-icon> --> <!ELEMENT large-icon (#PCDATA)> <!-- The port-component element associates a WSDL port with a Web service interface and implementation. It defines the name of the port as a component, optional description, optional display name, optional iconic representations, WSDL port QName, Service Endpoint Interface, Service Implementation Bean. Used in: webservices --> <!ELEMENT port-component (description?, display-name?, small-icon?, large-icon?, port-component-name, wsdl-port, service-endpoint-interface, service-impl-bean, handler*)> <!-- The port-component-name element specifies a port component's name. This name is assigned by the module producer to name the service implementation bean inthe module's deployment descriptor. The name must be unique among the port component names defined in the same module. Used in: port-component Example: <port-component-name>EmployeeService</port-component-name> --> <!ELEMENT port-component-name (#PCDATA)> <!-- The service-endpoint-interface element contains the fully-qualified name of the port component's Service Endpoint Interface. Used in: port-component Example: <remote>com.wombat.empl.EmployeeService</remote> --> <!ELEMENT service-endpoint-interface (#PCDATA)> <!-- The service-impl-bean element defines the Web service implementation. A service implementation can be an EJB bean class or JAX-RPC Web component. Existing EJB implementations are exposed as a Web service using an ejb-link. Used in: port-component --> <!ELEMENT service-impl-bean (ejb-link | servlet-link)> <!-- The servlet-link element is used in the service-impl-bean element to specify that a Service Implementation Bean is defined as a JAX-RPC Service Endpoint. The value of the servlet-link element must be the servlet-name of a JAX-RPC Service Endpoint in the same WAR file. Used in: service-impl-bean Example: <servlet-link>StockQuoteService</servlet-link> --> <!ELEMENT servlet-link (#PCDATA)> <!-- The small-icon element contains the name of a file containing a small (16 x 16) icon image. The file name is relative path within the ejb-jar file. The image must be either in the JPEG or GIF format. The icon can be used by tools. Example: <small-icon>employee-service-icon16x16.jpg</small-icon> --> <!ELEMENT small-icon (#PCDATA)> <!-- Defines the QName of a SOAP header that will be processed by the handler. --> <!ELEMENT soap-header (namespaceURI, localpart)> <!-- The soap-role element contains a SOAP actor definition that the Handler will play as a role. --> <!ELEMENT soap-role (#PCDATA)> <!-- The webservice-description element defines a WSDL document file and the set of Port components associated with the WSDL ports defined in the WSDL document. There may be multiple webservice-descriptions defined within a module. All WSDL file ports must have a corresponding port-component element defined. Used in: webservices --> <!ELEMENT webservice-description (description?, display-name?, small-icon?, large-icon?, webservice-description-name, wsdl-file, jaxrpc-mapping-file, port-component+)> <!-- The webservice-description-name identifies the collection of port-components associated with a WSDL file and JAX-RPC mapping. The name must be unique within the deployment descriptor. Used in: webservice-description --> <!ELEMENT webservice-description-name (#PCDATA)> <!-- The wsdl-file element contains the name of a WSDL file in the module. The file name is a relative path within the module. --> <!ELEMENT wsdl-file (#PCDATA)> <!-- Defines the name space and local name part of the WSDL port QName. --> <!ELEMENT wsdl-port (namespaceURI, localpart)> <!-- The ID mechanism is to allow tools that produce additional deployment information (i.e., information beyond the standard EJB deployment descriptor information) to store the non-standard information in a separate file, and easily refer from these tools-specific files to the information in the standard deployment descriptor. The EJB architecture does not allow the tools to add the non-standard information into the EJB deployment descriptor. --> <!ATTLIST description id ID #IMPLIED> <!ATTLIST display-name id ID #IMPLIED> <!ATTLIST ejb-link id ID #IMPLIED> <!ATTLIST handler id ID #IMPLIED> <!ATTLIST handler-class id ID #IMPLIED> <!ATTLIST handler-name id ID #IMPLIED> <!ATTLIST init-param id ID #IMPLIED> <!ATTLIST jaxrpc-mapping-file id ID #IMPLIED> <!ATTLIST large-icon id ID #IMPLIED> <!ATTLIST localpart id ID #IMPLIED> <!ATTLIST namespaceURI id ID #IMPLIED> <!ATTLIST param-name id ID #IMPLIED> <!ATTLIST param-value id ID #IMPLIED> <!ATTLIST port-component id ID #IMPLIED> <!ATTLIST port-component-name id ID #IMPLIED> <!ATTLIST service-endpoint-interface id ID #IMPLIED> <!ATTLIST service-impl-bean id ID #IMPLIED> <!ATTLIST servlet-link id ID #IMPLIED> <!ATTLIST small-icon id ID #IMPLIED> <!ATTLIST soap-header id ID #IMPLIED> <!ATTLIST soap-role id ID #IMPLIED> <!ATTLIST webservices id ID #IMPLIED> <!ATTLIST webservice-description id ID #IMPLIED> <!ATTLIST webservice-description-name id ID #IMPLIED> <!ATTLIST wsdl-file id ID #IMPLIED> <!ATTLIST wsdl-port id ID #IMPLIED> 7.2. Web 服务客户机部署描述符这一节定义 webservicesclient.xml 文件的功能、模块内的位置、角色和职责以及格式。 7.2.1. 概述
7.2.2. 开发者职责开发者要负责为模块内的组件希望引用的每个 Web 服务定义一个
开发者指定下面的信息:
7.2.3. 装配者职责除了 J2EE 1.3 规范中定义的职责之外,装配者还可以定义下面的信息:
装配者可以修改下面由开发者在
7.2.5. webservicesclient.xml DTDwebservicesclient.xml 部署描述符的 DTD: <!-- Last updated: 08/21/2002 11:30 All Web service client deployment descriptors must use the following declaration: <!DOCTYPE webservicesclient PUBLIC "-//IBM Corporation, Inc.//DTD J2EE Web services client 1.0//EN" "http://www.ibm.com/standards/xml/webservices/j2ee/j2ee_Web_services_client_1_0.dtd"> --> <!-- The webservicesclient element is the top level element for service references. --> <!ELEMENT webservicesclient (service-ref+|component-scoped-refs+)> <!-- The component-name element defines a link to a component name such as the ejb-name in the module deployment descriptor. It's value must exist in the module level deployment descriptor. Used in: component-scoped-refs --> <!ELEMENT component-name (#PCDATA)> <!-- The component-scoped-refs element defines service references that are scoped to a particular component of a module. Not all modules support component scoping. Used in: webservicesclient --> <!ELEMENT component-scoped-refs (component-name, service-ref+)> <!-- The description element gives the deployer a textual description of the Web service. Used in: service-ref --> <!ELEMENT description (#PCDATA)> <!-- The display-name element contains a short name that is intended to be displayed by tools. The display name need not be unique. Used in: port-component and webservices Example: <display-name>Employee Self Service</display-name> --> <!ELEMENT display-name (#PCDATA)> <!-- Declares the handler for a port-component. Handlers can access the init-param name/value pairs using the HandlerInfo interface. If port-name is not specified, the handler is assumed to be associated with all ports of the service. Used in: service-ref --> <!ELEMENT handler (description?, display-name?, small-icon?, large-icon?, handler-name, handler-class, init-param*, soap-header*, soap-role*, port-name*)> <!-- Defines a fully qualified class name for the handler implementation. --> <!ELEMENT handler-class (#PCDATA)> <!-- Defines the name of the handler. The name must be unique within the module. --> <!ELEMENT handler-name (#PCDATA)> <!-- The init-param element contains a name/value pair as an initialization param of the handler. Used in: handler --> <!ELEMENT init-param (param-name, param-value, description?)> <!-- The jaxrpc-mapping-file element contains the name of a file that describes the JAX-RPC mapping between the Java interaces used by the application and the WSDL description in the wsdl-file. The file name is a relative path within the module file. Used in: webservice-description --> <!ELEMENT jaxrpc-mapping-file (#PCDATA)> <!-- The large-icon element contains the name of a file containing a large (32 x 32) icon image. The file name is relative path within the module file. The image must be either in the JPEG or GIF format. The icon can be used by tools. Example: <large-icon>employee-service-icon32x32.jpg</large-icon> --> <!ELEMENT large-icon (#PCDATA)> <!-- The localpart element indicates the local part of a QNAME. Used in: service-qname, soap-header --> <!ELEMENT localpart (#PCDATA)> <!-- The namespaceURI element indicates a URI. Used in: service-qname, soap-header --> <!ELEMENT namespaceURI (#PCDATA)> <!-- The param-name element contains the name of a parameter. Each parameter name must be unique in the Web application. Used in: context-param, init-param --> <!ELEMENT param-name (#PCDATA)> <!-- The param-value element contains the value of a parameter. Used in: context-param, init-param --> <!ELEMENT param-value (#PCDATA)> <!-- The port-component-link element links a port-component-ref to a specific port-component required to be made available by a service reference. The value of a port-component-link must be the port-component-name of a port-component in the same module or another module in the same application unit. The syntax for specification follows the syntax defined for ejb-link in the EJB 2.0 specification. Used in: port-component-ref --> <!ELEMENT port-component-link (#PCDATA)> <!-- The port-component-ref element declares a client dependency on the container for resolving a Service Endpoint Interface to a WSDL port. It optionally associates the Service Endpoint Interface with a particular port-component. This is only used by the container for a Service.getPort(Class) method call. Used in: service-ref --> <!ELEMENT port-component-ref (service-endpoint-interface, port-component-link?)> <!-- The port-name element defines the WSDL port-name that a handler should be associated with. --> <!ELEMENT port-name (#PCDATA)> <!-- The service-endpoint-interface element defines a fully qualified Java class that represents the Service Endpoint Interface of a WSDL port. Used in: service-ref --> <!ELEMENT service-endpoint-interface (#PCDATA)> <!-- The service-interface element declares the fully qualified class name of the JAX-RPC Service interface the client depends on. In most cases the value will be javax.xml.rpc.Service. A JAX-RPC generated Service Interface class may also be specified. Used in: services-ref --> <!ELEMENT service-interface (#PCDATA)> <!-- The service-qname element declares the specific WSDL service element that is being refered to. It is not specified if no wsdl-file is declared. Used in service-ref --> <!ELEMENT service-qname (namespaceURI, localpart)> <!-- The service-ref element declares a reference to a Web service. It contains optional description, display name and icons, a declaration of the required Service interface, an optional WSDL document location, an optional set of JAX-RPC mappings, an optional QName for the service element, an optional set of Service Endpoint Interfaces to be resolved by the container to a WSDL port, and an optional set of handlers. Used in: webservicesclient.xml --> <!ELEMENT service-ref (description?, display-name?, small-icon?, large-icon?, service-ref-name, service-interface, wsdl-file?, jaxrpc-mapping-file?, service-qname?, port-component-ref*, handler*)> <!-- The service-ref-name element declares logical name that the components in the module use to look up the Web service. It is recommended that all service reference names start with "service/". Used in: services-ref --> <!ELEMENT service-ref-name (#PCDATA)> <!-- The small-icon element contains the name of a file containing a small (16 x 16) icon image. The file name is relative path within the module file. The image must be either in the JPEG or GIF format. The icon can be used by tools. Example: <small-icon>employee-service-icon16x16.jpg</small-icon> --> <!ELEMENT small-icon (#PCDATA)> <!-- Defines the QName of a SOAP header that will be processed by the handler. --> <!ELEMENT soap-header (namespaceURI, localpart)> <!-- The soap-role element contains a SOAP actor definition that the Handler will play as a role. --> <!ELEMENT soap-role (#PCDATA)> <!-- The wsdl-file element contains the URI location of a WSDL file. The location is relative to the root of the module. Used in: service-ref --> <!ELEMENT wsdl-file (#PCDATA)> <!ATTLIST component-name id ID #IMPLIED> <!ATTLIST component-scoped-refs id ID #IMPLIED> <!ATTLIST description id ID #IMPLIED> <!ATTLIST display-name id ID #IMPLIED> <!ATTLIST handler id ID #IMPLIED> <!ATTLIST handler-class id ID #IMPLIED> <!ATTLIST handler-name id ID #IMPLIED> <!ATTLIST init-param id ID #IMPLIED> <!ATTLIST jaxrpc-mapping-file id ID #IMPLIED> <!ATTLIST large-icon id ID #IMPLIED> <!ATTLIST localpart id ID #IMPLIED> <!ATTLIST namespaceURI id ID #IMPLIED> <!ATTLIST param-name id ID #IMPLIED> <!ATTLIST param-value id ID #IMPLIED> <!ATTLIST port-component-link id ID #IMPLIED> <!ATTLIST port-component-ref id ID #IMPLIED> <!ATTLIST port-name id ID #IMPLIED> <!ATTLIST service-endpoint-interface id ID #IMPLIED> <!ATTLIST service-interface id ID #IMPLIED> <!ATTLIST service-qname id ID #IMPLIED> <!ATTLIST service-ref id ID #IMPLIED> <!ATTLIST service-ref-name id ID #IMPLIED> <!ATTLIST small-icon id ID #IMPLIED> <!ATTLIST soap-header id ID #IMPLIED> <!ATTLIST soap-role id ID #IMPLIED> <!ATTLIST webservicesclient id ID #IMPLIED> <!ATTLIST wsdl-file id ID #IMPLIED> 7.3. JAX-RPC 映射部署描述符7.3.1. 概述JAX-RPC 映射部署描述符没有标准的文件名。模块中的 WSDL 文档和映射文件具有一一对应关系。JAX-RPC 映射部署描述符包含在 Java 接口和 WSDL 定义之间建立映射关系的信息。部署工具使用该信息,结合 WSDL 文件生成部署的服务和服务引用的存根和 TIE。 7.3.2. 开发者职责开发者在 WSDL 和/或 Java 接口被创建的同时创建映射文件。如果满足了下面的条件,开发者就可以仅指定打包映射。
如果条件不满足,那么就必须指定完整的映射。对于每个根 WSDL 类型必须有一个 不管 WSDL 内容是什么,Web Services for J2EE 提供者都可以通过使用标准的 JAX-RPC WSDL 到 Java 的映射规则来解析映射,从而支持部件映射规范(例如不为每种方法提供 开发者必须定义 webservices.xml 或 webservicesclient.xml 部署描述符的 开发者必须把映射文件和 WSDL 文件一起打包在模块中。 7.3.5. JAX-RPC 映射 DTD<!-- Last updated: 08/21/2002 11:30 All Web service deployment descriptors must use the following delcaration: <!DOCTYPE java-wsdl-mapping PUBLIC "-//IBM Corporation, Inc.//DTD J2EE JAX-RPC mapping 1.0//EN" "http://www.ibm.com/standards/xml/webservices/j2ee/j2ee_jaxrpc_mapping_1_0.dtd"> --> <!-- The element describes the Java mapping to a known WSDL document. It contains the mapping between package names and XML namespaces, WSDL root types and Java artifacts, and the set of mappings for services. --> <!ELEMENT java-wsdl-mapping (package-mapping+, java-xml-type-mapping*, exception-mapping*, (service-interface-mapping?, service-endpoint-interface-mapping+)*)> <!-- The class-type element is the fully qualified class name of a Java class. Used in: java-xml-type-mapping --> <!ELEMENT class-type (#PCDATA)> <!-- The constructor-parameter-order element defines the order that complexType element values are applied to a Java exception constructor. Element names are specified for each parameter of the constructor, including element names of inherited types if necessary. Used in: exception-mapping --> <!ELEMENT constructor-parameter-order (element-name+)> <!-- The data-member element is a boolean indicator that a Java variable is a public data member and not a JavaBeans property. Used in: variable-mapping --> <!ELEMENT data-member EMPTY> <!-- The element-name element defines the name of a complexType element name attribute value. Used in: constructor-parameter-order --> <!ELEMENT element-name (#PCDATA)> <!-- The exception-mapping element defines the mapping between the service specific exception types and the wsdl faults. This element should be interpreted with respect to the mapping between a method and an operation which provides the mapping context. Used in: service-endpoint-method-mapping --> <!ELEMENT exception-mapping (exception-type, wsdl-message, constructor-parameter-order?)> <!-- The exception-type element defines Java type of the exception. It may be a service specific exception. It must be a fully qualified class name. Used in: exception-mapping --> <!ELEMENT exception-type (#PCDATA)> <!-- The java-method-name element defines the name of a Java method within an interface. Used in: service-endpoint-method-mapping --> <!ELEMENT java-method-name (#PCDATA)> <!-- The java-port-name element is the string to use as the port name in Java. It is used in generating the Generated Service Interface method get<java-port-name>. Used in: port-mapping --> <!ELEMENT java-port-name (#PCDATA)> <!-- The java-variable-name defines the name of a public data member or JavaBeans property within a Java class. Used in: variable-mapping --> <!ELEMENT java-variable-name (#PCDATA)> <!-- The java-xml-type-mapping element contains a class-type that is the fully qualified name of the Java class, QName of the XML root type, the WSDL type scope the QName applies to and the set of variable mappings for each public variable within the Java class. Used in: java-wsdl-mapping --> <!ELEMENT java-xml-type-mapping (class-type, root-type-qname, qname-scope, variable-mapping*)> <!-- The localpart element indicates the local part of a QNAME. Used in: wsdl-binding, wsdl-message, wsdl-port-type, wsdl-service-name --> <!ELEMENT localpart (#PCDATA)> <!-- The method-param-parts-mapping element defines the mapping between a Java method parameters and a wsdl-message. Used in: service-endpoint-method-mapping --> <!ELEMENT method-param-parts-mapping (param-position, param-type, wsdl-message-mapping)> <!-- The method-return-value element defines a fully qualified class name or void type for the method's return value type. Used in: wsdl-return-value-mapping --> <!ELEMENT method-return-value (#PCDATA)> <!-- The namespaceURI element indicates a URI. Used in: package-mapping, wsdl-binding, wsdl-message, wsdl-port-type, wsdl-service-name --> <!ELEMENT namespaceURI (#PCDATA)> <!-- The package-mapping indicates the mapping between java-package-name and XML namespace in the WSDL document. Used in: java-wsdl-mapping --> <!ELEMENT package-mapping (package-type, namespaceURI)> <!-- The package-type indicates the Java package name. It must be a fully qualified name. Used in: package-mapping --> <!ELEMENT package-type (#PCDATA)> <!-- The parameter-mode element defines the mode of the parameter. It can have only three values, IN, OUT, INOUT. Used in: wsdl-message-mapping, wsdl-return-value-mapping --> <!ELEMENT parameter-mode (#PCDATA)> <!-- The param-position element defines the position of a parameter within a Java method. It must be an integer starting from 0. Used in: method-param-parts-mapping --> <!ELEMENT param-position (#PCDATA)> <!-- The param-type element defines the Java type of a parameter within a Java method. It must be defined by a fully qualified name of a class. Used in: method-param-parts-mapping --> <!ELEMENT param-type (#PCDATA)> <!-- The port-mapping defines the mapping of the WSDL port name attribute to the Java name used to generate the Generated Service Interface method get<java-name>. Used in: service-interface-mapping --> <!ELEMENT port-mapping (port-name, java-port-name)> <!-- The port-name is the attribute value of a name attribute of a WSDL port element. Used in: port-mapping --> <!ELEMENT port-name (#PCDATA)> <!-- The qname-scope elements scopes the reference of a QName to the WSDL element type it applies to. The value of qname-scope may be simpleType, complexType, or element. Used in: java-xml-type-mapping --> <!ELEMENT qname-scope (#PCDATA)> <!-- The root-type-qname identifies the WSDL QName of an XML type. Used in: java-xml-type-mapping --> <!ELEMENT root-type-qname (namespaceURI, localpart)> <!-- The service-endpoint-interface element defines the Java type for the endpoint interface. The name must be a fully qualified class name. Used in: service-endpoint-interface-mapping --> <!ELEMENT service-endpoint-interface (#PCDATA)> <!-- The service-endpoint-interface-mapping defines a tuple to specify Service Endpoint Interfaces to WSDL port types and WSDL bindings. An interface may be mapped to a port-type and binding multiple times. This happens rarely. Used in: java-wsdl-mapping --> <!ELEMENT service-endpoint-interface-mapping ( service-endpoint-interface, wsdl-port-type, wsdl-binding, service-endpoint-method-mapping*)> <!-- The service-endpoint-method-mapping element defines the mapping of Java methods to operations (which are not uniquely qualified by qnames). The wsdl-operation should be interpreted with respect to the portType and binding in which this definition is embedded within. See the definitions for service-endpoint-interface-mapping and service-interface-mapping to acquire the proper context. Used in: service-endpoint-interface-mapping --> <!ELEMENT service-endpoint-method-mapping (java-method-name, wsdl-operation, method-param-parts-mapping*, wsdl-return-value-mapping)> <!-- The service-interface element defines the Java type for the service. For static services, it is javax.xml.rpc.Service interface. For generated service, it would be the generated interface name. The name must be a fully qualified class name. Used in: service-interface-mapping --> <!ELEMENT service-interface (#PCDATA)> <!-- The service-interface-mapping element defines how a Java type for the service interface maps to a WSDL service. Used in: java-wsdl-mapping --> <!ELEMENT service-interface-mapping (service-interface, wsdl-service-name, port-mapping*)> <!-- The soap-header element is a boolean element indicating that a parameter is mapped to a SOAP header. Used in: wsdl-message-mapping --> <!ELEMENT soap-header EMPTY> <!-- The variable-mapping element defines the correlation between a Java class data member or JavaBeans property to an XML element name of an XML root type. If the data-member element is present, the Java variable name is a public data member. If data-member is not present, the Java variable name is a JavaBeans property. Used in: java-xml-type-mapping --> <!ELEMENT variable-mapping (java-variable-name, data-member?, xml-element-name)> <!-- The wsdl-binding element defines the wsdl binding by a QNAME which uniquely identifies the binding. Used in: service-endpoint-interface-mapping --> <!ELEMENT wsdl-binding (namespaceURI, localpart)> <!-- The wsdl-message element defines a WSDL message by a QNAME. Used in: wsdl-message-mapping, wsdl-return-value-mapping --> <!ELEMENT wsdl-message (namespaceURI, localpart)> <!-- The wsdl-message-mapping element defines the mapping to a specific message and its part. Together they define uniquely the mapping for a specific parameter. Parts within a message context are uniquely identified with their names. The parameter-mode is defined by the mapping to indicate whether the mapping will be IN, OUT, or INOUT.. The presence of the soap-header element indicates that the parameter is mapped to a soap header only. When absent, it means that the wsdl-message is mapped to a Java parameter. The soap headers are interpreted in the order they are provided in the mapping. Used in: method-param-parts-mapping --> <!ELEMENT wsdl-message-mapping (wsdl-message, wsdl-message-part-name, parameter-mode, soap-header?)> <!-- The wsdl-message-part-name element defines a WSDL message part. It should always be interpreter with respect to a wsdl-message element. Used in: wsdl-message-mapping, wsdl-return-value-mapping --> <!ELEMENT wsdl-message-part-name (#PCDATA)> <!-- The wsdl-operation element defines an operation within a WSDL document. It must be interpreted with respect to a port type. Used in: service-endpoint-method-mapping --> <!ELEMENT wsdl-operation (#PCDATA)> <!-- The wsdl-port-type element defines the wsdl port type by a QNAME which uniquely identifies the port type. Used in: service-endpoint-interface-mapping --> <!ELEMENT wsdl-port-type (namespaceURI, localpart)> <!-- The wsdl-return-value-mapping element defines the mapping for the method's return value. It defines the mapping to a specific message and its part. Together they define uniquely the mapping for a specific parameter. Parts within a message context are uniquely identified with their names. Used in: service-endpoint-method-mapping --> <!ELEMENT wsdl-return-value-mapping (method-return-value, wsdl-message, wsdl-message-part-name)> <!-- The wsdl-service-name element defines the wsdl service name by a QNAME which uniquely identifies the service. Used in: service-interface-mapping --> <!ELEMENT wsdl-service-name (namespaceURI, localpart)> <!-- The xml-element-name element defines name attribute value of a WSDL element within a root type. Used in: variable-mapping --> <!ELEMENT xml-element-name (#PCDATA)> <!-- The ID mechanism is to allow tools that produce additional deployment information (i.e., information beyond the standard EJB deployment descriptor information) to store the non-standard information in a separate file, and easily refer from these tools-specific files to the information in the standard deployment descriptor. The EJB architecture does not allow the tools to add the non-standard information into the EJB deployment descriptor. --> <!ATTLIST class-type id ID #IMPLIED> <!ATTLIST data-member id ID #IMPLIED> <!ATTLIST exception-mapping id ID #IMPLIED> <!ATTLIST exception-type id ID #IMPLIED> <!ATTLIST java-method-name id ID #IMPLIED> <!ATTLIST java-port-name id ID #IMPLIED> <!ATTLIST java-variable-name id ID #IMPLIED> <!ATTLIST java-wsdl-mapping id ID #IMPLIED> <!ATTLIST java-xml-type-mapping id ID #IMPLIED> <!ATTLIST localpart id ID #IMPLIED> <!ATTLIST method-param-parts-mapping id ID #IMPLIED> <!ATTLIST method-return-value id ID #IMPLIED> <!ATTLIST namespaceURI id ID #IMPLIED> <!ATTLIST package-mapping id ID #IMPLIED> <!ATTLIST package-type id ID #IMPLIED> <!ATTLIST parameter-mode id ID #IMPLIED> <!ATTLIST param-position id ID #IMPLIED> <!ATTLIST param-type id ID #IMPLIED> <!ATTLIST port-mapping id ID #IMPLIED> <!ATTLIST port-name id ID #IMPLIED> <!ATTLIST qname-scope id ID #IMPLIED> <!ATTLIST root-type-qname id ID #IMPLIED> <!ATTLIST service-endpoint-interface id ID #IMPLIED> <!ATTLIST service-endpoint-interface-mapping id ID #IMPLIED> <!ATTLIST service-endpoint-method-mapping id ID #IMPLIED> <!ATTLIST service-interface id ID #IMPLIED> <!ATTLIST service-interface-mapping id ID #IMPLIED> <!ATTLIST soap-header id ID #IMPLIED> <!ATTLIST variable-mapping id ID #IMPLIED> <!ATTLIST wsdl-binding id ID #IMPLIED> <!ATTLIST wsdl-message id ID #IMPLIED> <!ATTLIST wsdl-message-mapping id ID #IMPLIED> <!ATTLIST wsdl-message-part-name id ID #IMPLIED> <!ATTLIST wsdl-operation id ID #IMPLIED> <!ATTLIST wsdl-port-type id ID #IMPLIED> <!ATTLIST wsdl-return-value-mapping id ID #IMPLIED> <!ATTLIST wsdl-service-name id ID #IMPLIED> <!ATTLIST xml-element-name id ID #IMPLIED> 8. 部署本章定义了部署过程要求和职责。部署任务是由 J2EE 部署者平台角色使用通常由 Web Services for J2EE 产品提供者提供的工具处理。这包括特定于容器的 Web 服务类和 Web 服务引用类的生成、为每个端口的配置服务器 SOAP 请求侦听器、Web 服务的发布和定位,还有 J2EE 规范定义的一般职责。 8.1. 概述本节描述了 Web Services for J2EE 的一个说明性部署过程。过程本身是不需要的,但是部署必须满足某些需要,本章后面部分将详细描述这些内容。这个过程假定部署有一般有两个阶段。第一阶段将 Web 服务映射到标准的 J2EE 构件,第二阶段是标准的 J2EE 部署过程。 部署从启用服务的应用程序或模块入手。开发者使用部署工具来开始部署过程。一般来说,部署工具将验证内容是否为正确装配的部署构件、并从部属程序收集绑定信息、部署模块中定义的组件和 Web 服务、发布代表被部署 Web 服务的 WSDL 文档、部署任何使用 Web 服务客户机、配置服务器并启动应用程序。 部署工具开始部署过程时首先要检查可部署的构件并通过查找包含在模块中的 webservices.xml 部署描述符文件来确定哪个模块是启用 Web 服务的。服务的部署在服务引用的解析之前发生。这样是为了使部署能够在对它们的服务引用被处理之前更新 WSDL 端口地址。 执行构件打包的验证是为了确保:
每个端口-组件的部署都依赖于所使用的服务实现和容器。JAX-RPC 服务端点的部署需要与会话 bean 服务的部署不同的处理方法。 如果实现为 JAX-RPC 服务端点,那么将生成一个 servlet 以处理解析传入的 SOAP 请求并将其分派至 JAX-RPC 服务组件的实例上的过程。生成的 servlet 类依赖于 JAX-RPC 服务端点的线程使用模型。 部署工具必须部署和发布 Web 服务部署描述符中描述的所有 WSDL 文档的所有端口。部署工具为每个部署的 对 Web 服务客户机部署描述符中描述的每个服务引用来说,部署工具都确保客户机代码能够访问 Web 服务。部署工具检查客户机部署描述符中提供的信息(服务接口类、服务端点接口类以及客户机希望访问的 WSDL 端口)以及 JAX-RPC 映射信息。一般来说,过程包括提供部署描述符服务引用中声明的 JAX-RPC 服务接口类的实现、为所有 在使用客户机管理的端口访问服务时,部署工具必须对 Web 服务客户机部署描述符中声明的每个端口提供生成的存根或动态代理访问。选择生成的存根或动态代理是部署时绑定信息。如果在部署描述符中声明,那么容器必须为生成的服务接口提供实现。 在使用容器管理的端口访问时,容器必须对部署描述符中声明的每个端口提供生成的存根或动态代理访问。选择生成的存根或动态代理是部署时绑定信息。部署描述符可能包含 一旦支持 Web 服务的可部署构件被转换为 J2EE 可部署构件,部署过程将继续使用常规的部署过程。 8.2. 容器提供者要求这一节将详细描述容器提供者的要求。它不但包含容器运行时,还包含部署工具使用。 8.2.2. 生成 Web 服务实现类容器支持 JAX-RPC 服务端点或无状态会话 Bean 服务实现所需的任何运行时类的生成都是特定于提供者的。运行时类的行为必须与组件的部署描述符设置一致。JAX-RPC 服务端点必须与 8.2.3. 生成部署的 WSDL容器必须为 Web 服务部署描述符(webservices.xml)中声明的每个
8.2.4. 发布部署的 WSDL部署工具必须发布每个部署的 WSDL 文档。部署的 WSDL 文档可以被发布到文件、URL 或者注册中心。文件和 URL 发布必须被提供者支持。文件发布包含在应用程序生成的构件中。我们鼓励您发布到注册中心,如 UDDI 或 ebXML,但这不是必须的。 如果支持向文件或 URL 以外的位置发布,那么也必须支持包含该位置服务的 WSDL 文档。举例来说,Web 服务部署描述符声明了 选择从何处(什么位置以及几处地方)发布是部署时绑定信息。 8.2.5. 服务和生成的服务接口实现容器必须提供 JAX-RPC 服务接口的实现。服务实现不需要在部署期间创建。容器可以用生成的服务接口实现替代一般的服务接口实现。 如果 Web 服务客户机部署描述符定义了 JAX-RPC 生成的服务接口,那么容器就必须提供该接口的实现。生成的服务接口实现一般会在部署期间提供。 服务接口实现必须为 WSDL 描述中的服务元素声明的所有端口提供静态存根和/或动态代理。容器提供者必须支持至少静态存根或动态代理的其中一个,但可能为两者提供支持。 容器必须在 JNDI 名称空间位置 8.2.6. 静态存根生成部署工具可以支持静态存根的生成。如果不支持动态代理,那么容器提供者必须提供静态存根生成。静态存根是特定于提供者的,而且一般来说,开发者都应该避免将它们与应用程序打包在一起。 静态存根(和动态代理)必须遵循 [JAX-RPC] 规范的第 8.2.1 节和第 8.2.2 节。 如第 4.2.4 节 JAX_RPC 属性中所定义,容器需要在没有客户机代码干预的情况下支持凭证传播。存根/代理是否直接支持这一点或容器的另一部分不在本规范讨论的范围之内。 8.2.9. 部署失败的情况如果出现下面的情况,部署可能会失败:
9. 安全性这一节定义了 Web Services for J2EE 的安全性要求。第 5.2 节 概念中讨论了安全性的概念性概况,还讨论了它如何应用于 Web 服务。第 9.2 节 目标定义了本规范着眼于解决的问题,第 6.2 节 规范讨论了需求。 9.1. 概念Web 服务安全性面临的挑战是如何理解并评估当前使基于 Web 的服务安全化可能要付出的风险,同时紧随新兴的标准并理解它们如何部署,从而减少将来的风险。任何安全性模型都必须说明数据可以如何在应用程序和网络拓扑结构中传送,以满足业务定义的需求,而不会将数据暴露在不当的风险下。Web 服务安全性模型应该支持与协议无关的声明性安全策略(Web Service for J2EE 提供者可以实施),以及附加在服务定义后的客户机可以用来安全地访问服务的描述性安全策略。 为了保证信息交换的安全,需要强调五点安全性要求:
与这些要求有关的风险可以通过结合 J2EE 环境中各种已有和新兴的技术及标准来避免。有很多基本的业务原因构成了各种安全性机制以减轻上面总结出的各种安全性风险。实体的认证是必需的。这有助于根据 Web 服务调用者的标识提供访问。数据完整性的商业原因在于事务中的每一方都可以对商业事务有信心。它还是商业合法性问题,使审计追踪和某些不可抵赖性的证据可以解决可靠性问题。越来越多的企业开始注意到来自员工或防火墙里面的其它人对其应用程序产生的内部威胁。某些商业事务要求在服务调用或其数据(如信用卡号码)上提供保密性。因特网上的企业还需要保护自身免受正在发起的拒绝服务攻击。这就是我们需要插入安全性服务模型的环境。 9.1.1. 认证由于 Web 服务体系结构建立在已有的组件技术上,所以企业内的认证与当前的方法没什么不同。为了让两方或多方能够安全地通信,它们可能需要交换安全性凭证。Web 服务的安全性用来交换许多不同类型的凭证。凭证代表相关标识的可靠性,例如 Kerberos 票据。凭证可以被验证,以验证其可靠性,而且标识可以从凭证推断出。 当两方进行通信时,发送者要理解目标服务的安全性要求,这也很重要。这有助于发送者提供必要的凭证和请求。另一种情况是,目标将询问发送者以获取必要的凭证(与 HTTP 服务器询问 HTTP 客户机类似)。 将来,希望消息层安全机制将被支持。使用这种方法,凭证就可以与消息一起传播并脱离底层传输协议。类似地,使用消息层保护可以确保保密性和完整性。消息层安全性支持将有助于解决端对端安全性需要,这样请求就可以用独立于底层协议的安全的方式遍历多个网络层、拓扑结构和媒介。 将来,我们还估计到为了让客户机应用程序确定 Web 服务期望的安全性级别以及期望的凭证类型,关于认证策略的信息将包含在服务定义(WSDL)中,也可以通过它来获得。建立在这种服务定义的基础上,客户机提供了合适的凭证。如果容器有服务策略,那么它们必须被引用并使用。 请考虑这样一种情况:传入的 SOAP/WSDL 消息流经 HTTP(S)。上图提供了安全性流的简单概览。企业 Web 站点依赖于认证模型的 J2EE 服务器支持。站点还依赖于代理服务器对安全性的支持。在这几种情况中,J2EE 服务器接收到请求之前就会发生认证。在这几种情况下,代理服务器或 Web 服务器将认证凭证转发到 J2EE 应用程序服务器中。J2EE 应用程序服务器将按照类似于处理其它 HTTP 请求的方式处理请求。J2EE 应用程序服务器可以按照处理其它 HTTP 请求的方式处理请求。 根据已有的 J2EE 功能,Web Services for J2EE 中有两种形式的认证可以使用。它们是 HTTP 基本认证( HTTP BASIC-AUTH)和对称 HTTP(Symmetric HTTP),由 Servlet 2.3 规范定义。 使用上述认证模型,容器也能在执行路径的任一点执行传入凭证的凭证映射。映射将外部用户凭证转换为特定安全域中使用的凭证,举例来说,通过 Kerberos 或其它嵌入式第三方模型转换。 除了传播凭证所用的 J2EE 安全性模型之外,在 SOAP 消息本身(例如作为 SOAP 头)中传送标识信息可能也很有好处。这有助于对付需要支持 Web 服务,而本身对底层传输和协议的安全性支持可能并不充分的情况(例如 JMS)。JSR109 不需要在 SOAP 消息中具备任何对凭证传播的支持,并将该功能视为以后的事情。 9.1.2. 授权在企业安全性模型中,每个应用程序服务器和中间件元素分别执行其资源(EJB、Servlet、队列和表等等)的授权。J2EE 认证/委派模型确保用户标识证明在对请求进行处理时是可以取得的。 一旦认证成功,通过认证的用户的标识就与请求有了关联。根据用户的标识做出了授权决策。基于 J2EE 1.3 安全性模型的 J2EE 服务器来执行这项任务是为了只允许对 EJB 和 Servlet/JSP 的方法进行授权的访问。对于实现为 JAX-RPC 服务端点的 Web 服务,对其进行授权要根据 servlet/JSP 安全性模型。 9.1.3. 完整性和保密性一般来讲,完整性和保密性建立在已有的 J2EE 支持(如 HTTPS)的基础上。 消息发送方也许还想要确保,消息或消息的部件保密以及消息在传送过程中没有被修改。当消息需要保密时,消息的发送方可以使用 XML Encryption 加密消息中那些不可以公开的部分。当需要保证消息的完整性时,消息的发送方可以使用 XML Digital Signature 来确保消息在传送过程中没有被修改。本规范推荐,J2EE 服务器使用 XML Encryption 用于保密,XML Digital Signature 来确保完整性,不过要放到将来的标准化格式和 API 的工作中。 9.2. 目标J2EE 应用程序服务器中的 Web 服务的安全性模型应该易于设计和使用、普遍存在、成本效率高、基于开放源标准、可扩展,而且灵活。基本的功能需要能够用于多种安全性模型、安全性认证凭证、多信任域和多加密技术的构建。因此,安全性的目标包括以下几点:
9.3. 规范9.3.1. 认证很少有用来认证消息发送者的认证模型可以作为标准而采用或提倡。基于表单的登录需要 html 处理功能,所以并不包括在这个列表中。Web Services for J2EE 产品提供者必须支持下面几项:
10. 附录10.1. 附录 A. 与其它 Java 标准的关系用于 XML 的 Java API 该清单中我们需要的 API 只有 JAX-RPC。列出其余的是考虑到您可能有兴趣了解。这些 API 在将来的规范中可能会变成必需的。
J2EE API
10.2. 附录 B. 参考资料
|
到页首 | ![]() |
![]() | |
![]() |
![]() |
![]() |
(c) Copyright IBM Corp. 2001, (c) Copyright IBM China 2001, All Right Reserved |
关于 IBM | 隐私条约 | 法律条款 | 联系 IBM |