一. 创建 SOAP 消息

SOAP 消息的 XML 文档结构在前一篇文章中已有图示。其中，SAAJ APIs 中的 SOAPMessage 类表示一个 SOAP 消息，SOAPPart 类表示 SOAP part，SOAPEnvelope 接口表示 SOAP envelope，等等。很多 SAAJ APIs 的接口都继承了 DOM 接口。
当创建一个 SOAPMessage 时，该 SOAPMessage 会自动创建并包含 SOAP 消息所必须的部分：一个新的 SOAPMessage 对象会包含一个 SOAPPart 对象，这个 SOAPPart 则包含有一个 SOAPEnvelope 对象，该 SOAPEnvelope 对象会包含一个空的SOAPHeader 对象，紧接着是一个空的 SOAPBody 对象。SOAPHeader 在 SOAP 消息中是可选的，这里之所以自动创建它，是因为我们在 SOAP 消息中经常会使用到它。

MessageFactory factory = MessageFactory.newInstance();
SOAPMessage message = factory.createMessage();

默认是创建 SOAP 1.1 的消息，如果想要创建 SOAP 1.2 消息，那么代码如下：

MessageFactory factory = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);

如果既想创建 SOAP 1.1 消息，又想创建 SOAP 1.2 消息，那么代码如下：

MessageFactory factory = MessageFactory.newInstance(SOAPConstants.DYNAMIC_SOAP_PROTOCOL
);

接着，向消息中添加内容。

首先取得 SOAPMessage 中的 SOAPPart 对象：

SOAPPart soapPart = message.getSOAPPart();

然后，我们从 SOAPPart 中取出 SOAPEnvelope 对象：

SOAPEnvelope envelope = soapPart.getEnvelope();

有了 SOAPEnvelope 对象，就可以得到它的 SOAPHeader 和 SOAPBody 了。

SOAPHeader header = envelope.getHeader();
SOAPBody body = envelope.getBody();

不过，你可能觉得做了这么多的工作才取得 SOAPHeader 和 SOAPBody 是不是太麻烦了？ SAAJ APIs 提供了便捷通道，直接通过 SOAPMessage 就可以获得 SOAPHeader 和 SOAPBody 对象：

SOAPHeader header = message.getSOAPHeader();
SOAPBody body = message.getSOAPBody();

由于 SOAPHeader 是可选的，如果你不需要它，便可以去掉它，可以使用 DOM 接口的方法来删除：

header.detachNode();

下面向 SOAPBody 对象中添加内容：

SOAPBody body = message.getSOAPBody();
QName bodyName = new QName("http://wombat.ztrade.com", "GetLastTradePrice", "m");
SOAPBodyElement bodyElement = body.addBodyElement(bodyName);
QName name = new QName("symbol");
SOAPElement symbol = bodyElement.addChildElement(name);
symbol.addTextNode("SUNW");

这时的 SOAPBody 内容如下所示：

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<m:GetLastTradePrice xmlns:m="http://wombat.ztrade.com">
<symbol>SUNW</symbol>
</m:GetLastTradePrice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

如果你有一个以文件形式存在的 SOAP 消息，那么如下方式会使用创建一个 SOAPMessage 更便捷：

DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
dbFactory.setNamespaceAware(true);
DocumentBuilder builder = dbFactory.newDocumentBuilder();
Document document = builder.parse("file:///music/order/soap.xml");
DOMSource domSource = new DOMSource(document);

SOAPPart soapPart = message.getSOAPPart();
soapPart.setContent(domSource);

当然，如果已有一个 DOM document，想将它通过 SOAP 发送出去，SAAJ APIs 也提供了便捷方式：

SOAPBody body = message.getSOAPBody();
SOAPBodyElement docElement = body.addDocument(document);

一个 SOAPMessage 可以包含一个或多个 attachment part，在 SAAJ APIs 中，使用 AttachmentPart 类表示 attachment part。由于 AttachmentPart 在 SOAPMessage 中是可选的，因此必须自己亲自动手去创建和添加它。如果一个 SOAPMessage 对象有一个或多个 attachments, 则每个 AttachmentPart 对象必须有一个 MIME header 用于指示它所包含的数据的类型。

二. 创建连接并发送 SOAP 消息

当消息已经创建好后，可以使用各种机制发送(例如JMS 或 JAXM)。在 SAAJ APIs 中，也提供了简单的发送机制。它使用 SOAPConnection 代表连接，SOAPConnection 对象是一中 point-to-point 连接，意味着它是直接从发送方到目标。
首先创建连接 SOAPConnection 对象：

SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection connection = soapConnectionFactory.createConnection();

发送消息：

java.net.URL endpoint = new URL("http://wombat.ztrade.com/quotes");
SOAPMessage response = connection.call(message, endpoint);

一个连接使用了相当多的资源，所以使用结束后应尽早关闭：

connection.close();

处理响应内容：

SOAPBody soapBody = response.getSOAPBody();
java.util.Iterator iterator = soapBody.getChildElements(bodyName);
SOAPBodyElement bodyElement = (SOAPBodyElement)iterator.next();
String lastPrice = bodyElement.getValue();
System.out.print("The last price for SUNW is ");
System.out.println(lastPrice);

三. 带附件的 SOAP 消息

SAAJ APIs 中有 3 种方式创建附件。
第一种：创建一个没有内容的附件

AttachmentPart attachment = message.createAttachmentPart();
String stringContent = "Update address for Sunny Skies " + "Inc., to 10 Upbeat Street, Pleasant Grove, CA 95439";
attachment.setContent(stringContent, "text/plain");
attachment.setContentId("update_address");
message.addAttachmentPart(attachment);

setContent 方法的第一个参数 Object 是附件内容，第二个参数 String 则是 MIME 内容类型。MIME 内容类型会写入到 AttachmentPart 的 Header，且这个 MIME content type 是唯一强制要有的。SAAJ 提供了 Content-Type, Content-Id, and Content-Location headers 的 getter 和 setter 方法。

另外 2 个 SOAPMessage.createAttachment 方法会创建带内容的附件。其中一个方法，其参数类似于 AttachmentPart.setContent，它的 Object 可以是一个 String, 一个 stream, 一个 javax.xml.transform.Source object, 或者一个 javax.activation.DataHandler object。
另外一个方法则需要参数 DataHandler object，来自于 JavaBeans Activation Framework (JAF) APIs. 使用一个 DataHandler object 是相当直观的。首先，为想要添加到附件中的文件创建一个 java.net.URL object。然后创建一个 DataHandler object：

URL url = new URL("http://greatproducts.com/gizmos/img.jpg");
DataHandler dataHandler = new DataHandler(url);
AttachmentPart attachment = message.createAttachmentPart(dataHandler);
attachment.setContentId("attached_image");
message.addAttachmentPart(attachment);

这里之所以没有设置 MIME content type header，是因为 DataHandler 会含有这方面的信息。

访问附件内容：

java.util.Iterator iterator = message.getAttachments();
while (iterator.hasNext()) {
AttachmentPart attachment = (AttachmentPart)iterator.next();
String id = attachment.getContentId();
String type = attachment.getContentType();
System.out.print("Attachment " + id + " has content type " + type);
if (type.equals("text/plain")) {
Object content = attachment.getContent();
System.out.println("Attachment contains:\n" + content);
}
}

四. 创建 SOAPFault
for SOAP 1.1

SOAPBody body = message.getSOAPBody();
SOAPFault fault = body.addFault();
QName faultName =
new QName(SOAPConstants.URI_NS_SOAP_ENVELOPE, "Server");
fault.setFaultCode(faultName);
fault.setFaultActor("http://gizmos.com/orders");
fault.setFaultString("Server not responding");

还可以向 SOAPFault 对象添加详细信息：

Detail detail = fault.addDetail();
QName entryName = new QName("http://gizmos.com/orders/", "order", "PO");
DetailEntry entry = detail.addDetailEntry(entryName);
entry.addTextNode("Quantity element does not have a value");
QName entryName2 = new QName("http://gizmos.com/orders/", "order", "PO");
DetailEntry entry2 = detail.addDetailEntry(entryName2);
entry2.addTextNode("Incomplete address: no zip code");

注意：一个 SOAPFault 对象只能有一个 Detail 对象。

获取 SOAPFault 信息：

SOAPBody body = newMessage.getSOAPBody();
if ( body.hasFault() ) {
SOAPFault newFault = body.getFault();
QName code = newFault.getFaultCodeAsQName();
String string = newFault.getFaultString();
String actor = newFault.getFaultActor();
System.out.println("SOAP fault contains: ");
System.out.println(" Fault code = " + code.toString());
System.out.println(" Local name = " + code.getLocalPart());
System.out.println(" Namespace prefix = " + code.getPrefix() + ", bound to " + code.getNamespaceURI());
System.out.println(" Fault string = " + string);
if ( actor != null ) {
System.out.println(" Fault actor = " + actor);
}

访问详细信息：

Detail newDetail = newFault.getDetail();
if (newDetail != null) {
Iterator entries = newDetail.getDetailEntries();
while ( entries.hasNext() ) {
DetailEntry newEntry = (DetailEntry)entries.next();
String value = newEntry.getValue();
System.out.println(" Detail entry = " + value);
}
}

五. 参考资料

1. The Java™ Web Services Tutorial (For Java Web Services Developer’s Pack, v2.0)

Related Posts:

• 2009/07/19 -- SMTP Transport Binding for SOAP
• 2009/07/07 -- Which style of WSDL should I use? (reship)
• 2009/10/15 -- Structures of SOAP with Attachments
• 2008/07/29 -- What’s New in WSDL 2.0
• 2008/07/19 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Custody and Ownership Transfer API Set

SOAP Message with No Attachments

—-

SOAP Message with Attachments

Related Posts:

• 2009/10/21 -- Tutorial of SOAP with Attachments API for Java
• 2009/07/19 -- SMTP Transport Binding for SOAP
• 2009/07/07 -- Which style of WSDL should I use? (reship)
• 2008/07/19 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Custody and Ownership Transfer API Set
• 2008/07/15 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Value Set API Set

soap:binding element 的 transport 属性需指定一个 http://xxx(例如:http://schemas.xmlsoap.org/soap/smtp) URL 来表明所要 binding 的 protocol. 似乎这个 URL 是任意形式, 只要能让调用方知道要使用什么协议即可. 在 soap:address 要给定 mailto:xxxx@xxx.xxx 这样形式的 URI.

    <service name="StockQuoteServiceBinding_service">
        <port name="StockQuoteServiceBinding_port"
                binding="binding:StockQuoteServiceBinding">
            <soap:address location="mailto:getQuote@test.com"/>
        </port>
    </service>

注意: 在 soap:address element 中, 可能会有一些扩展元素, 例如smtp server, smtp username, smtp password, etc.

在需要 request / response 语义情况下, 需使用标准的 Message-Id 和 In-Reply-To SMTP header 来实现这一目标. 请求包含一个 Message-Id header, 相应的响应则在 In-Reply-To header 中使用请求的 Message-Id header 值, 同时也创建一个新的 Message-Id header. 这样, 在请求与响应之间便建立了关联.

请求:

To: <soap@example.org>
 From: <soap@client.com>
 Reply-To: <soap@client.com>
 Date: Tue, 15 Nov 2001 23:27:00 -0700
 Message-Id: <1F75D4D515C3EC3F34FEAB51237675B5@client.com>
 MIME-Version: 1.0
 Content-Type: text/xml; charset=utf-8
 Content-Transfer-Encoding: QUOTED-PRINTABLE

 <?xml version=3D"1.0" encoding=3D"UTF-8"?>
 <SOAP-ENV:Envelope SOAP-ENV:encodingStyle=3D"http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENC=3D"http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENV=3D"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd=3D"http://www.w3.org/2001/XMLSchema"
 xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance">
 <SOAP-ENV:Body>
 <m:echoString xmlns:m=3D"http://soapinterop.org/">
 <inputString>get your SOAP over SMTP here !</inputString>
 </m:echoString>
 </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

响应:

To: <soap@client.com>
 From: <soap@example.org>
 Date: Tue, 13 Nov 2001 23:27:00 -0700
 In-Reply-To: <1F75D4D515C3EC3F34FEAB51237675B5@client.com>
 Message-Id: <FF75D4D515C3EC3F34FEAB51237675B5@soap.example.org>
 MIME-Version: 1.0
 Content-Type: TEXT/XML; charset=utf-8
 Content-Transfer-Encoding: QUOTED-PRINTABLE

 <?xml version=3D"1.0" encoding=3D"UTF-8"?>
 <SOAP-ENV:Envelope SOAP-ENV:encodingStyle=3D"http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENC=3D"http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:SOAP-ENV=3D"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd=3D"http://www.w3.org/2001/XMLSchema"
 xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance">
 <SOAP-ENV:Body>
 <m:echoStringResponse xmlns:m=3D"http://soapinterop.org/">
 <return>get your SOAP over SMTP here !</return>
 </m:echoStringResponse>
 </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Resources:

1. http://www.pocketsoap.com/specs/smtpbinding/
2. http://people.apache.org/~pzf/SMTPBase64Binding.html

Related Posts:

• 2009/07/07 -- Which style of WSDL should I use? (reship)
• 2008/07/19 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Custody and Ownership Transfer API Set
• 2008/07/15 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Value Set API Set
• 2008/07/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set
• 2008/07/07 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Publication API Set(3)

Date: 24 May 2005 (Published 31 Oct 2003)
Level: Advanced

Summary: A Web Services Description Language (WSDL) binding style can be RPC or document. The use can be encoded or literal. How do you determine which combination of style and use to use? The author describes the WSDL and SOAP messages for each combination to help you decide.

Introduction

A WSDL document describes a Web service. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use. This gives you four style/use models:

1. RPC/encoded
2. RPC/literal
3. Document/encoded
4. Document/literal

Add to this collection a pattern which is commonly called the document/literal wrapped pattern and you have five binding styles to choose from when creating a WSDL file. Which one should you choose?

Before I go any further, let me clear up some confusion that many of us have stumbled over. The terminology here is very unfortunate: RPC versus document. These terms imply that the RPC style should be used for RPC programming models and that the document style should be used for document or messaging programming models. That is not the case at all. The style has nothing to do with a programming model. It merely dictates how to translate a WSDL binding to a SOAP message. Nothing more. You can use either style with any programming model.

Likewise, the terms encoded and literal are only meaningful for the WSDL-to-SOAP mapping, though, at least here, the traditional meanings of the words make a bit more sense.

For this discussion, let’s start with the Java method in Listing 1 and apply the JAX-RPC Java-to-WSDL rules to it (see Resources for the JAX-RPC 1.1 specification).

Listing 1. Java method

public void myMethod(int x, float y);

RPC/encoded

Take the method in Listing 1 and run it through your favorite Java-to-WSDL tool, specifying that you want it to generate RPC/encoded WSDL. You should end up with something like the WSDL snippet in Listing 2.
Listing 2. RPC/encoded WSDL for myMethod

<message name="myMethodRequest">
    <part name="x" type="xsd:int"/>
    <part name="y" type="xsd:float"/>
</message>
<message name="empty"/>

<portType name="PT">
    <operation name="myMethod">
        <input message="myMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>

<binding .../>
<!-- I won't bother with the details, just assume it's RPC/encoded. -->

Now invoke this method with “5″ as the value for parameter x and “5.0″ for parameter y. That sends a SOAP message which looks something like Listing 3.
Listing 3. RPC/encoded SOAP message for myMethod

<soap:envelope>
    <soap:body>
        <myMethod>
            <x xsi:type="xsd:int">5</x>
            <y xsi:type="xsd:float">5.0</y>
        </myMethod>
    </soap:body>
</soap:envelope>

There are a number of things to notice about the WSDL and SOAP message for this RPC/encoded example:

Strengths

• The WSDL is about as straightforward as it’s possible for WSDL to be.
• The operation name appears in the message, so the receiver has an easy time dispatching this message to the implementation of the operation.

Weaknesses

• The type encoding info (such as xsi:type="xsd:int") is usually just overhead which degrades throughput performance.
• You cannot easily validate this message since only the <x ...>5</x> and <y ...>5.0</y> lines contain things defined in a schema; the rest of the soap:body contents comes from WSDL definitions.
• Although it is legal WSDL, RPC/encoded is not WS-I compliant.

Is there a way to keep the strengths and remove the weaknesses? Possibly. Let’s look at the RPC/literal style.

Related Posts:

• 2009/07/19 -- SMTP Transport Binding for SOAP
• 2008/07/29 -- What’s New in WSDL 2.0
• 2008/07/19 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Custody and Ownership Transfer API Set
• 2008/07/15 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Value Set API Set
• 2008/07/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set

1. 模块可分解性（Modular Decomposability）——如果一种软件构造方法能有助于把一个软件问题分解为若干较简单的子问题、并用一个简单的结构将这些子问题连接起来、而且能够独立地对各个子问题作进一步分解，那么该方法就满足模块可分解性。
2. 模块可组合性（Modular Composability）——如果一种方法，由它生产出的软件元素，未来可在不同于最初被开发的环境中通过彼此自由组合的方式来产生新的系统，那么该方法就满足模块可组合性。
3. 模块可理解性（Modular Understandability）——如果一种方法，由它生产出的软件，人类读者无需了解其他模块（或最多只需研究少许其他模块）便可理解每一个模块，那么该方法就有利于模块可理解性。
4. 模块连续性（Modular Continuity）——如果一种方法，在由它得到的软件架构中，功能规格上的微小改动只会引起一个（或少量）模块的变化，那么该方法就满足模块连续性。
5. 模块保护性（Modular Protection）——如果一种方法，在由它得到的架构中，一个模块在运行时出现异常条件不会影响到该模块之外（或最多只蔓延到少数周边模块），那么该方法就满足模块保护性。

服务的模块性:

1. 可分解性（Decomposability）——如果一种方法能有助于把一个软件问题分解为若干较简单的子问题、并用一个简单的结构将这些子问题连接起来、而且能够独立地对各个子问题作进一步分解，那么该方法就满足可分解性。
2. 可组合性（Composability）——如果一种方法，由它生产出的软件元素，未来可在不同于最初被开发的环境中通过彼此自由组合的方式来产生新的系统，那么该方法就满足可组合性。
3. 可理解性（Understandability）——如果一种方法，由它生产出的软件，人类读者无需了解其他模块（或最多只需研究少许其他模块）便可理解每一个模块，那么该方法就有利于可理解性。
4. 连续性（Continuity）——如果一种方法，在由它得到的软件架构中，功能规格上的微小改动只会引起一个（或少量）模块的变化，那么该方法就满足连续性。
5. 保护性（Protection）——如果一种方法，在由它得到的架构中，一个模块在运行时出现异常条件不会影响到该模块之外（或最多只蔓延到少数周边模块），那么该方法就满足保护性。
6. 自查性（Introspection）——如果一个方法，由它得到的架构提供了“允许在运行时查询并检查模块结构及模块间通信结构”的机制，那么该方法就满足自查性。
7. 远程性（Remoteability）——如果一个方法，由它得到的架构提供了“允许托管于不同物理环境下的不同模块与之进行模块通信”的机制，那么该方法就满足远程性。
8. 异步性（Asynchronicity）——如果一个方法，由它得到的架构不假定模块调用将被立即响应，那么该方法就满足异步性。换言之，它假定网络或被调用模块有延迟。
9. 面向文档（Document Orientedness）——如果一个方法，在由它得到的架构中，内部模块间的通信消息均是明确定义且互相知道的、而且各次调用之间不存在隐式的状态共享，那么该方法就是面向文档的。
10. 标准化的协议信封（Standardized Protocol Envelope）——如果一个方法，由它得到的架构要求所有模块通信都共用一种通用信封消息格式，那么该方法就满足标准协议信封。
11. 分散式管理（Decentralized Administration）——如果一个方法，由它得到的架构不需要对所有模块进行集中管理，那么该方法就符合分散式管理。

原文:

1. SOA定义的松耦合
2. Loose Coupling in SOA Defined

Related Posts:

• 2010/02/01 -- Differences between WADL and WSDL 2.0 HTTP binding
• 2009/10/21 -- Tutorial of SOAP with Attachments API for Java
• 2009/10/15 -- Structures of SOAP with Attachments
• 2009/09/25 -- 一个简单的 POJO factory 实现
• 2009/07/19 -- SMTP Transport Binding for SOAP

通过使用 Java™ API for XML Web Services (JAX-WS) 技术设计和开发 Web 服务，可以带来很多好处，能简化 Web 服务的开发和部署，并能加速 Web 服务的开发。通过此教程，可以了解如何开发将其功能作为 Web 服务公开的示例订单处理程序，从而进行所有这些工作以及其他任务。完成了此教程后，您将能够应用这些概念和新获得的知识，来使用 JAX-WS 技术为应用程序开发 Web 服务。

JAX-WS 简介

为何使用 JAX-WS？

JAX-WS 是用于简化使用 Java 构造 Web 服务和 Web 服务客户机的工作的技术。该技术提供了完整的 Web 服务堆栈，可减少开发和部署 Web 服务的任务。JAX-WS 支持 WS-I Basic Profile 1.1，后者可确保使用 JAX-WS 堆栈开发的 Web 服务能够供采用 WS-I Basic Profile 标准使用任意语言开发的任意客户机使用。JAX-WS 还包括了 Java Architecture for XML Binding (JAXB) 和 SOAP with Attachments API for Java (SAAJ)。

JAXB 提供了一种非常方便的方法来将 XML 模式映射到 Java 代码的表示形式，从而支持数据绑定功能。JAXB 消除了将 SOAP 消息中的 XML 模式消息转换为 Java 代码的工作，因而不必全面了解 XML 和 SOAP 解析。JAXB 规范定义 Java 和 XML 模式之间的绑定。SAAJ 提供了标准的方法来处理 SOAP 消息中包含的 XML 附件。

而且，JAX-WS 提供了用于将传统 Java 对象（Plain Old Java Object，POJO）类转换为 Web 服务的 Annotation 库，从而加速了 Web 服务的开发工作。另外，它还指定了从采用 Web 服务描述语言（Web Services Description Language，WSDL）定义的服务到实现该服务的 Java 类之间的详细映射。采用 WSDL 定义的任意复杂类型都通过遵循 JAXB 规范定义的映射来映射为 Java 类。JAX-WS 之前与 Java Platform, Enterprise Edition (Java EE) 5 绑定。而 JAX-WS 2.0 规范是作为 Java Community Process (JCP) 的 JSR 224 开发的。

开发 Web 服务

契约优先方法与代码优先方法

进入 JAX-WS 时代的最好方法莫过于首先开发一个 Web 服务。可以采用以下两种方法之一开发 Web 服务：

• 契约优先：从 WSDL 契约着手，生成 Java 类来实现服务。
• 代码优先：从 Java 类着手，使用 Annotation 来生成 WSDL 文件和 Java 接口。

契约优先 WSDL 方法需要对用于定义消息格式的 WSDL 和 XML 模式定义（XML Schema Definition，XSD）有良好的理解。如果您对 Web 服务相当陌生，最好从代码优先方法着手，本教程中将使用此方法开发 Web 服务。

代码优先 Web 服务开发

使用代码优先方法时，将从实现希望作为服务公开的功能的 Java 类或类入手。在已经提供了 Java 实现且需要将实现作为服务公开的情况下，代码优先方法尤为有用。

开发订单处理 Web 服务

让我们首先创建一个订单处理 Web 服务，用于接受订单信息、配送信息和订购物品并最终生成确认 ID 作为响应。订单处理服务的代码如清单 1 中所示。这是一个虚拟实现，将在控制台输出客户 ID 和物品数量，然后输出虚拟订单 ID A1234。（可以在本文的下载部分下载完整的应用程序源代码。）将源代码解压到 C 盘，会在其中创建一个名为 JAXWS-Tutorial 的文件夹。此文件夹包含对应的源代码，如清单 1 中所示。

清单 1. 订单处理 Web 服务实现

package com.ibm.jaxws.tutorial.service;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import com.ibm.jaxws.tutorial.service.bean.OrderBean;

//JWS annotation that specifies that the portType name of the
//Web service is "OrderProcessPort," the service name
//is "OrderProcess," and the targetNamespace used in the generated
//WSDL is "http://jawxs.ibm.tutorial/jaxws/orderprocess."

@WebService(serviceName = "OrderProcess",
        portName = "OrderProcessPort",
        targetNamespace = "http://jawxs.ibm.tutorial/jaxws/orderprocess")

//JWS annotation that specifies the mapping of the service onto the
// SOAP message protocol. In particular, it specifies that the SOAP messages
//are document literal.
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,use=SOAPBinding.Use.LITERAL,
            parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

public class OrderProcessService {

    @WebMethod
    public OrderBean processOrder(OrderBean orderBean) {

        // Do processing...
        System.out.println("processOrder called for customer"
                + orderBean.getCustomer().getCustomerId());

        // Items ordered are
        if (orderBean.getOrderItems() != null) {
            System.out.println("Number of items is "
                    + orderBean.getOrderItems().length);
        }

        //Process order.

        //Set the order ID.
        orderBean.setOrderId("A1234");

        return orderBean;
    }
}

OrderBean 中包含订单信息，如清单 2 中所示。具体来说，其中包含对客户、订单项和配送地址对象的引用。

清单 2. 包含订单信息的 OrderBean 类

package com.ibm.jaxws.tutorial.service.bean;

public class OrderBean {

    private Customer customer;

    private Address shippingAddress;

    private OrderItem[] orderItems;

    private String orderId;

    public Customer getCustomer() {
        return customer;
    }

    public void setCustomer(Customer customer) {
        this.customer = customer;
    }

    public String getOrderId() {
        return orderId;
    }

    public void setOrderId(String orderId) {
        this.orderId = orderId;
    }

    public Address getShippingAddress() {
        return shippingAddress;
    }

    public void setShippingAddress(Address shippingAddress) {
        this.shippingAddress = shippingAddress;
    }

    public OrderItem[] getOrderItems() {
        return orderItems;
    }

    public void setOrderItems(OrderItem[] orderItems) {
        this.orderItems = orderItems;
    }
}

开发 JAX-WS Web 服务的起点是一个使用 javax.jws.WebService Annotation 进行了标注的 Java 类。所使用的 JAX-WS Annotation 属于 Web Services Metadata for the Java Platform 规范 (JSR-181) 的一部分。您可能已经注意到了，OrderProcessService 使用 WebService Annotation 进行了标注，而后者将类定义为了 Web 服务端点。

OrderProcessService 类（带有 @javax.jws.WebService Annotation 的类）隐式地定义了服务端点接口（Service Endpoint Interface，SEI），用于声明客户机可以对服务调用的方法。除了使用 @WebMethod Annotation 标注且 exclude 元素设置为 true 的方法外，类中定义的所有公共方法都会映射到 WSDL 操作。@WebMethod Annotation 是可选的，用于对 Web 服务操作进行自定义。除了 exclude 元素外，javax.jws.WebMethod Annotation 还提供 operation name 和 action 元素，用于在 WSDL 文档中自定义操作的 name 属性和 SOAP action 元素。这些属性是可选的；如果未定义，会从类名称派生缺省值。

实现 Web 服务后，需要生成部署服务所需的所有构件，然后将 Web 服务打包为部署构件（通常为 WAR 文件），并将 WAR 文件部署到任何支持 JAX-WS 2.0 规范的兼容服务器上。通常生成的构件是提供基于服务接口将 Java 对象转换为 XML、WSDL 文件和 XSD 模式的功能的类。

出于测试目的，Java 6 绑定了一个轻量级 Web 服务器，可以通过调用简单的 API 调用将 Web 服务发布到该服务器上。接下来我们将了解如何使用此方法测试 Web 服务。

发布服务

生成 JAX-WS 构件

运行 wsgen 工具，以生成订单处理 Web 服务的 JAX-WS 可移植构件。此工具将读取 Web SEI 类，并生成 Web 服务部署和调用所需的所有构件。wsgen 工具生成需要发布的 Web 服务的 WSDL 文件和 XSD 模式。

为了生成 JAX-WS 构件，首先需要编译服务和 Bean 源文件：

• 打开命令提示符，并进入到 c:\JAXWS-Tutorial目录。
• 运行以下命令，以编译 Java 文件，并将类文件放入其各自文件夹中：

javac com\ibm\jaxws\tutorial\service\*.java com\ibm\jaxws\tutorial\service\bean\*.java

• 运行以下命令，以生成 JAX-WS 构件：

wsgen -cp . com.ibm.jaxws.tutorial.service.OrderProcessService -wsdl

wsgen 工具提供了大量的选项，例如，其中提供了 -wsdl 选项，用于生成服务的 WSDL 和模式构件。运行此命令后，应该在 JAXWS-Tutorial 文件夹中看到生成的 OrderProcess.wsdl 和 OrderProcess_schema1.xsd，而且会看到在 com\ibm\jaxws\tutorial\service\jaxws 文件夹中创建了 JAX-WS 构件。

生成了构件后，运行以下 Web 服务发布器客户机，以发布订单处理 Web 服务。

• 从 c:\JAXWS-Tutorial 文件夹运行以下命令，以编译 OrderWebServicePublisher：

javac com\ibm\jaxws\tutorial\service\publish\OrderWebServicePublisher.java

• 然后运行以下命令：

java com.ibm.jaxws.tutorial.service.publish.OrderWebServicePublisher

运行 Java 程序后，应该看到以下消息： The Web service is published at http://localhost:8080/OrderProcessWeb/orderprocess. To stop running the Web service, terminate this Java process.
这会将订单 Web 服务发布到 http://localhost:8080/OrderProcessWeb/orderprocess。可以通过显示订单处理 Web 服务生成的 WSDL 来验证 Web 服务是否在运行：

• 打开浏览器，并导航到 http://localhost:8080/OrderProcessWeb/orderprocess?wsdl。

分析 OrderWebServicePublisher

在分析 WSDL 和模式构件前，让我们分析一下 OrderWebServicePublisher 的代码。清单 3 提供了 OrderWebServicePublisher 客户机的源代码。
清单 3. 用于发布订单处理 Web 服务的代码

package com.ibm.jaxws.tutorial.service.publish;

import javax.xml.ws.Endpoint;

import com.ibm.jaxws.tutorial.service.OrderProcessService;

public class OrderWebServicePublisher {

    public static void main(String[] args) {

Endpoint.publish("http://localhost:8080/OrderProcessWeb/orderprocess",
                new OrderProcessService());

    }

}

通过 Endpoint.publish() 方法，可以方便地发布和测试 JAX-WS Web 服务。publish() 接受两个参数：Web 服务的位置和 JAX-WS Web 服务实现类。publish() 方法在指定的 URL（本例中为本地主机，端口为 8080）创建轻量级 Web 服务器，并将 Web 服务部署到该位置。此轻量级 Web 服务器在 Java 虚拟机（Java Virtual Machine，JVM）中运行，可通过调用 endpoint.stop() 方法以有条件的方式终止，或终止 OrderWebServicePublisher 客户机。

分析生成的 WSDL

要查看生成的订单处理 Web 服务 WSDL，在浏览器中键入以下 URL 位置： http://localhost:8080/OrderProcessWeb/orderprocess?wsdl.

让我们分析 WSDL 一些重要方面的内容，并了解如何基于 JAX-WS 元数据生成 WSDL 和模式构件，首先要分析的是生成的 XSD。此内容使用 xsd:import 标记导入到 WSDL 文件中（请参见清单 4）；schemaLocation 指定 XSD 的位置。
清单 4. 包含订单处理模式定义的 WSDL 文件
<types>
<xsd:schema>
<xsd:import namespace=”http://jawxs.ibm.tutorial/jaxws/orderprocess”
schemaLocation=”OrderProcess_schema1.xsd”/>
</xsd:schema>
</types>

在浏览器中打开 schemaLocation (http://localhost:8080/OrderProcessWeb/orderprocess?xsd=1)，以查看模式定义在浏览器中呈现的情况。让我们分析一下其中的情况：模式定义最开始是 targetNamspace 和 tns 声明，映射到在 OrderProcessService 的 @WebService Annotation 中定义的 targetNamespace http://jawxs.ibm.tutorial/jaxws/orderprocess。清单 5 给出了对应的代码。
清单 5. 模式（Schema）命名空间声明

<xs:schema version=”1.0″
targetNamespace=”http://jawxs.ibm.tutorial/jaxws/orderprocess”
xmlns:tns=”http://jawxs.ibm.tutorial/jaxws/orderprocess”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”>

前面指定的 wsgen 工具命令生成两个包装 Bean 类，ProcessOrder 和 ProcessOrderResponse，分别包含订单处理 Web 服务的输入和输出消息。将基于这些包装 Bean 类生成以下模式元素：

• processOrder 属于 processOrder 类型，表示其中包含一个元素，且此元素的名称为 arg0，类型为 orderBean。可以看到，在 ProcessOrder 类和 processOrder 复杂类型之间存在一对一映射。

• processOrderResponse 与 processOrderResponse 类型类似，后者的定义映射到 ProcessOrderResponse 类。

让我们仔细分析一下清单 6 中的代码。
清单 6. processOrder 的模式声明

<xs:element name=”processOrder” type=”tns:processOrder”/>
<xs:element name=”processOrderResponse” type=”tns:processOrderResponse”/>
<xs:complexType name=”processOrder”>
<xs:sequence>
<xs:element name=”arg0″ type=”tns:orderBean” minOccurs=”0″/>
</xs:sequence>
</xs:complexType>

清单 7 中所示的 orderBean 类型定义映射到 OrderBean 类。orderBean 类型定义包括：

• 一个 customer 元素，其类型为 customer。

• 一个 orderId，其类型为 string。

• orderItems（它为数组类型，因为其将 maxOccurs 属性指定为 unbounded），其类型为 orderItem。

• shippingAddress，其类型为 address。

清单 7. processOrder 的模式声明

<xs:complexType name=”orderBean”>
<xs:sequence>
<xs:element name=”customer” type=”tns:customer” minOccurs=”0″ />
<xs:element name=”orderId” type=”xs:string” minOccurs=”0″ />
<xs:element nillable=”true” maxOccurs=”unbounded” name=”orderItems”
type=”tns:orderItem” minOccurs=”0″ />
<xs:element name=”shippingAddress” type=”tns:address”
minOccurs=”0″ />
</xs:sequence>
</xs:complexType

类似地，模式的其余部分 customer、orderItems 和 address 分别映射到 Customer、OrderItem 和 Address Java Bean。
分析了模式定义后，接下来让我们回头来看看 WSDL 中的消息定义，如清单 8 中所示。WSDL 指定消息 processOrder 和 processOrderResponse，其所属的元素为 processOrder 和 processOrderResponse（我们已经讨论了其模式定义）。portType 指定操作 processOrder，其输入消息为 processOrder，而输出消息为 processOrderResponse。
清单 8. WSDL 文档中的 processOrder 消息元素

<message name=”processOrder”>
<part element=”tns:processOrder” name=”parameters” />
</message>
<message name=”processOrderResponse”>
<part element=”tns:processOrderResponse” name=”parameters” />
</message>
<portType name=”OrderProcessService”>
<operation name=”processOrder”>
<input message=”tns:processOrder” />
<output message=”tns:processOrderResponse” />
</operation>
</portType>

接下来定义了 WSDL 绑定。此绑定将 soap:binding 样式定义为 document，soap:body 使用 literal 标记指定操作 processOrder 的输入和输出消息格式。生成的 WSDL 定义映射到 @SOAPBinding Annotation（已在 OrderProcessService 类上定义，请参见清单 9）。
清单 9. WSDL 文档的绑定信息

<binding name=”OrderProcessPortBinding” type=”tns:OrderProcessService”>
<soap:binding style=”document” transport=”http://schemas.xmlsoap.org/soap/http” />
<operation name=”processOrder”>
<soap:operation soapAction=”" />
<input>
<soap:body use=”literal” />
</input>
<output>
<soap:body use=”literal” />
</output>
</operation>
</binding>

接下来定义 WSDL 服务。这将指定端口和对应的绑定类型，以及服务的实际位置。此位置通常为 HTTP 位置，在本例中为 http://localhost:8080/OrderProcessWeb/orderprocess。可以在清单 10 中了解到具体的情况。
清单 10. WSDL 文档的服务信息

<service name=”OrderProcess”>
<port name=”OrderProcessPort” binding=”tns:OrderProcessPortBinding”>
<soap:address location=”http://localhost:8080/OrderProcessWeb/orderprocess” />
</port>

我们已经对生成的 WSDL 和模式构件进行了分析。清单 11 给出了一个示例 SOAP 请求消息，此消息是在 Web 服务客户机调用 processOrder 操作时发送的。
清单 11. processOrder 操作的示例 SOAP 消息

<?xml version=”1.0″?>
<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:ns1=” http://jawxs.ibm.tutorial/jaxws/orderprocess”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
<soapenv:Body>
<ns1:processOrder>
<arg0>
<customer><customerId>A123</customerId>
<firstName>John</firstName><lastName>Smith</lastName></customer>
<orderItems><itemId>11</itemId><qty>11</qty></orderItems>
</arg0>
</ns1:processOrder>
</soapenv:Body>
</soapenv:Envelope>

创建 Web 服务客户机

从 WSDL 创建 Web 服务客户机

在本部分，我们将了解如何从 WSDL 创建 Web 服务客户机。JAX-WS 提供了名为 wsimport 的工具，用于从 WSDL 生成 JAX-WS 可移植构件。生成的可移植构件通常包括以下内容：

• SEI

• 服务（需要实现的服务实现类）

• 从模式类型生成的 JAXB 生成类

• 从 wsdl:fault 映射的异常类（如果有）

客户机使用生成的构件调用 Web 服务。Web 服务客户机并不需要处理任何 SOAP 格式（如创建或解析 SOAP 消息）。这将由 JAX-WS 运行时予以处理，此运行时将使用生成的构件代码（JAXB 生成类）。Web 服务将处理 Java 代码（JAXB 生成类），从而减少了开发 Web 服务客户机和对 Web 服务调用操作的工作。

先使用 wsimport 工具从 OrderProcess WSDL 生成 JAX-WS 构件。然后要创建 Web 服务客户机，后者使用生成的构件代码调用订单处理 Web 服务。要生成 JAX-WS 构件，贤进入到 JAXWS-Tutorial 目录，并运行清单 12 中所示的 wsimport 命令。不过，进行操作前，请确保已经按照生成 JAX-WS 构件部分中的步骤 5 所述的方法，通过运行 OrderWebServicePublisher 发布了 Web 服务。

清单 12. 用于生成供 Web 服务客户机使用的 JAX-WS 构件的 wsimport 命令

wsimport -keep -p com.ibm.jaxws.tutorial.service.client

http://localhost:8080/OrderProcessWeb/orderprocess?wsdl

-keep 选项指示保留生成的文件，-p 选项指定需要在其中生成构件的包名称。http://localhost:8080/OrderProcessWeb/orderprocess?wsdl 指定 WSDL 文件的位置。以下构件是从 OrderProcessService WSDL 生成的：

• JAXB 类（Address、Customer, OrderBean 和 OrderItem）：通过读取 OrderProcessService WSDL 中定义的模式定义生成

• RequestWrapper 和 ResponseWrapper 类（ProcessOrder 和 ProcessOrderResponse）：包装 document literal-wrapped 样式类型的输入和输出

• 服务类 (OrderProcess)：客户机用于请求 Web 服务的类

• 服务接口 (OrderProcessService)：包含着用于服务实现接口的类

接下来了解一下如何使用上面生成的构件创建 Web 服务客户机。com\ibm\jaxws\tutorial\service\client 文件夹中提供了一个示例参考代码。Web 服务客户机的代码如清单 13 中所示。
清单 13. 订单处理 Web 服务客户机的代码清单

package com.ibm.jaxws.tutorial.service.client;

import java.net.MalformedURLException;
import java.net.URL;

import javax.xml.namespace.QName;

public class OrderClient {

    final QName qName = new QName(
            "http://jawxs.ibm.tutorial/jaxws/orderprocess", "OrderProcess");

    public static void main(String[] args) {
        if (args.length != 1) {
            System.out
                    .println("Specify the URL of the OrderProcess Web Service");
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- XML error:  The previous line is longer than the max of 90 characters ---------|
            System.exit(-1);
        }
        URL url = getWSDLURL(args[0]);
        OrderClient client = new OrderClient();
        client.processOrder(url);
    }

    private static URL getWSDLURL(String urlStr) {
        URL url = null;
        try {
            url = new URL(urlStr);
        } catch (MalformedURLException e) {
            e.printStackTrace();
            throw new RuntimeException(e);
        }
        return url;
    }

    public void processOrder(URL url) {

        OrderProcess orderProcessingService = new OrderProcess(url, qName);

        System.out.println("Service is" + orderProcessingService);

        OrderBean order = populateOrder();

        OrderProcessService port = orderProcessingService.getOrderProcessPort();
        OrderBean orderResponse = port.processOrder(order);

        System.out.println("Order id is " + orderResponse.getOrderId());

    }

    private OrderBean populateOrder() {

        OrderBean order = new OrderBean();
        Customer customer = new Customer();
        customer.setCustomerId("A123");
        customer.setFirstName("John");
        customer.setLastName("Smith");
        order.setCustomer(customer);

        // Populate Order Item.
        OrderItem item = new OrderItem();
        item.setItemId("11");
        item.setQty(11);

        order.getOrderItems().add(item);
        return order;
    }
}

上面列出的 Web 服务客户机代码执行以下任务：

• 通过传入 OrderProcess Web 服务的 WSDL URL 和服务的 QName 创建 OrderProcess 类的实例。
• 创建 OrderBean 的实例，并使用 populateOrder() 方法填充订单信息。
• 对服务调用 getOrderProcessPort()，以检索到服务的代理（也称为端口）。端口实现服务所定义的接口。
• 调用端口的 processOrder 方法，并同时传入在上面的第二个列表项目中创建的 OrderBean 实例。
• 从服务获得 OrderBean 响应并输出订单 ID。

运行 Web 服务客户机

要运行 Web 服务客户机，请首先从 JAXWS-Tutorial 文件夹运行以下命令来编译 Web 服务客户机：

javac com\ibm\jaxws\tutorial\service\client\OrderClient.java

通过使用以下命令提供订单处理 Web 服务的 WSDL URL 来运行 Web 服务客户机：

java com.ibm.jaxws.tutorial.service.client.OrderClient http://localhost:8080/OrderProcessWeb/orderprocess?wsdl

运行 Web 服务客户机时，会在控制台看到以下输出（OrderWebServicePublisher 在控制台中运行）：

processOrder called for customer A123 Number of items is 1

在运行 Web 服务客户机的控制台中，会得到以下输出：

Order id is A1234

如上面的客户机代码中所示，并不会处理调用 Web 服务操作时使用的任何基于 SOAP 或 XML 的格式；相反，需要处理的是输入和输出消息的 JAXB 生成类，并使用服务接口和服务类对象（充当 Web 服务调用的存根）。存根负责从 JAXB Annotation 创建 SOAP 请求，并将 SOAP 响应转换回 Java 对象。

您现在已经成功地创建和发布了 Web 服务，并通过 Web 服务客户机成功地执行了此服务。

总结

在本教程中，我们了解了如何使用代码优先的开发方法和 JAX-WS 技术设计和开发 Web 服务。JAX-WS 是一个非常不错的选择，因为其中提供了完整的 Web 服务堆栈，以简化 Web 服务的开发和部署。

本教程中开发的订单处理 Web 服务使用 Document 样式的 Web 服务，可确保服务使用者和服务提供者使用 XML 文档进行通信。XML 文档遵循定义良好的契约，而此类契约通常都是使用 XML 模式定义创建的。XML 模式格式指定服务使用者能够调用和遵循的业务消息的契约。Document 样式的 Web 服务应该是开发企业 Web 服务的首选方法。

关于作者

Naveen Balani 在 IBM India 担任 WebSphere Business Services Fabric 的开发经理。他是 developerWorks 的固定投稿人，撰写过关于 Web 服务、ESB、JMS、SOA、体系结构、开放源代码框架、语义 Web、J2ME、Persuasive Computing、Spring、Ajax 和各种 IBM 产品的大量文章。他目前正在与人合著一本关于 Spring 2 与 Web 服务的书。

Related Posts:

• 2008/11/21 -- JAX-WS 开发 web service
• 2010/08/15 -- 定制 xmlbeans 所生成的 package
• 2010/07/16 -- wait and notifyAll in Java multi-threading
• 2010/07/13 -- 关于 java.util.concurrent 您不知道的 5 件事(转载)
• 2010/05/07 -- java.util.concurrent 中的 Executor

通过使用 JAX-WS, clients and web services 具有一个很大的优势: Java 编程语言的平台中立性. 另外, JAX-WS 是不受限制的: 一个 JAX-WS client 能够访问一个非运行于 Java 平台的 web service, 反之亦然. 这种灵活性是可能的, 因为 JAX-WS 使用 World Wide Web Consortium (W3C) 定义的技术: HTTP, SOAP, 和 Web Service Description Language (WSDL). WSDL 指定了一种 XML 格式用于描述一个由一组 endpoints 组成的 service.
创建一个 web service 和 client 的基本步骤如下:

1. 编写实现类.
2. 编译这个实现类.
3. 使用 wsgen 生成必需的一些相关类或资源以发布服务.
4. 将这些文件打包为一个 WAR.
5. 发布该 WAR. The tie classes (用于与 clients 通信) 由应用服务器在发布时生成.
6. 编写 client 类.
7. 使用 wsimport 生成和编译 stub 文件.
8. 编译这个 client 类.
9. 运行该 client.

详细步骤:
(你也可以定义一个 Java interface 作为 service endpoint interface – SEI, 尽管这不是必须的，因为 web service 实现类会暗中定义一个 SEI.
你可能会通过在实现类中添加 endpointInterface 元素来指定一个明确的 SEI. 随后，你必须提供一个定义了公共方法且在该 endpoint 实现类中具有相应具体实现的 SEI.

JAX-WS Endpoint 的要求
JAX-WS endpoints 必须遵从下列要求:
• 实现类必须以 javax.jws.WebService or javax.jws.WebServiceProvider 注释进行标注.
• 实现类可能会通过 @WebService 的 endpointInterface 明确引用一个 SEI, 但不是必须要求这样去做. 如果在 @WebService 中没有指定任何 endpointInterface, 将会为该实现类暗中定义一个 SEI.
• 实现类的业务方法必须是 public, 且务必不可声明为 static or final.
• 暴露给 web service clients 的业务方法必须用 javax.jws.WebMethod 进行标注.
• 暴露给 web service clients 的业务方法必须具有与 JAXB 兼容的参数和返回类型.
• 实现类务必不可声明为 final 且务必不可是 abstract.
• 实现类必须有一个缺省的 public 构造方法.
• 实现类务必不可定义 finalize 方法.
• 实现类可能会在它的方法上使用 javax.annotation.PostConstruct or javax.annotation.PreDestroy 注释作为生命周期事件的回调.
@PostConstruct 方法会在实现类开始响应客户端请求前被容器调用.
@PreDestroy 方法会在 endpoint 被从 operation 中移除前被容器调用.

一个简单的例子

a) 编写实现类：

package helloservice.endpoint;
import javax.jws.WebService;

@WebService()
public class Hello {
    private String message = new String("Hello, ");

    public Hello() {}

    @WebMethod()
    public String sayHello(String name) {
        return message + name + ".";
    }
}

@WebService() 表明这是一个 web service, @WebMethod() 表示这个方法是暴露给 clients 的.

b) 编译这个实现类：

wsgen -d build -s build -classpath build helloservice.endpoint.Hello

-d 指定生成的class文件的输出位置. -s 指定生成的源文件的输出位置. -classpath 指定了要编译文件的位置, 在本例中是 endpoint 实现类, helloservice.endpoint.Hello, 在build目录下.

c) 打包并发布该服务：

在发布时, 服务器和 JAX-WS 运行环境会生成 web 服务调用所必需的一些资源, 包括 WSDL 文件.

发布后, 访问 http://localhost:8080/helloservice/hello?wsdl 可看到生成的 WSDL 文件内容.

d) JAX-WS Client：

JAX-WS client 通过一个 stub 调用 web 服务, 这个 stub 是一个本地对象, 扮演远程服务的代理. Stub 在开发阶段使用 wsimport 工具创建, 该工具能够基于 WSDL 文件产生 JAX-WS portable artifacts.

步骤如下：

1. 使用 javax.xml.ws.WebServiceRef 注释声明一个指向一个 web service 的引用. WebServiceRef 使用 wsdlLocation element 指定已发布服务的 WSDL 文件的 URI.
   @WebServiceRef(wsdlLocation=”http://localhost:8080/helloservice/hello?wsdl”)
   static HelloService service;
2. 通过调用该服务的 getHelloPort 获取该服务的一个 proxy, 也俗称为 port.
   Hello port = service.getHelloPort();
   该 port 实现了该服务所定义的 SEI.
3. 调用该 port 的 sayHello 方法, 给该服务传递一个 name.
   String response = port.sayHello(name);

完整代码：

package simpleclient;

import javax.xml.ws.WebServiceRef;
import helloservice.endpoint.HelloService;
import helloservice.endpoint.Hello;

public class HelloClient {

    @WebServiceRef(wsdlLocation = "http://localhost:8080/helloservice/hello?wsdl")
    static HelloService service;

    public static void main(String[] args) {
        try {
            HelloClient client = new HelloClient();
            client.doTest(args);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public void doTest(String[] args) {
        try {
            System.out.println("Retrieving the port from the following service: " + service);
            Hello port = service.getHelloPort();
            System.out.println("Invoking the sayHello operation on the port.");
            String name;
            if (args.length > 0) {
                name = args[0];
            } else {
                name = "No Name";
            }

            String response = port.sayHello(name);
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

以上是先从代码入手开发一个web service，如果你已有 WSDL，可以通过wsimport生成相应类来开发并发布一个web service。
详细的介绍不妨看看《设计与开发JAX-WS 2.0 Web 服务》，这是一篇来自 IBM developerworks 上的文章，很值得一看。

另外有一篇SUN员工的介绍 JAX-WS 的文章《JAX-WS 2.0, an HelloWorld例子》，也可以作为参考。

Related Posts:

• 2008/12/04 -- 设计与开发 JAX-WS 2.0 Web 服务
• 2010/08/15 -- 定制 xmlbeans 所生成的 package
• 2010/07/16 -- wait and notifyAll in Java multi-threading
• 2010/07/13 -- 关于 java.util.concurrent 您不知道的 5 件事(转载)
• 2010/05/07 -- java.util.concurrent 中的 Executor

Custody and Ownership Transfer API Set 使得一个注册中心的任意节点能够相互间从一个节点向另一个节点转移一个或多个 businessEntity or tModel 的保管关系, 也允许从一个发布者向另一个发布者转移这些数据的所有权. 一个 businessEntity 所包含的实体例如它的 businessService, bindingTemplate, 和 publisherAssertion 结构作为这个 businessEntity 保管关系转移的一部分进行转移.

从保管转移的视角来说, 参与这种转移的发布者总是不同的人, 尽管可能具有这种情况: 这些发布者都是同一个人. 这两个节点可能是不同的节点, 也可能是相同的节点; 两者发布者间的节点内(intra-node)转移简单退化为节点保管关系没有变化这种情况. 因而, 在节点内(规范上为inter-node, 注:这里应该是规范笔误)转移的情况下, 暗含的是所有权转移. 在节点内(intra-node)转移时, 这种转移使得两个发布者间进行所有权转移.

例如, 一个 UDDI 注册中心, UDDI-1, 可能允许每个节点(由节点1A, 1B and 1C组成)定义节点自己的注册, 认证, 授权策略. 在这种情况下, 一个”人(person)”, (P1) 会需要审视一下所有3个节点的策略, 决定注册到哪个节点上. P1 可能选择注册了多个节点. P1 注册了 node1A. Node1A 也指定了怎样验证 P1. 如果 P1 成功通过认证, 然后发布了一个 business entity (BE1), 这样 P1 成为 BE1 的 “owner”. Node1A 称之为 BE1 的 “保管人(custodian)”. P1 也可能注册到了 node1B. 如果成功通过认证并发布了一个 business entity (BE2), 这样 P1 成为 BE2 的 “owner”. Node1B 称之为 BE2 的 “保管人(custodian)”. 注册中心 UDDI-1 或者它的节点(node1A and node1B)不会意识到 P1 其实是同一个人.

另一个 UDDI 注册中心, UDDI-2, 可能需要它的每个节点(node2-1, node2-2 and node2-3)使用相同的注册, 认证和授权机制. 在这种情况下, 这些策略在所有节点中都是一样的. 它们的注册, 发布和所有权关系都保持相同. 如果 P1 想要注册到 UDDI-2 中的不同节点, 那就需要在这些不同的节点中区分这些注册关系, 因为在已经注册到了 node2-1 后又试图注册到 node2-2, 将会遭遇 “已经注册过(already registered)” 错误 (因为根据策略, 这些节点共享相同的注册, 认证和授权).

Overview

有许多关于发布者可能选择转移实体保管人或所有权关系的场景.

节点内所有权转移(Intra-Node Ownership Transfer)

节点内所有权转移包括在同一 UDDI 节点内, 从一个发布者向另一个发布者转移实体所有权. 这类转移的使用场景包括如下:

· 商业实体或者组织合并: 多个组织需要整合到一个单一发布者进行管理.

· Domain key generators: 所有权转移的一个用处是由一个发布者向另一个发布者转移一个 derived key generator 所有权, 使得后者可以使用这个 domain 内的 keys 发布实体.

save_xx APIs 也可以用于在(由同一发布者所拥有的)双亲实体间移动实体. save_service API, 例如, 能够用于在一个 business entity 和另一个 business entity 间(使用save_service API)移动 services (和 binding templates). 使用这种方式改变双亲关系将使得两个 businessEntity 结构发生改变. 见以下使用场景:

· 剥夺: 一个组织需要重新分配一组服务的控制权给两个或多个发布者.

· 注册中心实体的合并: 某个商业实体有多个实体要合并到单一一个发布者名下.

节点间保管关系转移(Inter-Node Custody Transfer)

节点间保管关系转移包括跨越 UDDI 注册中心多个节点的一组实体的保管关系转移. 所有权转移会跟随着保管关系转移而发生. 除了以上描述的节点内的使用场景, 节点间保管关系转移还可能用于下面这些用例:

· 令人不满的服务水平: 某节点提供的功能和服务水平不够, 发布者希望将他们的数据转移到另一个节点.

· UDDI 节点可用性发生变化: 某节点不再提供 UDDI 服务, 所有发布者都需要迁移到注册中心的其它节点上.

· 组织合并, 剥夺或巩固: 组织结构变化可能导致需要更改负责管理注册中心各节点上实体的发布者.

对于节点内和节点间的这些使用场景, 本系列提供了一个机制便于在节点间转移 businessEntity 和 tModel 实体的保管关系, 不管是否实体是在单一一个节点内转移, 或者不管是否是在注册中心的多个节点间转移这种保管关系.

保管关系转移时的特殊考虑

当一个 businessEntity 被转移时, 所有相关 businessService and bindingTemplate elements 也被转移. 另外, 任何引用了这个 businessEntity element 的 businessKey 的 publisherAssertion elements 也会被转移.

注意, 在一次保管关系转移请求中, 并不会要求该放弃保管关系的发布者转移他的所有 UDDI 实体(也就是 businessEntity 和/或 tModel 实体), 也不会要求他将他的所有实体转移给同一接收发布者或者接收节点. UDDI 注册中心实体可以转移给任意数目的接收发布者或者接收节点.

转移执行过程

Custody and Ownership Transfer API 能够使在一个 registry 中的两个发布者 P1 and P2 和两个节点, N1 and N2, 相互配合, 将一个或多个现有 businessEntity 或 tModel, E1…En, 的保管权, 从 N1 转移到 N2, 同时也会将这些实体的所有权从 P1 转移给 P2. 相关的 businessService, bindingTemplate, and publisherAssertion 也将随它们的 businessEntities 而被转移. 从 Registry 角度来看, 这些发布者总是不同的, 尽管可能有这种情况: P1 和 P2 是同一个组织. 这两个节点可能是同一节点或者也可能不是; 在节点内从 P1 向 P2 转移所有权是一种退化情况, 节点保管关系没有改变.

Custody and Ownership Transfer API 分为两部分, 2个 client APIs 和 1 个节点间 API. client APIs 包括 get_transferToken 和 transfer_entities; 简而言之, 这构成了这个 API 集的 Ownership Transfer API 部分. 节点间 API 包括 transfer_ custody, 与 replication 联合使用, 组成了这个 API 集的 Custody Transfer API 部分.

保管权和所有权转移的总体流程如下:

Publisher P1 调用 N1 的 get_transferToken, 指定要转移的实体 E1…En 的 keys K1…Kn. 如果 P1 获得许可 (即, 如果 P1 具有 E1…En 所有权), N1 返回一个结构 T, 称作转移令牌, 代表了可以转移实体的授权, 包括所有与要转移的 businessEntity(owned by P1) 有关的天生所包含的那些孩子和 publisherAssertion. 转移令牌(transferToken) 结构包含一个不易阅读的只有产生它的节点才能理解的字符串, 一个过期时间, 和一个节点标识符.

P1 然后将 T 交给 P2 (通常是通过安全方式, 因为 T 是很重要的). 欲获得保管信息的发布者在他/她能够完成保管权的转移之前, 需要先获取接收该实体保管权的节点上的一个发布者帐号. P2 接着调用 N2 的 transfer_entities, 传递 K1…Kn 和 T. 如果 transfer_entities 调用成功, 实体 E1…En 和它们相关的数据结构 (businessService, bindingTemplate, and publisherAssertion) 将位于 N2 保管之下, 由 P2 持有(own). 如果操作失败, 不会对这些实体产生影响. transfer_entities 的实际转移处理步骤如下.

如果 N1 and N2 并非是不同节点(即同一节点), 从 P1 向 P2 转移所有权完全就是节点内部操作 – 操作是如何发生的取决于实现. 如果 N1 and N2 是不同的, 当在 N2 上处理 transfer_entities 请求时, 将遵循下面的协议.

Upon receipt of a transfer_entities request, N2 checks that K1…Kn are valid keys. There is the possibility that P1 might transfer more data than P2 can accept due to policy-based restrictions on the limit of entities allowed to be owned by P2 at N2. As is described below, replication is used to complete the custody transfer process. A question that arises is at the time of accepting the datum related to the transfer, could N2 throw a replication error because the data being transferred exceeds the limits of user P2? Such limits can not be enforced during replication because they are node-local policy decisions from the perspective of enforcement. Thus, it is therefore possible that as a result of a custody transfer a publisher may be caused to hold more data that he/she would have been able to publish. Should this situation occur, P2 MUST not be allowed to publish any additional data unless P2 first reduces the number of entries it owns to an allowable limit.

If all is well, N2 invokes the inter-node API transfer_custody on N1, presenting the keys of top-level entities to be transferred, K1…Kn, P2’s identity (using the publisher’s authorizedName), N2’s node identifier (as known in the Replication Configuration structure, see Section 7.5.2 Configuration of a UDDI Node – operator element), and T. The transferToken, T, implies permission to transfer the entire content of the entities it identifies, including all of the contained entities and related publisherAssertions, if any. N1 checks to see whether T is a valid transferToken that it issued and that T represents the authority to transfer E1…En. If the validation is successful, N1 prevents further changes to entities E1… En. N1 then updates the authorizedName and nodeID of the operationalInfo of E1…En and related entities so that they are shown to be in the custody of N2 and owned by P2. Finally, N1 responds to N2 which triggers N2 to respond to the transfer_entities caller. This completes the processing for the transfer_entities request.

In the case that the datum being transferred is a key generator tModel, N1 will disallow further generation of keys associated with this key partition at its node.

Following the issue of the empty message by N1 to the transfer_custody call, N1 will submit into the replication stream a changeRecordNewData providing in the operationalInfo, N2’s nodeID identifying it as the node where the datum is being transferred to, and the authorizedName of P2. The acknowledgmentRequested attribute of this change record MUST be set to “true”.

The last modified date timestamp in the operationalInfo must change to reflect the custody transfer.

Figure 2 depicts the flow of a custody transfer between P1 and P2.

Figure 2 – Custody Transfer

Once N2 receives the changes via the replication stream it assumes custody of E1…En and assigns ownership of the entities and related entities owned by P1 to P2.

Related Posts:

• 2009/07/19 -- SMTP Transport Binding for SOAP
• 2009/07/07 -- Which style of WSDL should I use? (reship)
• 2008/07/15 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Value Set API Set
• 2008/07/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set
• 2008/07/07 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Publication API Set(3)

Value Set 编程接口

本系列的 APIs 提供了一种能力: UDDI registry 可能使用这种能力对值集的引用进行校验. 注册中心策略确定哪个外部值集是受支持的, 如何支持.
公共可访问的用于支持外部值集校验的 APIs 如下:

· validate_values: 由节点使用, 允许外部值集校验 Web service 的提供者评估 keyedReferences or keyedReferenceGroups 是否是有效的. 返回一个 dispositionReport 结构.
· get_allValidValues: 由支持从可缓存检查型值集缓存有效值的节点使用, 用于获得有效值的集合. 返回一个空消息或者一个 dispositionReport 结构.

注册中心策略可能需要提供其中一种 Web service 的值集提供者通过特定方式为这个 service 发布 bindingTemplate, 为该值集发布 tModel, 这样才能够找到正确的 Web service. 当一个值集提供者提供了其中一种 Web service, 应该在任何该提供者想要提供该值集的注册中心中为该检查型值集发布一个 tModel, 为值集提供者为该检查型值集提供的 Web service 发布一个 bindingTemplate. 该 tModel 应该具有 uddi-org:types category system 的分类, 表明值集类型(categorization, identifier, relationship, categorizationGroup), 是检查型的(checked), 并且, 如果该值集提供者允许根据节点对有效值的缓存进行校验, 也应该标明是 cacheable 类别.
为了让一个值集成为检查型的, 该 tModel 必须首先引用 uddi-org:types category system 使用 checked 值将其划为 checked 的.  检查这样的值集是由注册中心和节点策略决定的.
如果一个值集 tModel 被划分为 checked, 那么在试图发布一个使用到这个 checked tModel 的 keyedReference 时, 节点必须或者执行必要的校验, 或者返回 E_unsupported.
该 tModel 也应该具有一个到 get_allValidValues or validate_values Web service 的 bindingTemplate 的分类引用, 这需要使用 uddi-org:validatedBy category system.
get_allValidValues or the validate_values Web service 的 bindingTemplate 应该在它 tModelInstanceDetails 中引用适当的值集 tModel, 和其它该服务所适用的所有的值集 tModels.

validate_values：

当发布者保存的数据使用 keyedReference or keyedReferenceGroup 而引用了某检查型值集, 支持外部校验的 UDDI 节点调用适当的外部 Web service 的 validate_values API 进行校验, 这个外部 Web service 有且只有一个 API. 为了讨论方便, keyedReference elements 引用的 identifier, category, and relationship type systems 统称为检查型值集(checked value sets). keyedReferenceGroup elements 引用的 category group systems 也类似地称为 checked category group systems.
检查型值集的正常用途是验证特定值(检查 keyValue 属性的值)是否存在于值集中. 对于特定值集, 值集提供者可能依据所传递数据的上下文环境进一步限制对值的使用. 提供者可以通过提供一个校验 Web service 来执行这种上下文环境检查.
checked category group systems 的校验算法也类似, 依据该 checked category group system 的校验算法检查 keyedReferenceGroup elements 内容是否构成了一个有效值集合. 这种校验经常是确认它所包含的 keyedReferences 的 tModelKey 集合都是允许参加这个 category group system(Frequently such validation ensures that the value sets identified in contained keyedReferences are allowed to participate in the category group system).

参数：

UDDI 节点在调用 validate_values 时必须传递一个或多个 businessEntity elements, 一个或多个 businessService elements, 一个或多个 bindingTemplate elements, 一个或多个 tModel elements, 或者一个或多个 publisherAssertion elements, 作为唯一参数传给这个 Web service. 这些 elements 就是在调用 save_business, save_service, save_binding, save_tModel, add_publisherAssertion, or set_publisherAssertions API 时所传递的 UDDI 数据.
如果在同一保存操作中包含了多个同一类型的 elements, 它们可以一起传递给 validate_values.
可选的 authInfo 参数包含一个 authentication token. 可以通过 get_authToken API 或其它途径获得一个 authentication token. 同时服务多个注册中心的 validate_values Web services 提供者和需要限制哪些用户可以使用该 Web service 的该 service 提供者可能需要 authInfo.

行为：

为检查型值集所提供的 Web service 对所有引用到它的 keyedReferences or keyedReferenceGroups 执行校验. 这可以包括只检查 keyValue 值对该(由 keyedReference tModelKey 值指定的)给定值集来说是良好的. 其它期望的校验也可以, 包括利用要保存实体中的信息进行上下文敏感的检查.
要保存的实体可能包含多个到某(些)值集的引用. 当要保存的实体是一个 businessEntity, 它所包含的 businessService and bindingTemplate 实体可能自己也引用该值集中的值. 不管在被保存的实体中处于何位置, 所有到该(些)值集值的引用必须被校验.
如果外部值集和节点都支持缓存有效值, 节点通过检查它的缓存已经知道该被引用值是有效的, 节点可以不调用 validate_values.
一个 checked category group system 按照与一个 checked value set 相同的方式对待. keyedReferenceGroup 的 tModelKey 指向 checked category group system. 如果节点通过使用它的缓存可以确定包含于 keyedReferenceGroup 中的 keyedReference elements 的 tModelKey 属性都允许参加这个 category group system, 它可能不调用 validate_values 校验到该 cacheable checked category group system 的引用.

返回值：

如果在被保存实体中所有被引用值对该值集或者category group system(s)来说都是有效的, 正确的响应是一个空消息.

错误警告：

如果出现任何错误, 或者被调用 Web service 需要指出根据外部 Web service 提供者所选择的校验算法, 被保存的数据是无效的, 那么该 Web service 必须生成一个 SOAP Fault.
当使用这种方式声明一个错误时, UDDI 节点必须拒绝等候作出更改的改动并将该校验 Web service 所返回的相同的 SOAP fault 数据返回给原始调用者. 错误代码指出以下某个错误原因, 错误文本清楚指出被拒绝的 keyedReference 或者 keyedReferenceGroup 数据和被拒绝的原因.

· E_invalidValue: keyedReference 或 keyedReferenceGroup 里的 keyedReferences 中一个或多个 keyValues 校验失败. 只需要返回第一个错误.
· E_valueNotAllowed: 值可能是有效的, 但上下文环境不允许.

get_allValidValues：

支持外部值集的 UDDI node 经某外部值集提供者许可, 可能会调用该外部值集提供者提供的一个 get_allValidValues Web service 去缓存该值集的有效值. 外部值集提供者可能提供这个 get_allValidValues Web service, UDDI node 可能会使用它. 正常的用法是返回该值集有效值的一个完整集合. 如果值集提供者确认一次需要返回太多的值, 该有效值集合可能会分多次返回.
当缓存应该被注册中心的节点重新获取时, 注册中心策略可能需要该提供了 get_allValidValues Web service 的值集提供者重新发布这个值集的 tModel.
get_allValidValues 同样能够用于获得一个可缓存的 category group system 中的可参与该 category group system 的值集的 tModelKeys.

参数：

· tModelKey: 这个必需的 uddiKey 值标识了某值集或 category group system 的 tModel 的特定实例, 这个 Web service 就是用于为该 tModel 获得所有有效值. 它唯一标识 category, identifier, or category group system.
· chunkToken: 当第一次调用这个 API 时有太多数据, 这个可选元素可用于分几组来连续获取这些数据. 这种情况通常发生于在 validValuesList 结构中返回了一个 chunkToken 且值不为 “0″ 的时候. 为了获取下一批次数据, 返回的 chunkToken 应该用作下一次调用该 API 的参数.
· authInfo: 这个可选元素包含一个 authentication token. 可使用 get_authToken API 或其它方式获得 Authentication tokens. 服务于多个注册中心的 get_allValidValues Web services 的提供者和想要限制谁可以使用自己服务的提供者可能需要 authInfo.

返回值：

返回的 validValuesList 结构包含外部 category or identifier system 的有效值集合. 如果 Web service 提供者希望分批次提供提供数据的话, 该列表必须包含一个 chunkToken.

validValuesList 有：

1. chunkToken 元素：可选
2. validValue 元素：0..∞

行为：

成功的话, 这个被调用的 Web service 在 validValuesList 中返回有效值集合. 这个结构列出所传递 tModelKey 描述的值集或 category group system 中的每个有效值. 如果在一次响应中需要返回太多值(即, 消息大小超出了 UDDI 注册中心所允许的最大字节数), 或者值集提供者想要分多个批次提供这些值, 那么在 validValueList 中包含 chunkToken element 随后再次调用这个 API 便可得到剩下的有效值.

Chunking of valid values：

如果值集提供者认为在一组中返回的值太多, 那么该提供者应该为该结果集提供一个 chunkToken. chunkToken 是一个基于 token 的字符串, 当这些结果分多批次跨越多次响应时, 这个 token 用于为该特定调用者维护值的集合的状态. 提供者应该建立他们自己的策略用于确定 chunkToken 的内容和格式. 一个特定值集结果集的 chunkToken 应该被用于获取成批次的(subsequent)结果. 如果再没有结果集了, chunkToken 值将是 “0″ 或者省略掉(absent) chunkToken.
chunkToken 是为了用作短期内分批次获得结果的目的(A chunkToken is intended as a short-term aid in obtaining contiguous results across multiple API calls), 因此可能只在很短时间内保持有效. 值集提供者可以建立策略用于确定一个 chunkToken 可以保持多久有效.

错误警告：如果发生错误, 必须在 SOAP Fault 中返回一个 dispositionReport

· E_invalidKeyPassed: 所传递的 tModelKey 与任何已知的 tModels 的 uddiKey 都不匹配. 无效 key 的详细信息应该包含到 dispositionReport element 中.
· E_noValuesAvailable: 没有任何有效值.
· E_unsupported: 这个 Web service 不支持这个 API.
· E_invalidValue: chunkToken 值或者是无效的或者已经过期了.

Related Posts:

• 2009/07/19 -- SMTP Transport Binding for SOAP
• 2009/07/07 -- Which style of WSDL should I use? (reship)
• 2008/07/19 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Custody and Ownership Transfer API Set
• 2008/07/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set
• 2008/07/07 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Publication API Set(3)

· discard_authToken: 用于通知节点以前得到的某 authentication token 不再需要了, 如果在接收到这个消息之后还有使用它的, 应该认为它是无效的.
· get_authToken: 用于从一个节点请求一个使用 authInfo element 样式的 authentication token. 在使用 Inquiry API Set, Publication API Set, Custody and Ownership Transfer API Set, 和 Subscription API Set 中的 API 时, authInfo element 可能是必需的.

API 是否需要 authInfo elements 是由节点策略决定的. 如果一个 authInfo element 最后并没有被丢弃, 节点可能会选择使这个 authentication token 过期, 这样可以让它不再有效. 如果一个过了期的 token 被传递给一个 API, 除了 discard_authToken 外, 将返回错误 E_authTokenExpired.
如果一个 UDDI 节点不支持在 API set 中使用 authInfo element, 通常它也不支持 Security API set. 如果节点支持在该节点所提供的任何 API set 中使用 authInfo element, 它应该也支持 Security API set. 一个节点可能提供另一种可替代(security api的)机制用于获得 authInfo elements.

discard_authToken：

参数：

· authInfo: 这个必需的参数包含一个 authentication token. Authentication tokens 可使用 get_authToken API 获得.

行为：

Discarding an expired authToken is processed and reported as a success condition.

返回值：

完全成功的话, 返回一个空消息(return null).

错误警告：

如果在处理这个 API 调用时发生错误, 将在 SOAP Fault 中返回一个 dispositionReport 结构给调用者.

get_authToken：

get_authToken API 用于获得一个 authentication token. 在使用 Inquiry API Set, Publication API Set, Custody and Ownership Transfer API Set, 和 Subscription API Set 中的 API 时, 一个 authToken element 可能是必需的.

参数：

· userID 属性: 这个必需的属性是 UDDI 节点分配给一个已授权过用户的标识符. 节点应该提供一种方式供用户获得一个在给定节点有效的 userID and password 认证信息.
· cred 属性: 这个必需属性是密码或者与该用户相关联的 credential.

返回值：

这个 API 调用完全成功后会返回一个 authToken 结构, 包含一个有效 authInfo element, 这个 authInfo element 就可以在接下来的请求中使用.
authToken element 包含一个 authInfo element. authToken element 总是作为对 get_authToken 调用的同步响应而返回.

错误警告：发生错误时, 必须返回一个 dispositionReport element.

· E_unknownUser: UDDI node 不接受和认可请求所传递的 userID and/or cred 参数值为有效认证信息.

Related Posts:

• 2009/07/19 -- SMTP Transport Binding for SOAP
• 2009/07/07 -- Which style of WSDL should I use? (reship)
• 2008/07/19 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Custody and Ownership Transfer API Set
• 2008/07/15 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Value Set API Set
• 2008/07/07 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Publication API Set(3)