3.3.1. Web 服务组件

本规范定义了两种实现在 J2EE 环境中运行的 Web 服务的方式，但并不把 Web 服务实现局限为仅仅这两种方式。第一种方法是基于容器的 JAX-RPC 编程模式的扩展，它将 Web 服务定义为在 Web 容器中运行的 Java 类。第二种方法将使用 EJB 容器中的无状态会话 EJB 的受限实现。还可能有其它的服务实现情况，但它们并不在本规范的定义之列。

3.3.2. Web 服务容器

容器提供了服务实现的生命周期管理、方法调用的并发管理以及安全性服务。容器提供了专门在 J2EE 环境中支持 Web 服务的服务。本规范不需要实现新的容器。您可以使用已有的 J2EE 容器，而且我们的确希望您使用已有的容器来托管 Web 服务。Web 服务实例生命周期和并发管理依赖于服务实现在哪个容器中运行。Web 容器中的 JAX-RPC 服务端点实现遵循标准的 servlet 生命周期和并发需求，而 EJB 容器中的 EJB 实现遵循标准的 EJB 生命周期和并发需求。

3.6.1. JAX-RPC

JAX-RPC 提供了运行时服务，以便向 XML SOAP 消息编入 Java 数据和对象，以及从 XML SOAP 消息中编出 Java 数据和对象。另外，JAX-RPC 定义了服务端点接口（Service Endpoint Interface）和服务（Service）类从 WSDL 到 Java 的映射。

3.8.1. 作用域

• 本规范的作用域仅限于在业界中被广泛制定和接受的 Web 服务标准。这些标准包括：

  • SOAP 1.1 以及带附件的 SOAP

  • WSDL 1.1

  • UDDI 1.0

• 本规范仅限于定义 HTTP 1.1 或 HTTPS 协议上的 SOAP 以及 Web 服务通信 API（供应商可以随意支持更多的传输）。

• 这些标准应该会继续改变和发展。这个 JSR 将来的版本将适应和解决这些标准将来的版本的问题。在本规范中，所有对 SOAP、WSDL、和 UDDI 的引用都假定为上面定义的版本。

3.8.2. 作用域之外

• HTTP 上的 SOAP 最缺乏的就是基本可靠消息语义。除了这一不足之外，本 JSR 在其作用域内还没有考虑到消息可靠性（Message Reliability）或消息完整性（Message Integrity）。其它的 JSR，如 JAX-M 和 JMS 的演变和合并产物，还有 W3C 中的活动以及其它标准实体，将定义这些功能。

• XML 数据的持久性。

• 工作流和数据流模型。

• 任意的 XML 转换。

• 与本规范不一致的 Web 服务客户机的客户机编程模型。

4.2.1. 服务查找

客户机开发者需要为 Web 服务定义一个逻辑的 JNDI 名称，这被称为服务引用。该名称在客户机的部署描述符中指定。我们推荐在一个 JNDI 名称空间的服务子上下文中对所有服务引用逻辑名称进行组织，但这不是必需的。容器必须使用服务引用的逻辑名称在客户机环境上下文 java:comp/env 中绑定服务接口实现。在下面的示例中，客户机部署描述符中给出的逻辑服务名为 service/AddressBookService。

容器充当代表客户机的媒介，用来确保能够通过 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() 方法之外）。

客户机开发者必须在客户机部署描述符中说明应用程序使用的服务接口类型。

4.2.2.1 存根／代理访问

客户机可以使用下面的服务接口方法来获取 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 节 端口存根和动态代理中所描述，容器必须为这些方法提供至少一个静态存根或动态代理。容器必须确保存根或动态代理在返回到客户机之前被完全配置为由客户机使用。存根或动态代理由 getPort 还是 get<port name> 方法返回的部署时选择不在本规范的讨论之列。容器提供者可以自行提供其中一个或两者。

容器提供者必须提供 getPort(java.lang.Class serviceEndpointInterface) 方法的端口解析。这在解析多个使用同一绑定的 WSDL 端口或开发期间端口未知的情况下很有用。客户机必须在客户机部署描述符中说明它对服务端点接口的容器端口解析的依赖性。如果客户机部署描述符中没有说明解析接口端口参数的依赖性，容器可能会提供缺省的解析功能或抛出 ServiceException。

4.2.2.2 动态端口访问

客户机可以使用下面几种由客户机环境的 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] 规范以了解详细内容。

4.2.2.3 ServiceFactory

Web Services for J2EE 产品中不支持 JAX-RPC ServiceFactory 类。客户机必须按照第 4.2.1 节 服务查找中描述的方式使用 JNDI 查找来获取服务接口。

4.2.2.4 有完整 WSDL 的服务方法使用

如果客户机部署描述符中给出了完整的 WSDL 描述以及 JAX-RPC 映射文件，那么客户机开发者就可以使用服务接口的所有方法（除了第 4.2.2.7 节和第 4.2.2.8 节中描述的情况之外）。WSDL 中可能没有端口地址属性，也可能是虚值。

4.2.2.5 有部分 WSDL 的服务方法使用

如果客户机部署描述符中给出了部分 WSDL 定义，那么客户机开发者就可以使用下面服务接口方法。

Call createCall() throws ServiceException;
java.rmi.Remote getPort(java.lang.Class serviceEndpointInterface) throws ServiceException;
java.net.URL getWSDLDocumentLocation()
				

这里定义了一个不完整的 WSDL 定义，作为完全指定的 WSDL 文档，它不包括服务或端口元素。开发者所指定的 JAX-RPC 映射文件在这种情况下将不包括 service-interface-mapping。

如果服务接口的其它方法被调用，而开发者指定了部分的 WSDL 定义，那么容器就必须抛出 java.lang.UnsupportedOperationException。

4.2.2.6 没有 WSDL 的服务方法使用

如果客户机部署描述符中没有指定 WSDL 定义，那么客户机开发者就可以使用下面的服务接口方法：

     Call createCall() throws ServiceException;
				

如果部署描述符中没有指定 wsdl-file，那么就决不能指定 jaxrpc-mapping-file。

如果服务接口的其它方法被调用，而开发者没有指定 WSDL 定义，那么容器就必须抛出 java.lang.UnsupportedOperationException。

4.2.2.7 处理程序

组件不应使用 getHandlerRegistry() 方法。容器提供者必须从服务接口的 getHandlerRegistry() 方法抛出 java.lang.UnsupportedOperationException。处理程序支持在第 6 章 处理程序中描述。

4.2.2.8 类型映射

组件不应使用 getTypeMappingRegistry() 方法。容器提供者必须从服务接口的 getTypeMappingRegistry() 方法抛出 java.lang.UnsupportedOperationException。

4.2.3. 端口存根和动态代理

4.2.3.1 标识

端口存根和动态代理是客户机的 Web 服务表示。与存根或代理进行通信的端口在客户机视图中没有标识。equals() 方法不能用于比较两个存根或代理实例以确定它们是否代表同一个端口。存根的 equals()、hash() 和 toString() 方法的结果是未指定的。客户机无法确保端口存根、动态代理或调用在多次调用中会访问某个特定的端口实例或者同一个端口实例。

4.2.3.2 类型强制转型

尽管我们认为存根和动态类是远程（Remote）对象，但客户机并不需要使用 PortableRemoteObject.narrow(...)。然而，我们鼓励客户机使用 PortableRemoteObject.narrow(...) 来防止与其它远程对象的客户机使用发生混淆。

4.2.4. JAX_RPC 属性

J2EE 容器环境改变了 JAX-RPC 中定义的支持存根／代理属性所需的条件。

4.2.4.1 可选的属性

容器提供者不需要支持下面 javax.xml.rpc.Stub 和 javax.xml.rpc.Call 接口上的属性。如果 setProperty() 方法是通过使用下面的属性调用的，而且存根实现不支持属性，那么存根就必须抛出 java.lang.UnsupportedOperationException 异常。

USERNAME_PROPERTY 以及 PASSWORD_PROPERTY — 客户机管理的凭证传播属性。

容器提供者不需要支持存根实现上的 USERNAME_PROPERTY 和 PASSWORD_PROPERTY 属性。容器提供者负责获取凭证信息并根据给定请求的认证需求将其传送到服务器。举例来说，当提交一条 HTTP 请求以访问 Web 服务，而服务器被配置为需要 HTTP Basic 认证时，那么容器就必须获取用户标识和密码，并将 HTTP 授权（Authorization）头添加到 HTTP 请求。在 HTTP 请求需要客户机证书的情况下，容器负责用共用的 SSL 建立 HTTPS 连接，方法是让底层 SSL 层能够访问客户机证书。

J2EE 1.3 规范的第 9.2 节描述了客户机能够用来以编程方式通过实现 javax.security.auth.callback.CallbackHandler 接口向容器提供认证信息的机制。

SESSION_MAINTAIN_PROPERTY — 会话管理配置。

容器提供者不需要支持存根实现上的 SESSION_MAINTAIN_PROPERTY 属性。参与 HTTP 会话的容器管理和配置是特定于容器实现以及最终用户需求的。容器一般会为最终用户提供一种方法来选择是否希望参与 HTTP 会话，但对定义这一点没有标准要求。

参与 HTTP 会话特定于 JAX-RPC 服务端点模型，并不一定适合实现 Web 服务的会话 EJB 模型。如果客户机调用了需要参与 HTTP 会话的 Web 服务，而客户机被配置为不参与 HTTP 会话，那么它就会接收到错误。

4.2.4.2 所需的属性

ENDPOINT_ADDRESS_PROPERTY — 动态端点地址分配。

容器提供者需要支持 ENDPOINT_ADDRESS_PROPERTY，从而使组件能够动态地将存根／代理重定向至不同的 URI。

4.2.5. JAX-RPC 定制序列化程序／反序列化程序

JAX-RPC 定制序列化程序／反序列化程序的使用不在规范的这个版本的讨论之列。JAX-RPC 定制序列化程序／反序列化程序不能在 Web Services for J2EE 提供者之间移植，因此也不属于可移植部署单元的一部分。我们希望在 JAX-RPC 的将来版本解决该问题之前，提供商将为此问题提供专门的解决方案。

4.2.6. 打包

开发者要负责通过容纳或引用的方式，对 WSDL 文件、服务端点接口类、生成的服务接口类（如果使用了该类）、它们相关的类、JAX-RPC 映射文件以及 J2EE 模块中的 Web 服务客户机部署描述符进行打包。模块中 Web 服务客户机部署描述符的位置特定于模块。WSDL 文件的位置相对于模块的根，而且一般与模块的部署描述符并列。JAX-RPC 映射文件位于模块根结构的相对位置，而且一般与 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 实例为请求提供服务。

5.3.2.1 EJB 编程模型

无状态会话 Bean，如 [EJB] 规范的第 7.8 到 7.10 节中所定义，可以用来实现将在 EJB 容器中部署的 Web 服务。

无状态会话 Bean 不必担心多线程访问。EJB 容器需要通过服务实现 Bean 的任意实例来对请求流进行序列化。

这里将部分重复对创建服务实现 Bean 作为无状态会话 EJB 的要求。

• 服务实现 Bean 必须有缺省的公开构造函数

• 服务实现 Bean 可以实现服务端点接口，但并非必须如此。bean 必须实现 SEI 所有的方法说明。服务实现 Bean 方法不需要抛出 javax.rmi.RemoteException。bean 的业务方法必须是公开的，而且绝不能是最终或静态的。它可以实现除 SEI 所定义的方法之外的其它方法。

• 服务实现 Bean 必须是无状态对象。服务实现 Bean 绝不能在各方法调用之间保存特定于客户机的状态，不管是在 bean 实例的数据成员中还是在实例外部都不可以。

• 类必须是公开的，绝不能是最终的，也绝不能是抽象的。

• 类绝不能定义 finalize() 方法。

• 目前，它必须实现不接受参数的 ejbCreate() 和 ejbRemove() 方法。这是 EJB 容器的要求，不过一般可以用空的实现来排除。

5.3.2.1.1 所需的会话 Bean 接口

目前，无状态会话 Bean 必须直接或间接地实现 javax.ejb.SessionBean 接口。

该接口使容器能够在其状态中通知服务实现 Bean 即将发生的错误。Enterprise JavaBean 规范 2.0 的第 7.5.1 节中定义了该接口的全部需要。

5.3.2.1.2 允许的对容器服务的访问

[EJB] 规范的第 7.8.2 节定义了允许的容器服务访问要求。

5.3.2.1.3 公开已有的 EJB

已有的 Enterprise JavaBean 如果符合下面的要求，就可以作为服务实现 Bean 使用：

• EJB bean 类的业务方法必须满足第 5.3.1 节 服务端点接口中定义的服务实现 Bean 的要求。

• 服务端点接口方法必须是 EJB 的远程接口方法的一个子集，而且 SEI 必须符合 Java 到 WSDL 映射的 [JAX-RPC] 规范中描述的要求。

• SEI 方法的事务属性绝不能包括强制属性。

开发者必须按照第 5.4 节 打包中描述的方式打包 Web 服务，而且必须指定从 Web 服务部署描述符中的端口到已有 EJB 的 ejb-link。

5.3.2.2 Web 容器编程模型

[JAX-RPC] 规范中使用的 JAX-RPC 服务端点一词有点令人迷惑，因为服务实现 Bean 都需要使用 JAX-RPC 运行时。然而，在这种情况下它指的是用来创建在 Web 容器中运行的 Web 服务的 [JAX-RPC] 规范中定义的编程模型。我们在这里重复这个要求，并加以澄清。对 JAX-RPC 定义的编程模型的改变是在 J2EE 容器管理的环境中运行所需要的。

JAX-RPC 服务端点可以是单线程，也可以是多线程的。我们在这里说明并发性要求是作为编程模型的一部分。如果组件需要单线程访问，JAX-RPC 服务端点就必须实现 javax.servlet.SingleThreadModel。容器必须将实现 SingleThreadModel 接口的服务实现 Bean 的方法请求序列化。

服务实现 Bean 必须遵循 [JAX-RPC] 规范中概述的服务开发者要求，除非另行指出，否则以下面列出的为准。

• 服务实现 Bean 必须有一个缺省的公开构造函数。

• 服务实现 Bean 可以实现服务端点接口，但并非必须如此。bean 必须实现 SEI 的所有方法说明。bean 的业务方法必须是公开的（public），并且绝不可以是最终（final）的或静态（static）的。它可以实现除 SEI 所定义的方法之外的其它方法。

• 服务实现必须是无状态对象。服务实现 Bean 绝不能在各方法调用之间保存特定于客户机的状态，不管是在 bean 实例的数据成员中还是在实例外部都不可以。容器可以使用任何 bean 实例作为请求。

• 类必须是公开的，绝不能是最终的，也绝不能是抽象的。

• 类绝不能定义 finalize() 方法。

5.3.2.2.1 可选的 ServiceLifecycle 接口

Web 容器的服务实现 Bean 可以实现 java.xml.rpc.server.ServiceLifeCycle 接口：

     package javax.xml.rpc.server;
     public interface ServiceLifecycle {
     void init(Object context) throws ServiceException;
     void destroy();
     }
					

ServiceLifeCycle 接口使容器能够通知服务实现 Bean 即将发生的自身状态的改变。bean 可以使用通知来准备转换的中间状态。如果 bean 实现 ServiceLifeCycle 接口，容器就需要按照下面描述的方式调用 init 和 destroy 方法。

容器在开始将请求分派到 bean 的 SEI 方法之前，必须调用 init 方法。容器所提供的 init 方法参数值由 [JAX-RPC] 规范描述。bean 可以使用容器通知来使其中间状态准备好接收请求。

容器必须让 bean 知道它将通过调用 destroy 方法从容器的工作集中删除 bean 实例的意图。容器在请求正由 bean 实例处理时可能不会调用 destroy 方法。容器在 destroy 方法被调用后可能不会将其它请求分派到 bean 的 SEI 方法。

5.3.2.2.2 允许的对容器服务的访问

容器根据服务实现 Bean 的生命周期状态提供特定服务。下表描述了可以在 bean 的各种方法中访问的服务。如果 bean 试图访问不允许访问的容器服务，就会抛出 java.lang.IllegalStateException。

表 1：允许的对容器服务的访问

Bean 方法	允许的容器支持
构造函数
init	java:comp/env 的 JNDI 查找
destroy SEI 的业务方法	ServletEndpointContext 方法 资源管理器 enterprise bean

5.3.3. 服务实现 Bean 生命周期

服务实现 Bean 的生命周期由容器控制，如图 6 所示。容器调用的方法与容器／bean 有关，但一般来说是非常相似的。图 6 说明了 Web 容器中的生命周期。EJB 容器生命周期的描述可以在 [EJB] 规范的第 7.8.1 节中找到。

图 6. Web 容器中的服务实现 Bean 生命周期

容器向 WSDL 端口所定义的请求提供服务。它通过为 WSDL 端口地址创建侦听器、接受请求并将请求分派到服务实现 Bean 上实现这一点。在能够服务于请求之前，容器必须实例化一个服务实现 Bean 并使之准备好接受方法请求。

容器准备 bean 实例的方法是：首先调用服务实现 Bean 类上的 newInstance 来创建实例。容器然后调用与容器有关的服务实现 Bean 上的生命周期方法。对 Web 容器来说，如果服务实现 Bean 类实现 ServiceLifecycle 接口，它就调用实例上的 init 方法。对 EJB 容器来说，它将调用 setSessionContext 和 ejbCreate 方法。

服务实现 Bean 实例没有标识。

容器可以对服务实现 Bean 的方法就绪（method ready）的实例进行池化，并将方法请求分派到处于方法就绪状态的任何实例上。

容器通过调用实例上特定于容器／bean 的生命周期方法来通知服务实现 Bean 实例它将被从方法就绪状态删除。对于 Web 容器来说将调用 destroy 方法。对于 EJB 容器来说将调用 ejbRemove 方法。

5.3.4. JAX-RPC 定制序列化程序／反序列化程序

JAX-RPC 定制序列化程序／反序列化程序的使用不在规范的这个版本的讨论之列。JAX-RPC 定制序列化程序／反序列化程序不能在 Web Services for J2EE 提供者之间移植，因此也不属于可移植部署单元的一部分。我们希望在 JAX-RPC 的将来版本解决该问题之前，提供商将为此问题提供专门的解决方案。

5.4.1. EJB 模块打包

无状态会话 EJB 服务实现 Bean 打包成包含类文件和 WSDL 文件的 EJB-JAR。打包规则遵循那些由 Enterprise JavaBean 规范定义的规则。另外，Web 服务部署描述符在 EJB-JAR 文件中的位置是 META-INF/webservices.xml。

5.4.2. Web 应用程序模块打包

JAX-RPC 服务端点打包在包含类文件和 WSDL 文件的 WAR 文件中。WAR 文件的打包规则是由 Servlet 规范定义的。Web 服务部署描述符在 WAR 中位于 WEB-INF/webservices.xml。

5.4.3. EAR 文件中的装配

将包含端口组件的模块装配成 EAR 文件遵循 J2EE 规范定义的要求。

6.2.1. 适用情况

处理程序必须能够支持以下几种情况：

第 1 种情况：处理程序必须能够转换 SOAP 头。一个例子是用处理程序添加特定于应用程序的信息（如 customerID）的 SOAP 头。

第 2 种情况：处理程序必须能够只转换主体的部件。这可能包括改变 SOAP 主体中的部件值。这种情况的例子是对某些参数值的加密。

第 3 种情况：处理程序必须能够只读取消息，而不对消息进行添加、转换或修改。常用的情况有日志纪录、测量和记帐。

6.2.2. 编程模型

Web Services for J2EE 提供者需要提供下面的 javax.xml.rpc.handler 包的接口和类。

• Handler

• HandlerRegistry

• MessageContext

• GenericHandler

• HandlerInfo

不需要提供 HandlerChain 接口。HandlerChain 的功能以特定于容器的方式提供。它不被应用程序代码使用。容器提供者不需要使用 HandlerChain 接口来实现链功能。

HandlerInfosetHandlerConfig() 和 getHandlerConfig() 方法不影响容器的处理程序请求处理。

Web Services for J2EE 提供者需要提供 HandlerRegistry 的实现。该功能是特定于容器的。

Web Services for J2EE 提供者需要提供 MessageContext 的实现。

Web Services for J2EE 提供者需要提供 javax.xml.rpc.handler.soap 包的所有接口。提供者还必须提供 SOAPMessageContext 接口的实现。

按照第 5.3.2.1 节 EJB 容器编程模型和第 5.3.2.2 节 Web 容器编程模型中所定义，Port 组件的编程模型可以是单线程的，也可以是多线程的。JAX-RPC 处理程序的并发性必须符合与其关联的业务逻辑的并发性。根据访问 Port 的不同业务逻辑，客户机处理程序可能需要支持多线程执行。

处理程序必须使用装入应用程序代码所使用的相同的类装入器来装入。类装入规则遵循为处理程序运行所在的容器定义的规则。

6.2.2.1 处理程序生命周期

处理程序的生命周期由容器控制，图 7 中说明了它。

图 7. 处理程序生命周期

处理程序接口的 init 和 destroy 方法允许容器通知应用程序实例它的状态即将改变。处理程序可以使用这个通知来为它的内部状态过渡作准备。容器需要调用 init 和 destroy 方法，如下所述。

容器必须先调用 init 方法，然后才能够开始将请求分派给处理程序的 handleRequest()、handleResponse() 和 handleFault() 方法。处理程序可以使用容器通知来准备好它的内部状态，以接收请求。

容器必须通知处理程序它想调用 destroy 方法来从容器的工作集中删除该处理程序实例。在请求正在被处理程序实例处理时，容器绝对不可以调 destroy 方法。在调用了 destroy 方法之后，容器绝对不可以再分派额外的请求给处理程序接口的方法。

正如 JAX-RPC 所定义的，从处理程序的任何方法抛出的 RuntimeException（不是 SOAPFaultException）都会导致 destroy 方法被调用并且过渡到“Does Not Exist”状态。

池化处理程序实例是允许的，但不是必须的。如果处理程序实例被池化，那么用端口组件池化它们。这是因为处理程序可以跨方法调用（这些方法调用特定于端口组件）保持特定于非客户机的状态。举例来说，处理程序可能会用特定于端口组件的环境变量值来初始化内部数据成员。当单个处理程序类型与多个端口组件关联时，这些值可能会不一致。端口组件的处理程序的任何处于方法就绪状态的池化后的实例都可以用来为 handleRequest()、handleResponse() 和 handleFault() 方法服务。不要求同一个处理程序实例同时为任何给定请求的 handleRequest() 和 handleResponse() 或 handleFault() 方法调用服务。

6.2.2.2 安全性

与一个端口组件关联的多个处理程序在授权之后，服务实现 bean 的业务逻辑方法被分派出去之前运行。对于 JAX-RPC 服务端点，处理程序在容器执行完与定义端口组件的 servlet 元素相关联的安全性约束检查之后运行。对于基于 EJB 的服务实现，处理程序在发生了方法级的授权之后运行。

处理器绝对不可以以任何会导致先前执行过的授权检查以不同方式执行的方式更改消息。Handler.handleRequest() 绝对不可以更改操作名、消息中部件的数量或者消息部件的类型。如果处理程序做了这样的事，那么容器就必须将 java.rmi.MarshalException 或 java.rmi.UnmarshalException 抛给客户机。尽管主要不是由于安全性原因，但 Handler.handleResponse() 方法绝对不可以更改消息中的部件数量或消息的部件类型。如果处理程序做了这样的事，那么容器就必须将 MarshalException 或 UnmarshalException 抛给客户机。由于客户机可能不期望得到响应（即可能是一个单向调用），所以容器应该记录这些错误的发生情况。

如果授权仅仅基于 MessageContext 和组件的环境变量值，那么处理程序可能会执行编程式授权检查。处理程序既不能执行基于角色的编程式授权检查，也不能访问与请求相关联的 Principal。

处理程序的 Java 2 安全性权限与运行该处理程序的容器所定义的权限相同。应用程序客户机、Web 和 EJB 容器可能具有不同的权限。如果提供者允许按每应用程序对权限进行定义，那么授予处理程序的权限由授予应用程序代码（该处理程序与这些代码包装在一起）的权限定义。请参阅 J2EE 1.3 规范的 J2EE.6.2.3 一节了解更多详情。

6.2.2.3 事务

处理程序在未特别指定的事务上下文中运行。

处理程序通常和与事务有关的 Servlet 过滤器满足相同的要求。处理程序绝对不可以使用 javax.transaction.UserTransaction 接口给事务划定界限。处理程序必须以本地事务模式使用事务资源，但不应该在任何对象的用来打包 MessageContext 的方法中使用事务资源。

6.2.3. 开发者职责

不要求开发者实现处理程序。处理程序是编写与处理 Web 服务请求有关的业务逻辑的另一种手段。一个开发者可以实现零个或多个与 Port 组件和／或服务引用相关联的处理程序。如果一个开发者实现了一个处理程序，则它们都必须满足本节所概述的要求。

处理程序作为无状态实例实现。在处理（handle）方法的多个调用之间，处理程序不在它的实例变量中维护任何与消息处理（特定于客户机的）有关的状态。

处理程序类必须实现 java.xml.rpc.handler.Handler 接口。

Handler.handleXXX() 方法可以使用“java:comp/env”上下文的 JNDI 查找，并且可以通过执行 JNDI 查找访问部署描述符中定义的 env-entry-names，这样便可以访问组件的环境实体。详情请参阅 [EJB] 规范的第 20 章。如果从任何其它处理程序方法访问环境并且环境不可用，那么容器就会抛出 java.lang.IllegalStateException。此外，处理程序可以使用 HandlerInfo.getHandlerConfig() 方法来访问处理程序的 init-params，init-params 在部署描述符中定义。

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 节中的处理顺序。

要求容器提供 HandlerInfo 实例中的 java.util.Map 对象的实例。HandlerInfo.getHeaders() 方法必须返回部署描述符中定义的 soap-headers 的设置。Map 对象必须提供对处理程序的各个 init-param 名称／值对的访问，这些名称／值对在部署描述符中被声明为 java.lang.String 值。容器必须为每一个处理程序实例提供唯一的 HandlerInfo 实例和映射配置（Map config）实例。必须为部署描述符中声明的每一个端口组件提供一个唯一的处理程序实例。

容器必须在端口组件的环境的上下文中调用 init() 方法。容器必须确保端口组件的 env-entrys 被设置为供 init 方法访问。

容器必须提供请求类型独有的 MessageContext 类型。例如，在处理 SOAP 请求时，容器必须给处理程序链中的处理程序的 handle<action>() 方法提供一个 SOAPMessageContext。这个 SOAPMessageContext 必须包含完整的 SOAP 消息。

容器必须跨所有处理程序实例和在单个请求和响应或在特定节点上进行的故障处理期间被调用的目标端点共享同一个 MessageContext 实例。

容器在调用处理程序链的 handle<action>() 方法之前必须设置端口组件的执行环境。各个处理程序在同一个执行环境下作为端口组件的业务方法运行。需要这样做处理程序才能够访问端口组件的 java:comp/env 上下文。

不要求容器提供者支持在 EJB 容器中运行的端口组件的处理程序。人们期望当本规范被包含到 J2EE 1.4 中时，会要求这一点。

6.4.1. 客户机 Web 服务方法访问

图 8. 客户机方法调用处理程序对象交互图

6.4.2. EJB Web 服务方法调用

图 9. EJB Web 服务方法调用处理程序处理之第 1 部分

7.1.1. 概述

webservices.xml 部署描述符文件定义了将部署到启用了 Web Services for J2EE 的容器中的 Web 服务集合。webservices.xml 部署描述符文件的打包在第 5.4.1 节 EJB 模块打包和第 5.4.2 节 Web 应用程序模块打包中定义。按照第 3.2 节 Web 服务中所描述，Web 服务是由 WSDL 文档所定义的。部署描述符定义了 WSDL 端口与端口组件之间的关系。端口组件在第 5 章 服务器编程模型中定义。

7.1.2. 开发者职责

开发者不但要负责 Web 服务的实现，还要负责声明其部署特征。部署特征在特定于模块的部署描述符以及 webservices.xml 部署描述符两者中定义。使用无状态会话 bean 的服务实现必须使用 session 元素在 ejb-jar.xml 部署描述符中定义。使用 JAX-RPC 服务端点的服务实现必须使用 servlet-class 元素在 web.xml 部署描述符中定义。请参阅 [EJB] 和 Servlet 2.3 规范以了解其它关于开发者对定义部署描述符的要求的详细内容。开发者还需要提供在 webservices.xml 部署描述符文件中定义端口组件的结构信息。开发者负责提供描述将部署的 Web 服务的 WSDL 文档集合、表示 Web 服务的 Java 类以及在两者之间建立关系的映射。

开发者负责在 webservices.xml 部署描述符中提供下面的信息：

• 端口的名称。开发者必须使用端口-组件-名称（port-component-name）元素为端口指定逻辑名称。这个名称与 WSDL 端口名称没有任何关系。这个名称在模块中的所有端口组件名称中必须是唯一的。

• 端口的 bean 类。开发者使用部署描述符的 service-impl-bean 元素声明 Web 服务的实现。这个元素中声明的 bean 指的必须是实现端口的服务端点接口的方法。这个元素使您可以选择实现。对于 JAX-RPC 服务端点来说，servlet-link 元素将 port-component 关联到 Web.xml 中 servlet-class 元素定义的 JAX-RPC 服务端点类。对于无状态会话 bean 实现来说，ejb-link 元素将 port-component 关联到 ejb-jar.xml 中的一个 session 元素。ejb-link 元素所指的可能不是另一个模块中定义的 session 元素。

• 端口的服务端点接口。开发者必须在 service-endpoint-interface 中指定服务端点接口的完全限定类名。您可以在第 5.3.1 节 服务端点接口中找到服务端点接口要求。

• 端口的 WSDL 定义。wsdl-file 元素指定一组 Web 服务的 WSDL 描述的位置。它位于模块根结构的相对位置，而且必须由开发者指定。

• 端口的 QName。除了指定 WSDL 文档之外，开发者还必须在 wsdl-port 元素中为部署描述符中定义的每个端口指定 WSDL 端口 QName。

• JAX-RPC 映射。开发者必须使用 jaxrpc-mapping-file 元素指定 WSDL 定义与接口之间的相关性。第 7.3. 节 JAX-RPC 映射部署描述符中讨论了在 jaxrpc-mapping-file 中指定信息的要求。对于和一个 wsdl-file 关联的所有接口必须使用同一个映射文件。

• 处理程序。开发者可以选择使用 handler 元素指定与 port-component 关联的处理程序。

请注意，如果 WSDL 在端口中指定了地址语句，它的 URI 地址就会被忽略。这个地址是在部署期间在部署的 WSDL 中生成并被取代的。

还是请参阅第 7.2.2 节 开发者职责中定义的开发者要求。

7.1.3. 装配者职责

Web Services for J2EE 的装配者的职责是在 [EJB]、Servlet 2.3 和 J2EE 1.3 规范定义的装配者职责上进行了扩展。装配者通过组成多个模块、分析模块间的依赖性并生成 EAR 文件，从而创建一个可部署的构件。

装配者可以修改下面由开发者在 webservices.xml 部署描述符文件中指定的任何信息：

• 描述字段。装配者可以修改已有的或创建新的 description 元素。

• 处理程序。装配者可以改变已有 param-value 元素的值、可以改变或添加 init-param 元素、可以改变或添加 soap-header 元素或添加 soap-role 元素，也可以添加新的处理程序元素（handler elements）。

还请参阅第 7.1.3 节 装配者职责中定义的装配者职责。

7.1.4. 部署者职责

部署者的职责是由 J2EE 1.3、[EJB] 以及 Servlet 2.3 规范所定义的。

另外，部署者必须分析下面的信息：

• 发布后的 WSDL 定义在什么位置。部署者必须用正确的端口地址属性值发布每个 webservice-description wsdl-file 以访问服务。

• 部署后的服务的端口地址属性值。

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.1. 概述

webservicesclient.xml 部署描述符包含服务引用条目。这些条目声明 Web、EJB 或应用程序客户机容器中 J2EE 组件所使用的对 Web 服务的引用。如果 Web 服务客户机为 J2EE 组件，那么它就使用 Web 服务的逻辑名称（称为服务引用）来查找服务。任何使用 Web 服务引用的组件都必须在 webservicesclient.xml 部署描述符文件中声明 Web 服务引用的相关性。webservicesclient.xml 文件与模块的部署描述符打包在同一个目录下。至于 WAR 模块，它打包在 WEB-INF 目录中。而 EJB JAR 和应用程序客户机模块则打包在 META-INF 目录下。

7.2.2. 开发者职责

开发者要负责为模块内的组件希望引用的每个 Web 服务定义一个 service-ref。它包括下面的信息：

• 服务引用名。它为客户机源代码中使用的引用定义了逻辑名称。我们推荐让名称以 service/ 开头，但不是必需的。

• 服务类型：service-interface 元素定义了 JNDI 查找返回的 JAX-RPC 服务接口类的完全限定名。

• 端口。开发者使用 port-component-ref 元素为容器受管的端口解析声明要求。port-component-ref 元素将被容器解析为 WSDL 端口。请参阅第 4 章 客户机编程模型，那里有一个关于容器受管端口访问的讨论。

• 作用域。如果 EJB-JAR 中定义了服务引用，那么 service-ref 元素就必须在 component-scoped-refs 元素中定义，这样 service-ref 才能够与特定的 EJB 关联。与 EJB 的关联是由 component-name 元素定义的。

开发者指定下面的信息：

• WSDL 定义。wsdl-file 元素服务的 WSDL 描述的位置。它位于模块根结构的相对位置。WSDL 描述可能是部分的 WSDL，但必须至少包括 portType 和 binding 元素。开发者所提供的 WSDL 描述可以被视为必须由装配／部署过程保留的模板。换句话说，WSDL 描述包含应用程序与端口类型、绑定和 QName 的相关性的声明。如果应用程序依赖于端口 QName（例如使用 Service.getPort(QName,Class) 方法），WSDL 文档就必须被完全指定，包括服务和端口元素。如果使用了第 4 .2.2.4 节或第 4.2.2.5 节中声明的任何服务方法，开发者就必须指定 wsdl-file。

• 服务端口。如果指定的 wsdl-file 有不止一个 service 元素，开发者就必须指定 service-qname。

• JAX-RPC 映射。开发者通过使用 jaxrpc-mapping-file 元素指定 WSDL 定义到接口的关系。它位于模块根结构的相对位置。对于和一个 wsdl-file 关联的所有接口必须使用同一个映射文件。如果指定了 wsdl-file，那么开发者必须指定 jaxrpc-mapping-file。

• 处理程序。开发者可以选择使用 handler 元素指定与 service-ref 关联的处理程序。

7.2.3. 装配者职责

除了 J2EE 1.3 规范中定义的职责之外，装配者还可以定义下面的信息：

• 服务引用的绑定。 装配者可以使用 port-component-link 元素将 Web 服务引用链接到 J2EE 应用程序单元中的组件。

装配者可以修改下面由开发者在 webservicesclient.xml 部署描述符中指定的任何信息：

• 描述字段。 装配者可以修改已有的或创建新的 description 元素。

• 处理程序。装配者可以改变已有 param-value 元素的值、可以添加新的 init-param 元素、可以改变或添加 soap-header 元素、可以改变或添加 soap-role 元素，也可以添加新的 handler 元素。

• WSDL 定义。装配者可以用一个新的 WSDL（它将找回丢失的服务和端口元素或丢失的端口地址属性）来代替已有的 WSDL 定义。装配者可以更新端口地址属性。

7.2.4. 部署者职责

除了担负 J2EE 部署者平台角色的普通任务之外，部署者还必须提供部署时绑定信息来为每个 service-ref 解析 WSDL 文档。

7.2.5. webservicesclient.xml DTD

webservicesclient.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.1. 概述

JAX-RPC 映射部署描述符没有标准的文件名。模块中的 WSDL 文档和映射文件具有一一对应关系。JAX-RPC 映射部署描述符包含在 Java 接口和 WSDL 定义之间建立映射关系的信息。部署工具使用该信息，结合 WSDL 文件生成部署的服务和服务引用的存根和 TIE。

7.3.2. 开发者职责

开发者在 WSDL 和／或 Java 接口被创建的同时创建映射文件。如果满足了下面的条件，开发者就可以仅指定打包映射。

• WSDL 文件必须包含正好一个 service 元素。

• service 元素必须定义正好一个端口。

• service 名称、binding 名称、portType 名称以及所有根 WSDL 类型（例如 complexType、simpleType 等）名称都必须是唯一的。

• port's binding 必须是 style="rpc" 的 soap 1.1 绑定；它的所有操作都必须指定 use="encoded", encodingStyle="<the SOAP 1.1 encoding>" 作为输入、输出和错误消息，而且要么省略部件属性，要么包括部件属性，总之要让输入和输出消息的所有部件都映射到 soap 主体。而且，绑定中不能指定任何 soap 头或头错误。

• 每个 operation 都必须：

  • 有遵循 Java 方法名称约定的唯一名称（在它所属的端口类型上下文中）。

  • 正好有一条输入消息。

  • 最多有一条输出消息。

  • 有零条或多条 fault 消息。

  • 要么没有 parameterOrder 属性，要么该属性的值为输入消息中所有部件的完整清单，顺序为输入消息中出现的顺序。

• 错误必须被映射到异常上，使得它：

  • 直接或间接地从 java.lang.Exception 继承，但决不能从 RuntimeException 继承，也不能从 RemoteException 继承。

  • 最多有一个单独属性名为“message”，类型为 java.lang.String，带有对应的单个 String 参数的构造函数。

  • 必须是 SOAP 编码的。

• 每条输入消息都必须有零或多个部件。

• 每条输入消息都必须有零或一个部分。如果有，部件的名称必须有别于输入消息中的任何部件。

• 每个部件必须是下面这种形式：

  <part name="..." type="T"/>

• 每种类型 T 都必须是下面的有效类型之一：

  • [JAX-RPC] 规范的第 4.2.1 节的表 4-1 中所定义的简单类型。

  • 使用 sequence 组合器的复杂类型：

              <xsd:complexType name="T">
                 <xsd:sequence>
                        <xsd:element name="..." type="Tprime"/>
                 </xsd:sequence>
              </xsd:complexType>
    					

    或使用 all 组合器的复杂类型：

              <xsd:complexType name="T">
                 <xsd:all>
                        <xsd:element name="..." type="Tprime"/>
                 </xsd:all>
              </xsd:complexType>
    					

    不管哪种情况，元素声明都可以出现一次或多次，而且每个 Tprime 类型都必须有效。所有的元素名被映射为 JavaBean 属性，element 名遵循标准 JavaBean 属性命名约定，第一个字母小写，而 complexType 名遵循 Java 标准类名称约定，第一个字母大写。

  • 遵循这种形式的一个 SOAP 数组：

              <xsd:complexType name="...">
                 <xsd:restriction base="soapenc:Array"/>
                        <xsd:attribute ref="soapenc:arrayType"
                               wsdl:arrayType="Tprime[]"/>
                 </xsd:restriction>
              </xsd:complexType>
    					

    其中 Tprime 为有效类型，而且不是 SOAP 数组类型。

如果条件不满足，那么就必须指定完整的映射。对于每个根 WSDL 类型必须有一个 java-xml-type-mapping。必须为每个 WSDL 错误创建一个 exception-mapping。对于在具有开发者所使用的生成的服务接口的 WSDL 文件中的每个 service 元素，都必须有一个 service-interface-mapping。WSDL 文件中的端口类型和绑定的每个结合都必须有一个 service-endpoint-interface-mapping。WSDL 中定义的每个名称空间都必须有一个 package-mapping。

不管 WSDL 内容是什么，Web Services for J2EE 提供者都可以通过使用标准的 JAX-RPC WSDL 到 Java 的映射规则来解析映射，从而支持部件映射规范（例如不为每种方法提供 method-param-parts-mapping）。如果映射是指定的，它们优先于映射规则。这种部分映射是特定于供应商的，因此不能够被移植。

开发者必须定义 webservices.xml 或 webservicesclient.xml 部署描述符的 jaxrpc-mapping-file 元素，作为映射文件的位置。

开发者必须把映射文件和 WSDL 文件一起打包在模块中。

7.3.3. 装配者职责

装配者决不能改变 JAX-RPC 映射文件。

7.3.4. 部署者职责

部署者使用部署工具来部署模块中包含的服务和服务引用。部署工具必须使用 JAX-RPC 映射文件来为服务和服务引用生成存根和 TIE。

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 d