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

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)

save_binding API 用于保存或更新一个完整的 bindingTemplate element. 它可以用于添加或更新一个或多个 bindingTemplate elements, 也可以用于调整与某 businessService element 的包含关系. 每个 bindingTemplate 可能(MAY) 被签名, 可能(MAY)使用 publisher-assigned keys.

参数：

· authInfo: 略.

· bindingTemplate: 必需的. 可有1个或多个 bindingTemplate. 如要保存一个新的 bindingTemplate, 则提供一个 bindingTemplate element,
或者 bindingKey 属性值为空, 或者使用 publisher-assigned bindingKey.

每个新的 bindingTemplate 必须(MUST)包含一个 serviceKey 值, 该 serviceKey 所对应的 businessService 也是由该发布者所控制的. 一个已存在的 bindingTemplate 可能(MAY)包含一个 serviceKey 值, 对应于该同一发布者所控制的 businessService. 调用这个 API 将影响到每个 bindingTemplate 参数的父 businessService(即其父businessService可能会更改为其它businessService). 如果同一 bindingTemplate (由 bindingKey 值决定是否相同) 出现多次, 它的上级 businessService 具体是哪个将由处理顺序确定, 即决定于从第一个到最后一个(该相同的) bindingTemplate 的位置.
如果一个 bindingTemplate element 的 bindingKey 缺失或是一个空值, 这表示 bindingTemplate 首次被插入. 当出现这种情况的时候, node 必须(MUST) 自动为该没有 key 的 bindingTemplate 生成一个新 key. 新的 bindingTemplate 结构也可以使用 publisher-assigned keys.
使用这个 API, 可以将一个已存在的 bindingTemplate 从一个 businessService 移动到另一个 businessService, 只需要简单地为该 bindingTemplate 指定一个另一个不同的父 businessService 的 serviceKey. 通过这种方式改变父 businessService, 将对这两个 businessService 结构都产生影响. The net result of such a move is that the bindingTemplate still resides within one, and only one businessService based on the value of the serviceKey passed. 如果一个发布者尝试通过这种方式移动一个 bindingTemplate, 但并非该 bindingTemplate 中 serviceKey 所对应 businessService 的所有者, 那么该操作请求必须(MUST)被拒绝, 并返回一个 E_userMismatch 错误.
当一个 bindingTemplate 被保存, 且使用了 categoryBag 关联到一个 checked value set 或 category group system tModel, 这些 references 必须(MUST)先于保存操作完成之前接受有效性检查, 或者 node 必须返回 E_unsupported 指出它并不支持引用 checked value set 或 category group system.

返回值：

本 API 返回一个 bindingDetail 结构包含刚刚注册的已生效的 bindingTemplate elements 信息. 如果在一次调用中不止一个 bindingTemplate 被保存, 作为结果返回的 bindingDetail 必须(MUST)按照 save_binding 调用时相同的参数顺序返回结果信息. 如果同一 bindingTemplate (根据 bindingKey 确定是否相同) 在 save_binding 中出现多次, 它可能(MAY)要为 save_binding 中每次出现的该 bindingTemplate 只返回一个对应结果. 如果同一 bindingTemplate 在响应中出现不止一次, 最后一个出现的该 bindingTemplate 表示最终保存于注册中心的状态. save_binding 调用所返回结果中的 bindingTemplate 都会有 bindingKey.

bindingDetail 可以有 0 个或多个 bindingTemplate.

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

· E_accountLimitExceeded: 超出用户的帐户限制.
· E_invalidKeyPassed: 所指定一个或多个 uddiKey 值对要发布的实体来说是无效的 key. tModelKey, serviceKey, or bindingKey 值或者不存在, 或者存在但类型不对, 或者没有经过发布者授权使用. 导致这个错误的 key 应该(SHOULD)清楚地在错误文本中指明. 这个错误代码最终也会被返回, 表示没有提供 serviceKey, bindingKey 或者缺失或者所使用的值并没有在注册中心注册过. 在这种情况下, 错误文本应该(SHOULD)清楚地指明当前使用了一个不完整的 bindingTemplate.
· E_invalidValue: keyValue 属性所使用的这个值没有通过验证. 应用于 checked value sets(使用keyedReferences进行引用). 错误文本应该(SHOULD)清楚地指出验证失败的 key 和 value 值对.
· E_keyUnavailable: 所提供的 key 已被指派给其他发布者使用或者没有在该发布者所拥有的 key generator tModel 定义的键分区中.
· E_requestTimeout: 该请求没有被执行, 因为必须调用的 validate_values 服务并没有在合理时间范围内返回响应. 这个发生失败的 Web service 的详细信息应该(SHOULD)包含在 dispositionReport element.
· E_userMismatch: 略.
· E_valueNotAllowed: 所引用的 value set 中的某个值是不被允许的.

save_business：

save_business API 用于保存或更新一个完整 businessEntity 结构信息. 本 API 在所有 save_xx APIs 中具有最大的作用范围, 能够用于对某个发布者所控制的一个或多个 businessEntity elements 信息做彻底更改.
这个 API 可以用于与其它 businessEntity 所管理的 businessService 结构建立引用关系. 使用这种方式, 原本是一个 businessEntity 一部分的 businessService 能够作为另一个 businessEntity 的一个服务投影. 使用这种方式的投影服务的内容不作为引用它的实体的一部分而进行管理.
businessEntity 结构可能(MAY)会被签名, 可能(MAY)会使用 publisher-assigned keys.

参数：

· authInfo: 略.

· businessEntity: 必需的, 0..∞. 可以通过 get_businessDetail API 或其它方式得到这些 businessEntity.

如果一个 businessEntity element 中的 uddiKey 值(例如这个 businessEntity 中的 businessKey, serviceKey 或 bindingKey)缺失或者只设置了一个空值, 这就表明这个数据是首次插入. 当出现这种情形时, node 必须(MUST)自动为该缺少 key 的数据生成一个新 key. 新实体也可以使用 publisher-assigned keys.
要想用这个 API 对一个已存在的数据执行更新操作, 那么该实体(businessEntity, 以及内含的 businessService or bindingTemplate)必须(MUST)要带有 uddiKey 值.
使用这个 API 可以删除数据. 比如某个 businessEntity 原本有某个 businessService 和 bindingTemplate, 后来在更新这个 businessEntity 时该 businessEntity 并不含这些数据, 结果, 这些数据就从 registry 中删除掉了.
包含在 businessEntity 结构里的数据可以使用这个 API 进行重新整理. 比如重新定义包含关系. 例如, 如果要保存的 businessEntity 带有一个 businessService 信息, 而这个 businessService 已经作为另一个不同的 businessEntity 一部分而注册, 这将使得这个 businessService 被从它当前所在的 businessEntity 移动到这个新 businessEntity. 在上述情形下, 要保存的这个 businessService 的 businessKey 匹配要保存的那个 businessEntity 的 businessKey. 如果某人并非某个 businessService 的发布者, 却想使用这种方式删除或移动这个 businessService, node 必须(MUST)拒绝这种请求, 返回一个 E_userMismatch 错误.
如果要保存的 businessEntity 包含一个 businessService, 该 businessService 的 businessKey 引用了其它 businessEntity 而不是这个要保存的 businessEntity, UDDI registry 注意到note 这个引用, 称之为对其它已存在的 businessService 的 “服务投影(service projection)”. 随后调用 get_businessDetail API, 传递原本这个 businessService 所在的 businessEntity 的 businessKey 或者包含了对这个 businessService 服务投影的 businessEntity 的 businessKey, 都将在结果集中返回一个完全相同的 businessService element.
businessEntity 务必不可同时包含一个 businessService 和对这个 businessService 的服务投影. 因此, 不能将一个 businessService 移动到一个已经包含了该 businessService 服务投影的 businessEntity 中. 不管操作顺序如何, 一个 businessService 和该 businessService 的服务投影永远不能在同一个 businessEntity 中. 在发生这种情况的 save_business 操作时, UDDI 实现要拒绝并返回一个 E_fatalError.
建立一个 businessService 的服务投影不会影响到该 businessService. 一个原本已存在于 businssEntity 中的服务投影, 在更新这个 businessEntity 时不再包含其中, 则该服务投影被自动删除. 这种引用删除不会改变被引用的 businessService. 如果被引用的 businessService 被删除了, 所有的在其它 businessEntity 中对它的引用将保留不动. 像这样”损毁的(broken)”服务投影作为 businessService elements 出现在它们的 businessEntity 中, 所包含的 businessKey 和 serviceKey 属性只是作为内容存在而已. 如果 businessService 移动到其它 business, 所有服务投影都将被更新, 以实时反映这个新的 businessKey. 因此, 最好重新整理一下对发布于其它 businessEntity 下的 businessService 的引用.
当保存一个 businessEntity 含有服务投影的时候, 在 save_business 操作中提供的该 businessService 的内容, 除了 serviceKey 和 businessKey, 其余都将被忽略. 被引用的 businessService 的 businessKey 和 serviceKey 用于决定该 businessService 是否用于服务投影. 如果由 serviceKey 所标识的 businessService 并非由 businessKey 所标识的 businessEntity 的一部分, 将返回错误 E_invalidProjection.
当一个要保存的 businessEntity 带有 identifierBag 或 categoryBag 内容, 且该内容涉及到 checked value set 或者 category group system tModel, 则这些内容中的引用必须(MUST)先于保存操作完成之前接受有效性检查, 或者, node 必须返回 E_unsupported, 指出自己不支持该被引用的 checked value set or category group system.

返回值：

本 API 返回一个 businessDetail 结构, 包含调用的最终结果, 该结果反映了新注册的 businessEntity 信息. 任何被指定 businessKey, serviceKey, 或 bindingKey 属性都将作为 save_business 处理结果而包含于返回的数据中. 对于服务投影的 businessService elements, 响应或者包含发布者所提供的 businessService elements 或者包含真实 businessService elements 的完整内容. 结果包含任何使用引用而包含进来的 businessService elements. 如果同一实体(businessEntity, businessService, or bindingTemplate), -根据key的匹配情况确定是否是同一实体, 在 save_business 调用时列了不止一次, 可能(MAY)会在结果中只列一次. 如果同一实体在响应中出现不止一次, 最后一次出现的实体或者反映了最终保存的状态或者在请求中该发布者所提供的最后一次出现的实体.
businessDetail 具有 0 个或多个 businessEntity.

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

· E_accountLimitExceeded: 超出用户的帐户限制.
· E_invalidKeyPassed: 所指定一个或多个 uddiKey 值对要发布的实体来说是无效的 key. tModelKey, serviceKey, or bindingKey 值或者不存在, 或者存在但类型不对, 或者没有经过发布者授权使用. 导致这个错误的 key 应该(SHOULD)清楚地在错误文本中指明. 这个错误代码最终也会被返回, 表示没有提供 serviceKey, bindingKey 或者缺失或者所使用的值并没有在注册中心注册过. 在这种情况下, 错误文本应该(SHOULD)清楚地指明当前使用了一个不完整的 bindingTemplate.

· E_invalidProjection: 要保存的 businessEntity 所含的某个服务投影, 其要投影的服务(businessService being projected)并非是该被投影 businessService 的 businessKey 标识的 businessEntity 的一部分(其实被投影的服务自己也是一个服务投影). 至少一个这样的 businessService 的 serviceKey 应该(SHOULD)包含在 dispositionReport 中.

· E_userMismatch: 略.
· E_invalidValue: keyValue 属性所使用的这个值没有通过验证. 应用于 checked value sets(使用keyedReferences进行引用). 错误文本应该(SHOULD)清楚地指出验证失败的 key 和 value 值对.
· E_keyUnavailable: 所提供的 key 已被指派给其他发布者使用或者没有在该发布者所拥有的 key generator tModel 定义的键分区中.
· E_requestTimeout: 该请求没有被执行, 因为必须调用的 validate_values 服务并没有在合理时间范围内返回响应. 这个发生失败的 Web service 的详细信息应该(SHOULD)包含在 dispositionReport element.

· E_unsupported: 引用了 checked value set 的某个 categoryBag 或 identifierBag 中的某个 keyedReference 不能通过 UDDI node 校验, 因为 node 不支持该被引用的 checked value set. 错误文本应该清楚地指明是哪个 keyedReference 没能通过校验.

· E_unvalidatable: 引用了 checked value set 的某个 categoryBag 或 identifierBag 中的某个 keyedReference 不能通过 UDDI node 校验, 因为被引用的 tModel 已经标记为无效. 错误文本应该清楚地指出哪个 keyedReference 没能通过校验.
· E_valueNotAllowed: 所引用的 value set 中的某个值是不被允许的.

save_service：

save_service API 用于新增或更新一个或多个 businessService elements. 每个 businessService 可能(MAY)被签名, 可能使用 publisher-assigned keys.

参数：

· authInfo: 略.
· businessService: 必需的, 0..∞. 可以通过 get_serviceDetail API 或其它方式得到这些 businessService.

在传递的 businessService 中, 每个新 businessService 必须包含一个 businessKey 值, 对应于该发布者所管理的某个 businessEntity; 一个已存在的 business service 可能包含一个 businessKey 值, 这个值对应于该发布者所管理的某个 businessEntity.
如果一个 businessService element 中的任意某个 uddiKey (即, 该businessService的serviceKey或所包含的bindingTemplate的bindingKey)是一个空值, 这表示是首次插入. 在这种情形下, 必须为这种不带 key 值的数据自动生成一个新 key 值. 新实体也可以使用 publisher-assigned keys.
如果在一次调用中传递了多个同一 businessService 作为参数, 最终这个 businessService 的上级 businessEntity 是哪个将由处理顺序决定 – 请求中这些相同 businessService 的传递顺序. 类似地, 如果同一 bindingTemplate 在调用中包含在多个 businessService 中, 最终结果将是最后一个 businessService 参数才是这个 bindingTemplate 的双亲.
使用这个 API, 可以将一个已存在的 bindingTemplate element 从一个 businessService element 移动到另外一个, 或者将一个已存在的 businessService element 从一个 businessEntity 移动到另外一个, 只需简单地为它指定与原来不同的双亲 businessEntity. 通过这种方式改变双亲关系将使得这两个 businessEntity 或者两个 businessService 结构发生改变. An attempt to move a bindingTemplate or a businessService in this manner by a party who is not the publisher of the businessService that is specified by the serviceKey or the businessEntity that is specified by the businessKey MUST be rejected with an error E_userMismatch.
当一个要保存的 businessService 带有 categoryBag , 且该 categoryBag 引用到一个 checked value set or category group system tModel, 其中的引用必须接受有效性检查, 而且检查要先于保存操作完成之前, 或者 node 必须返回一个 E_unsupported, 指出自己不支持该被引用的 checked value set or category group system.

返回值：

这个 API 返回一个 serviceDetail 包含该次调用的最终结果, 该结果直接反映出已生效(新增或更新成功)的 businessService elements. 当在某次请求中传递了多个 businessService elements, 结果包含所传递的每个 businessService 相对应的最终结果, 它们按照与请求中相同的顺序出现于结果集中. save_service API 结果集中的 businessService 都带有 serviceKey 或 bindingKey 值.
如果同一实体(businessService, or bindingTemplate), 由 key 确定是否相同, 在 save_service API 中出现多次, 那么在结果集中可能为请求中该实体的每个 elementit 只列出一个 element. 如果同一实体不止一次出现于响应中, 最后一次出现的实体反映了其在 registry 中的存储状态.
serviceDetail 包含 0 个或多个 businessService element.

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

· E_accountLimitExceeded: 超出用户的帐户限制.
· E_invalidKeyPassed: 所指定一个或多个 uddiKey 值对要发布的实体来说是无效的 key. tModelKey, serviceKey, or bindingKey 值或者不存在, 或者存在但类型不对, 或者没有经过发布者授权使用. 导致这个错误的 key 应该(SHOULD)清楚地在错误文本中指明. 这个错误代码最终也会被返回, 表示没有提供 businessKey, serviceKey或者缺失或者所使用的值并没有在注册中心注册过. 在这种情况下, 错误文本应该(SHOULD)清楚地指明当前使用了一个不完整的 businessService.

· E_userMismatch: 略.
· E_invalidValue: keyValue 属性所使用的这个值没有通过验证. 应用于 checked value sets(使用keyedReferences进行引用). 错误文本应该(SHOULD)清楚地指出验证失败的 key 和 value 值对.
· E_keyUnavailable: 所提供的 key 已被指派给其他发布者使用或者没有在该发布者所拥有的 key generator tModel 定义的键分区中.
· E_requestTimeout: 该请求没有被执行, 因为必须调用的 validate_values 服务并没有在合理时间范围内返回响应. 这个发生失败的 Web service 的详细信息应该(SHOULD)包含在 dispositionReport element.

· E_unsupported: 引用了 checked value set 的某个 categoryBag 或 identifierBag 中的某个 keyedReference 不能通过 UDDI node 校验, 因为 node 不支持该被引用的 checked value set. 错误文本应该清楚地指明是哪个 keyedReference 没能通过校验.

· E_unvalidatable: 引用了 checked value set 的某个 categoryBag 或 identifierBag 中的某个 keyedReference 不能通过 UDDI node 校验, 因为被引用的 tModel 已经标记为无效. 错误文本应该清楚地指出哪个 keyedReference 没能通过校验.
· E_valueNotAllowed: 所引用的 value set 中的某个值是不被允许的.

save_tModel：

save_tModel API 用于添加或者更新一个或多个 tModel elements. tModels 可能被签名, tModels 可能使用 publisher-assigned keys, 包括那些使用 publisher-assigned keys 建立 domain partition 的 tModels, 即常说的 domain key generator tModels.

参数：

· authInfo: 略.
· tModel: 必须的, 1..∞ . 可以使用 get_tModel API 或其它方式得到这些数据.

行为：

如果一个 tModel 的  uddiKey 值(即, tModelKey) 缺失或者是一个空值, 这表示要插入的是一个新的 tModel, UDDI registry 必须为这个 tModel 指派一个新的 tModelKey 标识符. 如果这个新 tModel 使用 uddi:uddi.org:categorization:types category system 中的 keyGenerator 值进行归类, 任何 publisher-assigned key 都必须以字符串 “:keygenerator” 结尾, 使这个 tModel 成为一个 key generator tModel. 如果这个新 tModel 使用 uddi:uddi.org:categorization:types category system 中的 keyGenerator 值进行归类, 但其 tModelKey 是一个空值, 这表示由 node 生成的这个 tModelKey 将以字符串 “:keygenerator” 结尾, 使得这个 tModel 成为一个 key generator tModel.

当 tModel 的 tModelKey 对应于某个已注册了的 tModel 时, 这个 API 能够对该 tModel 进行更新.

如果所传递的 tModelKey 值对应于一个已被 delete_tModel API 隐藏掉的 tModel, save_tModel 可以恢复这个 tModel 使之完全可见, 重新出现于 find_tModel 的返回结果中.

在保存操作中, tModel 中的 deleted 属性值都设置为 false.

可以为 tModel 提供多个 overview document, 例如, 技术的和易于阅读的 overview 文档都可以.

当一个要保存的 tModel 带有 keyedReferences, 在 keyedReferences 中用到的所有 tModelKeys 必须已引用已经存在的 tModels, 这一步先于对包含这些引用的 tModel 的处理. save_tModel API 能够包含一系列 tModels, 在这种情况下, 一个 tModel 中的某个 keyedReference 可能引用了这一系列中先创建的 tModelKeys (A save_tModel API call may contain a sequence of tModels, in which case a keyedReference in a tModel may refer to tModelKeys created earlier but not later in the sequence). 一个要新建的 tModel 务必不能引用它自己. 自引用的(Self-referencing) tModels 可以通过两步 save_tModel API 调用来创建, 第一步不带引用, 然后第二部带引用(引用已经被保存了的tModel,即第一步保存的tModel). 如果这些条件不能满足, node 必须返回 E_invalidKeyPassed.

当一个要保存的 tModel 带有 identifierBag or categoryBag 内容, 而这些内容关联到一个 checked value set or category group system tModel, 这些引用必须接受有效性检查, 这一步先于保存操作, 或者 node 必须返回 E_unsupported, 表示自己不支持该被引用的 checked value set or category group system.

Domain key generator tModels：

对于那些使用推荐的 key 语法的 registries 来说, 一个 domain key generator tModel 就建立了一个 key partition, 从这个键分区可以派生出 uddiKeys 并可用在该发布者所控制的其它实体中. 当首次发布一个 domain key generator tModel 时需要做些额外考虑.

1. tModelKey 必须遵从 domain_key 形式, 并且必须以术语: keyGenerator 结尾.

2. tModelKey 必须在 uddi:uddi.org:categorization:types category system 中使用 keyGenerator 值进行归类.

3. 对于建立 key domains, Registry policy 可能要求 tModel 使用签名.

同样, key generator tModels 的发布者可能使用 overviewDoc 去描述键空间是如何定义的.

save_tModel API 首先检查 tModel 是否合适, 如果根据注册中心策略它是可以保存一个 domain key generator tModels, 那么返回 tModelDetail. 如果不能接受这个 tModel, 会在返回的 dispositionReport 中清楚地指明原因, 不再继续处理下去.

如果注册中心有多个 nodes, 返回 tModelDetail 并不意味着该 domain key generator tModel 已经发布成功. 一个允许 publisher-assigned keys 的 registry 必须具有策略确保不会发生 domainKey 冲突. The custodial node MUST ensure that the domain key generator tModel is not in the process of being published simultaneously on some other node. 如果, 在完整复制周期结束后, 没有其它 UDDI node 已经指派或试图指派这个分区(例如, 没有从其它节点收到任何改变记录-change record), 保管节点就完成这个 domain key generator tModel 的发布操作, 然后指派它给它的发布者. 如果其它节点已经分派了该分区, 该 tModel 就不会被发布.

当发布一个 domain key generator tModel 完成后, 保管节点可能通知它的发布者说这个 tModel 已经准备好可以使用了. 一个 node 是否这样做以及通过何种方式这样做是由节点策略决定的. 一个典型的节点策略是通过 email 通知其发布者, 这个 e-mail 地址是在该发布者帐户创建时所提供的那个.

在发布操作完成之前, domain key generator tModel 将在 find_xx and get_xx API 调用结果中被忽略, 在继续调用 save_tModel 时, 将返回一个 E_keyUnavailable 错误.

如果复制周期完成后, 发布者怀疑发布结果, 可以使用 get_tModelDetail 并指定发布 domain key generator tModel 时所使用的 key 进行验证. 如果得到一个 tModel 且该发布者是这个 tModel 的所有者, 就表明操作已经成功. 如果得到一个 tModel 但其它发布者是这个 tModel 的所有者, 那么之前的 save_tModel 操作就是失败的, 因为其他发布者已经先选用这个 domain_key 发布了一个 domain key generator tModel. 如果没有得到 tModel, 那么就是或者 registry 遭遇到失败, 或者两个发布者”同时(simultaneously)”试图使用相同的 key 发布 tModels, 最终两人都不成功. 在上述情形下, save_tModel 操作可能会重试.

试图从一个已经成功发布的 key generator tModel 中移除下面所列的分类将失败, 错误是 E_fatalError, 因为它是一个非常特殊的分类用于将 key generator tModels 从其它 tModels 中区分开来:

<tModelKey=”uddi:uddi.org:categorization:types” keyValue=”keyGenerator” />

返回值：

大部分情况下这个 API 返回一个 tModelDetail 包含该次调用的最终结果, 该结构反映了受影响 tModel 的新注册信息或者等待处理的(pending)注册信息. 返回的 tModel 都带有 tModelKey 属性. 当首次保存一个 domain key generator, 返回的 tModelDetail 里的 tModel 呈现的是中间状态, 直到注册中心的所有节点都已经确定被请求的 key domain 确实是属于该发布者.

如果在 save_tModel 请求中传递多个 tModel elements, 响应的顺序必须完全匹配在保存操作请求中这些 elements 出现的顺序. 如果同一 tModel, 根据 key 判断是否是相同的 tModel, 在 save_tModel API 中出现多次, 在结果中可能为 save_tModel API 中出现的这些 tModel 只列出一次. 如果同一 tModel 在响应中出现多次, 最后一次出现的 tModel 反映了它在注册中心的存储状态.

tModelDetail 具有 0 个或多个 tModel elements

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

· E_accountLimitExceeded: 超出用户的帐户限制.
· E_invalidKeyPassed: 所指定一个或多个 uddiKey 值对要发布的实体来说是无效的 key. tModelKey 值或者不存在, 或者存在但类型不对, 或者没有经过发布者授权使用. 导致这个错误的 key 应该(SHOULD)清楚地在错误文本中指明.

· E_userMismatch: 略.
· E_invalidValue: keyValue 属性所使用的这个值没有通过验证. 应用于 checked value sets(使用keyedReferences进行引用). 错误文本应该(SHOULD)清楚地指出验证失败的 key 和 value 值对.
· E_keyUnavailable: 所提供的 key 已被指派给其他发布者使用, 或者没有在该发布者所拥有的 key generator tModel 定义的键分区中, 或者是该首次保存的这个 domain key generator tModel 已被分派给其他发布者或仍旧在等待处理(pending its first save).

· E_requestTimeout: 该请求没有被执行, 因为必须调用的 validate_values 服务并没有在合理时间范围内返回响应. 这个发生失败的 Web service 的详细信息应该(SHOULD)包含在 dispositionReport element.

· E_unacceptableSignature:  tModel 缺少数字签名或者不满足注册中心的要求. errInfo element 提供更多详细信息.

· E_unsupported: 某个 categoryBag 或 identifierBag 中, 引用了 checked value set 的某个 keyedReference 不能通过 UDDI node 校验, 因为 node 不支持该被引用的 checked value set. 错误文本应该清楚地指明是哪个 keyedReference 没能通过校验.

· E_unvalidatable: 在某个 categoryBag 或 identifierBag 中, 引用了 checked value set 的某个 keyedReference 不能通过 UDDI node 校验, 因为被引用的 tModel 已经标记为无效. 错误文本应该清楚地指出哪个 keyedReference 没能通过校验.

· E_valueNotAllowed: 所引用的 value set 中的某个值是不被允许的.

set_publisherAssertions：

set_publisherAssertions API 用于管理某个发布者所有被记录的关系断言.

参数：

· authInfo: 略.
· publisherAssertion: 可选, 0..∞ . 关系断言构成了一个对两个 businessEntity key 值的引用, 这两个 businessKey 值由关系断言的 fromKey 和 toKey elements 指定, 同时在这个关系断言中的 keyedReference element 指定一个关系指向(父子, or peer 2 peer)表达式(该表达式是必需的). fromKey, toKey, 和 keyedReference 中所有的三部分– tModelKey, keyName, 和 keyValue – 必须指定. 如果在 publisherAssertion elements 中这些 elements 中任意一个缺失, 将返回 E_fatalError. 空的(零长度)keyNames 和 keyValues 是允许的.

行为：

当使用这个 API 后, 该发布者具有的完整断言集合将被立即替换掉. 当这个 API 的调用被处理后, 对于一个给定的发布者, 在本次调用之前存在的那些发布者断言将被 UDDI registry 检查. 任何在本次调用前不存在的新断言将被加入到该发布者所属的断言集合中. 任何已存在但没有出现在本次调用中的断言将被删除掉. 结果, 新关系可能建立完成(例如. 决定于是否具有完成状态), 已存在的关系可能被解散掉. 调用本 API 但不带有任何 publisherAssertion elements 将会删除掉该发布者的所有断言.

Any relationships attributed to assertions previously present but not present in the data provided in this call are deactivated and are no longer visible via the find_relatedBusinesses API. 为了在断言集合中确定唯一性, publisherAssertion element 中的 fromKey, toKey, 和整个 keyedReference 是很重要的. 在检测一个新断言时, publisherAssertion element 中任何内容如与所有已存在断言内容不同, 都将构成一个新的唯一的断言. 由 fromKey and toKey elements 中这两个 businessKey 值所指明的关系方向, 也会关系到确定断言唯一性.

发布者必须拥有fromKey, toKey, 或者这两者所引用的 businessEntity. 如果在断言中传递的这两个 businessKey 值都属于该发布者, 那么该断言将自动完成, 并且在断言中所描述的关系通过 find_relatedBusinesses API 也是可见的. 当发布者只拥有这两个 keys 中的某一个时, 要建立一个关系, 所传递给 API 的断言必须完全匹配由拥有另一个 key 引用的 businessEntity 发布者所建立的断言. 断言完全匹配, 当且只有当他们:

1. 它们的 fromKey 引用相同 businessEntity;

2. 它们的 toKey 引用相同的 businessEntity;

3. 它们的 tModelKey 引用相同的 tModel;

4. 具有完全相同的 keyNames; 并且

5. 具有完全相同的 keyValues.

当一个要保存的 publisherAssertion 在 keyedReference 中使用 tModelKey 引用了一个 checked relationship system, 该引用必须接受有效性检查, 检查要在保存操作完成之前, 或者 node 必须返回 E_unsupported, 指出自己不支持该被引用的 checked relationship system. 对一个关系系统引用的校验必须验证:根据为该关系系统所定义的由它的 tModel 所描述的校验算法, 引用是有效的. 对于可缓存的检查型关系系统, 校验算法验证 对于该关系系统这些 keyedReferences 是有效的.

对于任意节点都支持 subscription APIs 的注册中心来说, 有必要为 publisherAssertion elements 记录修改时间, 这样便于节点有足够的信息作为对订阅请求(包括find_relatedBusinesses和get_assertionStatusReport filters)的响应.

返回值：

成功完成后, 会返回一个 publisherAssertions 结构, 包含当前属于该发布者的所有的关系断言. 如果注册中心区分发布者, 这个结构包含与所传递的 authInfo 相关的断言数据.

这个 API 返回该发布者所创建的所有断言.

错误警告：

发生错误的时候, 必须在 SOAP Fault 中返回一个 dispositionReport element.

· E_invalidKeyPassed: 指出某个 uddiKey 值与任何已知的 businessKey or tModelKey 值都不匹配. 导致该问题的 assertion element 和 key 应该在错误文本中清楚的标明.

· E_userMismatch: 内嵌的 fromKey 和 toKey elements 所指定的 businessKey 值都不是由该发布者所掌握的. 错误文本应该明确地指出究竟是哪个断言导致这个错误.

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/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set

• add_publisherAssertions: 用于向已存在的断言集合中添加关系断言.
• delete_binding: 用于从 registry 中移除一个已有的 bindingTemplate.
• delete_business: 用于删除已有的 businessEntity 信息.
• delete_publisherAssertions: 用于从一个特定发布者所控制的断言集合中删除该特定发布者的断言. 从断言集合中删除断言影响到商业实体关系的可见性. 删除一个断言导致任何基于那个断言的关系都将成为不完整的.
• delete_service: 用于删除一个已有的 businessService.
• delete_tModel: 用于隐藏已有的 tModel 的信息. 任何使用这个方式隐藏掉的 tModel, 对于引用来说, 仍将是可用的, 并且可以通过 get_tModelDetail API 访问, 但从 find_tModel 结果集中是看不到的(即被hidden). 没有任何方式可以(真正、物理)删除一个 tModel.
• get_assertionStatusReport: 用于获得包含发布者断言和状态信息的状态报告. 这种报告对于帮助管理员管理发布者断言来说是非常有用的. 返回的 assertionStatusReport 包括发起该请求的发布者所控制的任何 businessEntity 构成的所有断言的状态.
• get_publisherAssertions: 用于获得一列由某发布者控制管理的发布者断言. 返回的 publisherAssertions 结构包含所有与这个发布者有关联的发布者断言.
• get_registeredInfo: 用于请求一个给定发布者当前所管理的 businesses 和 tModels 的简要列表.
• save_binding: 用于注册新 bindingTemplate 信息或更新已有的 bindingTemplate 信息. 使用这个 API 去管理某注册商业实体所暴露出来的技术能力信息.
• save_business: 用于注册新 businessEntity 信息或更新已有的 businessEntity 信息. 使用这个 API 去管理整个商业实体的全部信息集合, 包括它的 businessService 和 bindingTemplate 结构. 这个 API 在所有 save_xx APIs 中有最广泛的影响.
• save_service: 用于注册或更新一个 businessService 的完整信息.
• save_tModel: 用于注册或更新一个 tModel 信息.
• set_publisherAssertions: 用于保存一个发布者的发布者断言的全部集合. 这个 API 将替换任何已有断言, 导致任何的没有被重新 reasserted 的旧断言被删除掉.

add_publisherAssertions：

调用 add_publisherAssertions API 会把一个或多个 publisherAssertions 加到一个发布者的断言集合中.

参数：

authInfo：同上

publisherAssertion：必需的(1..∞).

一个关系断言由一个 fromKey element 和一个 toKey element, 以及一个必需的表达关系的 keyedReference element 组成. 需要注意, fromKey 和 toKey 引用的都是 businessEntity. fromKey, toKey, 和 keyedReference 中的3部分 – tModelKey, keyName, 和 keyValue 必须(MUST)提供, 否则调用将失败, 错误是 error E_fatalError. 空的(零长度) keyNames 和 keyValues 是允许的.

发布者必须拥有 fromKey, toKey, 或者所有这两者所引用的 businessEntity. 如果一个断言中的这两个 businessKey 值都是该发布者所拥有的, 那么该断言会自动完成, 并且该断言所描述的关系通过 find_relatedBusinesses API 是可见的. 如果发布者只拥有这两个keys中的一个的时候, 该发布者所发布的这个断言必须与拥有另一个 key 引用的 businessEntity 的发布者所发布的断言完全匹配, 才能构成想要的关系. 当且只有当出现如下情形时, 才会对断言进行完全匹配:

1. 在 fromKey 中引用相同的 businessEntity;
2. 在 toKey 中引用相同的 businessEntity;
3. 在 tModelKey 中引用相同的 tModel;
4. 具有完全相同的 keyNames; 并且
5. 具有完全相同的 keyValues.

当一个被添加的 publisherAssertion 在它的 keyedReference 中使用 tModelKey 引用了一个 checked relationship system 的时候, 该引用必须(MUST)接受有效性检查, 这一步骤在完成添加之前, 或者 node 必须返回 E_unsupported, 指出不支持所引用 checked relationship system. 对一个 relationship system 引用的检验必须确认: 根据为该 relationship system 所定义的由它的 tModel 所描述的校验算法, 该引用是有效的. 对于 cached checked relationship systems, 校验算法检验引用的 keyValues 是在该 relationship system 的有效值集合之中的.
对于那些任意 node 都支持 subscription APIs 的 registry, 跟踪 publisherAssertion 修改日期是必要的, 这样 nodes 可以有必要信息作为对订阅请求(包括find_relatedBusinesses and get_assertionStatusReport filters)的响应.

返回值：

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

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

· E_invalidKeyPassed: 同上.
· E_userMismatch: fromKey 和 toKey 所使用的 businessKey 值都不是由该发布者所拥有. 错误文本应该(SHOULD)清楚地指出哪个断言导致这个错误.

delete_binding：

删除一个或多个 bindingTemplate.

参数：

· authInfo: 同上.
· bindingKey: 一个或多个 bindingTemplate 的 key.

返回值：

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

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

· E_invalidKeyPassed: 略.
· E_userMismatch:略.

delete_business：

delete_business API 用于删除一个或多个商业实体的注册信息和该商业实体的 businessEntity 所包含的全部 elements.

参数：

· authInfo: 同上.
· businessKey: 一个或多个 businessEntity 的 key.

UDDI registry 必须(MUST)永久删除 businessEntity 的所有(natural)内容, 包括任何当前内嵌的 businessService 和 bindingTemplate 数据.
如果有对这些被删除掉的 businessService elements 服务投影, 这些服务投影仍将保留(left untouched). Such “broken” service projections appear in their businessEntity as businessService elements containing the businessKey and serviceKey attributes as their only content(仅仅是作为businessEntity的内容出现). 因此, 最好重新梳理一下对发布于其它 businessEntity 的 businessService 数据的引用.
所有 publisherAssertion, 如果它们的 fromKey or toKey 所引用的 businessEntity 已被删除, 该 publisherAssertion 也必须(MUST)被自动删除. 一个被删除的商业实体务必不可(MUST)在调用 find_relatedBusinesses API 时被返回.
任何引用了已被删除掉的 businessEntity 的 transferToken 都将变为无效的, 并且永远不能用于转移任何实体.

返回值：

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

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

· E_invalidKeyPassed: 略.
· E_userMismatch:略.

delete_publisherAssertions：

从一个发布者断言集合中删除一个或多个 publisherAssertion.

参数：

· authInfo: 略.
· publisherAssertion: 一个或多个要删除的断言, 必须完全匹配该发布者断言集合中的断言.

UDDI registry 扫描该发布者的断言集合, 删除掉对所传递的每个 publisherAssertion 所有部分都完全匹配的断言. 任何不能定位(即在registry中找不到相匹配)的断言都将导致一个错误. 使用这个 API 删除断言将使得相对应的关系在调用 find_relatedBusinesses API 时永不可见. 对于任意节点都支持 subscription APIs 的注册中心, 跟踪 publisherAssertion elements 的修改日期是很必要的, 便于节点使用这些必要信息作为对 subscription 请求(包含find_relatedBusinesses and get_assertionStatusReport filters)的回应.

返回值：

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

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

· E_assertionNotFound: 某个断言结构与该发布者断言集合中的断言都不匹配, 或者传递了同一 publisherAssertions element 的多个实例. 导致该问题的断言应该(SHOULD)在错误文本中清楚地指出来.

delete_service：

删除一个或多个 businessService elements.

参数：

· authInfo: 略.
· serviceKey: 一个或多个要删除的businessService的key.

作为这个 API 的调用结果, 所有被包含的 bindingTemplate 数据必须从注册中心删除.
如果一个被删除的 businessService 是另一个 businessEntity 的一个服务投影的目标(target), 该服务投影保留不变. 这样”损坏的(broken)”的服务投影仍出现在它们所在的 businessEntity 中, 它们的 businessService elements 所包含的 businessKey 和 serviceKey 属性只是作为内容出现(Such “broken” service projections appear in their businessEntity and businessService elements containing the businessKey and serviceKey attributes as their only content). 因此, 最好对发布在其它 businessEntity 下的 businessService 数据的引用(即指服务投影)做一下适当调整.

返回值：

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

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

· E_invalidKeyPassed: 某个 key 与任何已知的 serviceKey 都不匹配, 或者传递了同一 serviceKey 的多个实例. 导致该问题的key 应该(SHOULD)在错误文本中清楚地指出来.

· E_userMismatch: 略

delete_tModel：

delete_tModel API 用于逻辑删除一个或多个 tModels. 逻辑删除将隐藏被删除的 tModels, 使之不出现于 find_tModel 的结果集中, 而不是物理删除它们. 如果知道已删除(即隐藏) tModels 的 keys, 那么发布者仍可以建立对该 tModels 的新引用. 删除一个已删除的 tModel 没有任何影响.

参数：

· authInfo: 略.
· tModelKey: 一个或多个要删除的 tModel 的key.

如果一个 tModel 使用这种方法隐藏起来, 它务必不可被物理删除. 任何通过这种方式隐藏起来的 tModels, 通过 get_registeredInfo 和 get_tModelDetail APIs 仍旧是可访问的, 但是不出现在 find_tModel 的返回结果中. 所有其它 inquiry APIs 可以包含对这种已被删除的 tModelKeys 的引用, 引用了这些 tModels 的 UDDI 数据结构仍是可以找到和重新获取到的.
定义 delete_tModel 这种行为的目的是为了确保与一个隐藏的 tModel 相关的详细信息仍旧对当前正在使用该 tModel 的其他人可用. 一个隐藏的 tModel 能够被恢复, 使之在搜索结果中可见, 这需要调用 save_tModel API 并传递该隐藏的 tModel 的原始数据和它的 tModelKey 来完成.
转移一个隐藏掉(即deleted属性设置为TRUE)的 tModel 并非是一个错误.

返回值：

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

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

· E_invalidKeyPassed: 某个 key 与任何已知的 tModelkey 都不匹配, 或者传递了同一 serviceKey 的多个实例. 导致该问题的key 应该(SHOULD)在错误文本中清楚地指出来.

· E_userMismatch: 略

get_assertionStatusReport：

get_assertionStatusReport API 提供了管理功能的支持, 比如确定与某个发布者所管理的 businessEntity 相关的发布者断言的当前状态. 使用这个 API, 发布者可以看到他们所创建的断言的状态, 也能看到其他人所创建的牵扯到自己所管理的 businessEntity 的断言.

参数：

· authInfo: 略.
· completionStatus: 这个可选的参数可以让发布者限制结果集只能是具有指定状态值的 relationships. Assertion status is a calculated result based on the sum total of assertions made by the individuals that control specific business registrations. 当没有提供 completionStatus element 时, 所有的断言包括该发布者所拥有的 businessEntity 的断言被返回, 不管 relationship 是否完成. completionStatus 必须包含以下值之一

• status:complete: 传递这个值使得只有已完成的发布者断言被返回.

• status:toKey_incomplete: 只有由 toKey 所引用的 businessEntity 还没有建立相匹配断言的发布者断言才会被返回.

• status:fromKey_incomplete: 只有由 fromKey 所引用的 businessEntity 还没有建立相匹配断言的发布者断言才会被返回.

• status:both_incomplete. 只应用于 UDDI subscription 环境, 不应该(SHOULD not)出现在一个get_assertionStatusReport请求的响应结果中.

返回值：

成功的话, 返回一个 assertionStatusReport 结构, 内含0个或多个 assertionStatusItem 结构, 这些会按照最后修改时间的升序进行排序.

assertionStatusReport 包含所有完成的和未完成的断言, 可作为管理服务用于确定是否有任何 outstanding, 未完成的断言.
因为经过 get_assertionStatusReport API 认证过的发布者可能拥有多个 businessEntity, assertionStatusReport 结构会显示该发布者所拥有的所有 businessEntity 有关的断言.
assertionStatusReport 由一组 assertionStatusItem elements 组成,  assertionStatusItem element 描述该发布者的 businessEntity 所参与的断言. assertionStatusItem element 有以下形式:

• completionStatus 属性：必需的.
• fromKey 元素：必需的.
• toKey 元素：必需的.  fromKey, toKey 和 keyedReference 一起标识该断言
• keyedReference 元素：必需的.
• keysOwned 元素：必需的. 指定该发布者所管理的那些 businessKeys. keysOwned element 具有以下形式:
  • fromKey 元素：0..1
  • toKey 元素：0..1
  • 或者同时具有 fromKey 和 toKey

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

· E_invalidCompletionStatus: 注册中心不识别所传递的 completionStatus 值. 导致该问题的 completionStatus 应该在错误文本中清楚地标识出来.

get_publisherAssertions：

get_publisherAssertions API 用于获得某发布者的发布者断言的完整集合. 它完善了 get_registeredInfo API, 该 API 只用来获取一个发布者的 businesses, services, bindings, 和 tModels 的信息.

参数：

· authInfo: 略.

返回值：

本 API 返回一个 publisherAssertions 结构, 内含该发布者所建立的每个发布者断言的 publisherAssertion element. 当注册中心区分发布者的时候, 这个信息是与认证信息相关联的. 只有该发布者所创建的断言才会返回. 这些 publisherAssertion elements 将按照最后修改时间的升序排序.

publisherAssertions 结构包含 0 个或多个 publisherAssertion element.

错误警告：

None, other than those common to all UDDI APIs. See Section 12.1 Common Error Codes.

get_registeredInfo：

get_registeredInfo API 用于获取一个发布者所控制的所有 businessEntity 和 tModel 数据的简短列表. 当注册中心区分发布者的时候, 这个结果与 authInfo element 中的认证信息有关. 这个返回信息可用于, 例如, 供其它工具显示注册信息列表, 然后提供 drilldown features. 当执行 save 操作时发生网络错误, 使用这个 API 去查看该未知状态是很方便的.

参数：

· authInfo: 略.
· infoSelection 属性: 这个必需的参数表示要返回哪些 tModels. “all” 表示该发布者所拥有的所有可见的和隐藏的 tModels 都要返回(这是默认值). “visible” 表示只有该发布者所拥有的可见的 tModels 需要返回. “hidden” 表示只有该发布者所拥有的隐藏(逻辑删除)的 tModels 需要返回.

返回值：

完全成功的话, 必须返回一个 registeredInfo 结构, 包含 businessInfos 和 tModelInfos, 其中 businessInfos 列出一组 businessEntity 简短信息, tModelInfos 列出一组 tModel 的简短信息. 本 API 在确定某个发布者拥有的所有 businessEntity 和 tModel 信息时非常有用. 这个结构完善了 get_publisherAssertions API, 该 API 只返回某个发布者所拥有的断言信息. businessInfos and/or tModelInfos will be sorted case-sensitively on the primary name in ascending order, using the collation sequence determined by node policy.
registeredInfo 结构具有如下形式:

• businessInfos 元素：
• tModelInfos 元素：

错误警告：

None, other than those common to all UDDI APIs. See Section 12.1 Common Error Codes.

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/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set

发布实体时使用节点指定的(node-assigned) keys
当发布者没有为新实体提供 keys 时,  UDDI node 将依照 registry policy 指定 keys. Node-assigned keys 必须(MUST)遵从 Section 4.4 关于 uddiKeys 的语法.

发布实体时使用发布者指定的(publisher-assigned)keys

registry 键策略可能(MAY)允许一个实体的 key 由发布者提供. 如果发布者没有为实体提供 key, registry 必须为其指定一个. 因为实体 keys 在一个 registry 中必须(MUST)唯一, 不管它是什么实体类型(即在所有类型的实体中key都必须唯一), 并且, 因为 registries 必须定义关于哪些发布者可以发布何种 keys 的强制性策略, 所以, publisher-assigned keys 是受 UDDI registry 所施行的规则所支配的. 对所有 registry 来说, 必须保证对所有的实体类型来说 key 都是唯一的(Behavior that ensures uniqueness across entity types (businessEntity, businessService, bindingTemplate, tModel and subscription) is REQUIRED for all registries). 这一系列讨论 registry 所应该使用的受推荐的 “uddi:” key 结构. 这种方式提供了唯一性, 并且提升了在多个 registry 间的互操作性, 同时允许建立各种不同的 registry-specific policies. 对这种方式的实践指南可以在规范(Section 9.4.2 <General Keying Policy> and Section 9.4.3 <Policy Abstractions for the UDDI keying scheme> 找到.

Key generator keys 和它们的键分区

为了确保 publisher-generated keys 不与其它的产生冲突, registries 通过如下方式赋予发布者生成 keys 的权力：

1. uddiKeys 的概念空间划分为无重叠的, 按等级排列的分区, 每个分区都可以与一个发布者关联起来.
2. 只有与一个特定分区关联的发布者才有权力使用这个分区去指定keys.
3. 拥有给定分区权限的发布者可以把他管理的这个分区的任一直接下级分区指定给他所选择的任意发布者, provided it has not already designated a publisher to that partition.
4. 拥有某个分区权限的发布者可以把它的权限转移给另外的发布者.
5. 最初,  registry 自己有这个等级分区结构上的根分区的权限.

这些规则可以解释如下：

registry 每个 node 都是一个 keys generator. 这要求 node 能够生成(而非由发布者提供的) keys. 另外, registry policy 可能(MAY)允许独立的个人发布者获得权力成为 uddiKeys 空间中的特定分区的 keys 的生成者(generator). 发布者通过拥有一个特殊的 tModel(叫做key generator tModel) 获得这个权限. key generator tModel 包含一个键生成器的 key, 它指定了发布者可以从中分配 key 的键分区.
key generator key 具有如下形式:
keyGeneratorKey = uddiKey “:keygenerator”
从上级键分区派生出来的 key generator key 由上级键分区的某个 key(如这里是uddiKey) 加上一个非空的, 具有冒号前缀的字符串组成.
可以这样认为, 一个给定 keyGeneratorKey 的完整键分区是如下 key 集合:

1. 与 keyGeneratorKey 一样都基于相同的 uddiKey 而新派生出来的键集合(The set of derivedKeys based on the same uddiKey that the keyGeneratorKey is based upon).
2. 基于这个键分区中的key的 keyGeneratorKeys 集合(The set of keyGeneratorKeys based on a key that is in the partition).
3. domainKey, 如果 keyGeneratorKey 是基于这个domainKey(The domainKey, if the keyGeneratorKey is based upon that domainKey).

需要注意的是, 键分区的 keyGeneratorKey 自己是不在这个键分区之内的.
一个 rootKeyGeneratorKey 是一个非派生出来的 keyGeneratorKey. 即: rootKeyGeneratorKey = (uuidKey / domainKey) “:keygenerator”

伪代码：

If x is a keyGeneratorKey, and y is that key minus the “:keygenerator” suffix,
then  if y is a domainKey
-then x is a top-level keyGenerator, and has no keyGeneratorKey (1.a)
-else y is a derivedKey, based on z,
-and x’s keyGeneratorKey is z:keyGenerator (1.b)
else

-If x is a domainKey
-then x’s keyGeneratorkey is x:keyGenerator (2)
-else x is based on a key y, and x’s keyGenerator is y:keyGenerator (3)

有关键分区的详细情况, 可参考《UDDI 规范 v3 的键分区(Key Partitions)》.

发布者行为

要想成功发布一个使用自己设置的 key 的新 entity, 发布者需要拥有这个 key 所在的键分区的 key generator tModel. 典型地, 发布者通过发布这样的 tModel 来获得键分区的所有权, 但发布者也可以通过其它方式来获得所有权, 例如通过让另一个发布者转移所有权给自己.
当发布者拥有一个 key generator tModel 后, 这个发布者可能(MAY)会发布新的 entity, 并为这些 entity 使用这个 key generator tModel 的键分区中的 key.  只能从非隐藏(即tModel标记为deleted != “true”)的 keyGenerator tModel 来生成新的 keys. 发布者负责管理他所拥有的键分区中的 key 的唯一性. 如果发布者没有这样去做, 又生成了一个已经使用了的 key, 发布操作会默默地(inadvertently)替换掉一个该发布者以前所发布的 entity.
如果发布者在多个 registries 中都拥有具有相同 key 的 key generator tModels – 例如一个在发布者的私有测试 registry, 一个在 UDDI 商业 Registry – 该发布者可能(MAY)会向这些 registries 中发布具有相同 key 的 entities. 这提供了许多有趣的能力. 例如, 发布者也许会选择通过向测试 registries 发布他们自己开发的 UDDI entities, 然后, 在某个合适的时间, 将它们进一步发布到 UDDI Business Registry.

UDDI node 行为

确保 publisher-assigned keys 正确工作.

1. “New” and “existing” entities：发布实体时, 该实体可能是新的, 或是已存在于注册中心.
2. 没有为 entities 指派 key 时的行为：UDDI node 必须生成一个 key 并指派给发布者所没有指派 key 的每个 entity. node 可能会为该(没有指定key的)新 entities 生成 uuidKeys, 或者可能从它所拥有的某个 key generator tModel 的键分区中生成 keys.
   如果一个 registry 它的 nodes 是指派 uddiKeys 给新 entities, 那么该 registry 叫做 root registry. UDDI Business Registry 就是一个 root registry. 一个 registry 的 nodes 通过在 UDDI Business Registry 中发布 key generator tModels 来获得它们的 key generator tModels 的所有权, 那么就说这个 registry 是 UDDI Business Registry 的成员.
3. uuidKeys 的行为：根据 registry policy, 在发布操作过程中, 如果发布者是 uuidKey 的一个可信任发布者, 一个 UDDI node 应该(SHOULD)接受一个 uuidKey 作为一个新 entity 的 key. UDDI nodes 务必不能(MUST NOT)允许其他发布者生成 uuidKeys.
4. key generator keys 的行为：如果一个非 tModel entity 的 key 是由它的发布者指派的, 且这个 key 是一个 key generator key, 那么 UDDI node 务必不可(MUST NOT)发布任何这样的 entity. 如果一个 tModel 的 key 是由它的发布者指派的, 且该 key 是一个 key generator key, 那么该 tModel 务必(MUST)包含一个 category bag, 该 categoryBag 内含一个 keyed reference, 带有 tModelKey 且值设置为 “uddi:uddi.org:categorization:types”, keyValue 被设置为 “keyGenerator”.
5. root key generator keys 行为：根据 registry policy, 在发布操作过程中, UDDI node 应当接受一个 root key generator key 作为一个新的 tModel 的 key, 如果这个 root key generator key 是由获得发布该key权限的发布者所提供的. policy 必须防止2个及2个以上发布者发布具有同样 root key generator key 的 tModels.
6. 其它发布者指派的 keys 的行为：在发布操作时, 如果满足以下条件, UDDI node 应该接受由发布者指派给这些新 entities 的 keys.
   * 发布者提供的 key 依存于一个已存在的 key generator tModel 的键分区, 且该 key generator tModel 不是隐藏的(即deleted!=”true”).
   * 提供该新 key 的发布者应该拥有上面提到的那个 key generator tModel.

注册中心联盟：

一组 registries 可能会合作管理一个单一的多注册中心键空间(multi-registry key space), 这可以通过指派这组中的某个注册中心成为 “root registry”并且指派它去管理这个根分区(root partition) 来实现. 这个集合中的其它注册中心被称作是成员注册中心.
UDDI Business Registry 是 root registry. 它的 policies and procedures 用于使对成员注册中心的管理更简单.
指派一个新的管理者可通过在 root registry 或一个或多个成员注册中心中发布 key generator tModels 来实现. key generator tModel 的所有者是该 tModel 所表示的键分区的命名管理者.

对受验证值集的特殊考虑：

标识符, 分类和关系类型系统统称为”值集(value sets)”. UDDI 允许值集为 checked 或 unchecked. UDDI node 会对注册于UDDI中的受检查值集的引用进行内部检查, 或者使用外部的Web验证服务进行外部检查. UDDI node 也可以选择不支持部分或所有的受检查值集.

当 UDDI node 遇到在一个 keyedReference 中对一个受检查值集的引用时, 它会或者确保引用是经过验证的, 或者令该保存失败. 像这种对受支持的检查型值集的引用将根据为该值集所定义、由它的tModel所描述的验证算法做有效性验证. 当所有检查都成功, save 操作是获得许可的. E_unvalidatable 错误表示该检查型值集是受支持的但它的验证算法是不可用的. E_unsupported 表示该检查型值集不受 node 支持. E_invalidValue 或 E_valueNotAllowed 表示一个或多个引用验证失败. 当检查型值集不受支持时, 该值集的验证算法是不可用的, 或者任何引用都将验证失败, save 操作必须(MUST)失败.
当 UDDI node 支持一个检查型值集时, 它可以自己检查对该值集的引用, 或者询问 Web 验证服务该引用是否有效. 对于可缓存的检查型值集, UDDI node 检验被引用的 keyValues 是在该值集的有效值集合之内. 对检验一个检查型值集的算法的选择是 registry policy 的事情, as detailed in Chapter 9 Policy.
一个 category group system 由一个 keyedRefererenceGroup element 描述. 每个 keyedReferenceGroup 都有一个引用 category group system 的 tModelKey, 和一组包含于该 keyedReferenceGroup 构成实际分类组别的 keyedReference elements. 类似于对检查型值集的引用, 如果所引用的 category group system 是检查型的, 那么会对该 keyedReferenceGroup 执行校验. 根据该 category group system 的 tModel 所描述校验算法, 这样的校验必须要验证 keyedReferenceGroup 是有效的. 对一个引用 cached checked category group system 的 keyedReferenceGroup 的校验包括, 对于 category group system 来说, 检查该 keyedReferenceGroup 所包含的 keyedReference elements 所引用的 tModels 是有效的. 这样一个 cacheable checked category group system 的有效值集是由能够参与到这个组别中的 tModels 的 tModelKeys 集合所定义的.
对非检查型值集, 不对它们的引用做任何校验.

对 xml:lang 属性的特殊考虑：

在调用 save_xx API 过程中, name, description, address, 和 personName 等 UDDI elements 可能(MAY)会使用 xml:lang 属性标识内容使用何种语言表示. 当一个 element 省略掉这个可选的 xml:lang 属性时, 不会为这个 element 保存 xml:lang 属性.
在 UDDI node 数据结构中, Name elements 经常在查询时被首选用于排序. 当一个 UDDI 数据结构有多个 names 时, 排序将基于第一个 name. 需要注意的是, 在保存实体时应该将首选 name 放在最一个位置, 这样可以确保该实体在排序后的结果集中被放在一个正确的位置(proper placement).

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/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set

查找 businessService elements, 返回 serviceList.

参数：

maxRows 属性：可选, 同上

businessKey 属性：可选. 查找这个 businessKey 的 businessEntity 中的 businessService.

投影服务也会包含在结果集中, 除非指定了 “suppressProjectedServices” findQualifier. 如果 businessKey 被省略或指定了一个空值(i.e., businessKey=”"), 这表示要搜索所有 businessEntities 下的 services, 但不包括投影服务.

listHead 属性：可选, 同上

authInfo 元素：可选, 同上

findQualifiers 元素：可选, 同上

name 元素：0..∞. 多个 name 一般会使用 xml:lang 属性.

因为 “exactMatch” 是默认匹配方式, 所以对 name 参数将进行精确匹配(exact match). 如果使用了 “approximateMatch” findQualifier 同时在 name 中又使用了适当的通配符, 那么包含在指定 businessEntity(或者, 如果省略了businessKey或者指定空值, 那么就搜索所有的business) 中的任何匹配 name 值的 businessService 数据将作为结果返回. 如果传递了多个 name 参数, 对这些 name 的匹配方式将是逻辑 OR. 每个 name 可能(MAY)会使用 xml:lang 修饰. 如果指定了语言标记, 那么匹配同时基于 name 和语言. 对语言的匹配将是从左至右、忽略大小写的比较.

categoryBag 元素：包含一列分类引用, 只有匹配所有分类的service才会被返回.(默认是逻辑 AND)

指定适当的 findQualifiers 能够覆盖这个默认匹配方式.

tModelBag 元素：所包含的bindingTemplates具有由这些tModelBag中的tModelKey所指向的技术指纹的businessService.

在 UDDI 中每个 Web service instance 都是用一个 包含于 businessService 中的 bindingTemplate 表示的. 一个bindingTemplate 包含一组 tModel 引用, 称之为它的”技术指纹(technical fingerprint)”. tModelBag 参数是一组 tModelKey 值, 表示搜索出的结果应限于那些 所包含的 bindingTemplates 具有这些(由这些tModelKey指定的)技术指纹的 businessServices.

find_tModel 元素：这是对指定tModelKey(指使用tModelBag)的一种替换用法.

当使用了这个参数的时候, find_tModel 参数将被看作是一个内嵌查询, 先于对服务的查询而执行. 所找到的 tModelKeys 应该是那些匹配 find_tModel element 所含查询条件的 tModels 的 tModelKey. 找到的 tModelKeys 加入到由 tModelBag 指定的(可能是空的)集合中, 这一步也先于对服务的查找.
需注意的是, 给这个内嵌 find_tModel 参数指定 authInfo 参数总是会被忽略. 大结果集的一些行为如返回 listDescription 不适用于内嵌查询参数. 如果在处理这个内嵌查询时发生一个 E_unsupported 错误, 这个错误将向上传播到它的上级(containing) API.

如果指定 find_tModel 参数, 它将被看作是一个内嵌查询. 对作为这个内嵌 find_tModel 参数的结果集中的 tModelKeys 的使用, 就好比它们是通过在一个 tModelBag 参数中提供的一样. 改变集合中的 keys 的顺序或对相同 tModelKey 指定不止一次, 不会改变查找行为.
默认地, 只有那些包含所有的 tModelKey 所指向的技术指纹的 bindingTemplates 才是匹配的(逻辑AND). 指定适当的 findQualifiers 能够覆盖掉这个默认方式, 这样可以查找那些包含任一指定 tModelKey 的 bindingTemplates(逻辑OR).

返回值：

成功的话返回一个serviceList.

truncated 属性：可选

listDescription 元素：可选

serviceInfos 元素：可选. 包含一个或多个 serviceInfo 结构.

serviceInfo 元素：

serviceKey 属性：必需. 服务的serviceKey

businessKey 属性：必需. 服务所属的businessEntity的businessKey

name 元素：0..∞. 服务的 name

如果最终没有匹配查询条件的结果, 返回的 serviceList 结构不包含 serviceInfos element. 如果没有传递查询参数(包括businessKey), 将返回零匹配的结果集. 如果只传递 businessKey 查询参数, 这个 business 下的全部 services 将被返回. 当传递了多个不同的 name 参数, 那么符合条件的 services 是那些匹配所有条件的 services.
如果提供了一个 businessKey, 返回的 serviceList 所包含的 services 只是这个给定的 business 中的 services. 服务投影也将包含在这个列表中, 除非明确地使用 suppressProjectedServices find Qualifier. 当省略 businessKey 或指定空值(i.e., businessKey=”"), 那么将查找所有 businessEntity 的全部 services. 当省略 businessKey 或者留空, 服务投影将不会包含在返回的结果集中, 这是因为它们会在结果集中重复出现.
因为一个 serviceInfo 结构能表达一个已被删除的 businessService 的投影, 在这个 serviceInfo 结构中 name element 是可选的(see Section 5.2.16 save_business on deleting projected services).
如果最终符合条件的结果集太大(由node确定是否太大), 或者符合条件的结果集数超出了 maxRows 属性值, 结果集可能(MAY)会被截取. 当出现这种情况的时候, serviceList 包含属性 “truncated”, 且值设置为 “true”.
作为 truncated 属性的替换用法, registry 可能(MAY)返回一个 listDescription element.

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

· E_invalidCombination: 指定的 findQualifiers 有冲突. 错误文本需清楚地识别出导致这个问题的 findQualifiers.
· E_invalidKeyPassed: 指出所传递的 uddi_key 值与任何已知的 businessKey 或 tModelKey 值都不匹配. The error structure signifies the condition that occurred and the error text clearly calls out the offending key.
· E_unsupported: signifies that one of the findQualifier values passed was invalid. The findQualifier value that was not recognized will be clearly indicated in the error text.
· E_resultSetTooLarge: signifies that the node deems that a result set from an inquiry is too large and does not honor requests to obtain the results for this inquiry, even using subsets. The inquiry that triggered this error SHOULD be refined and re-issued.

find_tModel：

查找 tModel.

参数：

maxRows 属性：可选, 同上

listHead 属性：可选, 同上

authInfo 元素：可选, 同上

findQualifiers 元素：可选, 同上

name 元素：0..1. 要查找的 tModel 的 name.

因为 tModel 只能有一个 name, 所以只能有一个 name 参数. 因为 “exactMatch” 是默认匹配方式, 所以 name 参数必须被精确匹配, 但如果使用 “approximateMatch” findQualifier 且同时使用了适当的通配符, 那么将根据通配符规则进行匹配. name 可能(MAY)使用 xml:lang 进行修饰. 如果指定了语言标记, 搜索结果将是那些同时匹配 name 值和语言的数据. 对语言的匹配将是从左至右、忽略大小写的比较.

identifierBag 元素：这是一列标识符引用, 由 keyedReference elements 构成.

返回的 tModelList 所包含的 tModelInfo elements 应该是那些具有给定的任一(默认是逻辑OR)标识符的 tModel. 指定适当的 findQualifiers 能够覆盖掉这个默认匹配方式.

categoryBag 元素：这是一列分类引用.

返回的 tModelList 所包含的 tModelInfo elements 应该是那些匹配所有给定分类参数的 tModels(默认是逻辑AND). 指定适当的 findQualifiers 能够覆盖掉这个默认匹配方式.

返回值：

成功的话返回 tModelList 结构.

truncated 属性：可选

listDescription 元素：可选

tModelInfos 元素：包含一列 tModelInfo.

tModelInfo：包含 tModelKey 属性和name、description元素.

如果最终没有符合查询条件的结果, 那么tModelList不会包含 tModelInfos element. 如果没有传参数, 也将返回同样的结果.

如果最终符合条件的结果数太大(由node确定是否结果数太大), 或者如果结果数超过了 maxRows 属性值, 结果集可能(MAY)被截断. 当发生这种情况的时候, tModelList 包含属性 “truncated” 且其值设为 “true”.
作为 truncated 属性的替代, registry 可能(MAY)返回一个 listDescription element.

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

· E_invalidCombination: 同上.
· E_invalidKeyPassed: 同上.
· E_unsupported: 同上.
· E_resultSetTooLarge: 同上.

get_bindingDetail：

通过给定的 bindingKey, 找到对应的 bindingTemplate 结构.

参数：

authInfo 元素：同上

bindingKey 元素：0..∞.  要查找的 bindingTemplate 的 bindingKey.

返回值：

成功的话返回bindingDetail. 如果传了多个 bindingKey, 结果将按照这些 keys 在传递时的顺序而返回.
如果传递的 keys 数太大,  node 可能(MAY)截断结果集. 当发生这种情况的时候, bindingDetail 结果包含属性 “truncated” 且其值设为 “true”.
node 务必不能(MUST NOT)返回一个 listDescription element 作为 bindingDetail 的一部分.

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

· E_invalidKeyPassed: 某个 uddi_key 与现有任何已知的 bindingKey 都不匹配. 如果任何一个所传递的 bindingKey 不是有效的 bindingKey, 这个错误将被返回, 而不会返回部分结果. 错误文本要清楚地指出违法的 key.

get_businessDetail：

按给定的 businessKey 查找 businessEntity.

参数：

· authInfo: 可选.
· businessKey: 1..∞.

返回值：

成功的话返回 businessDetail.

businessDetail 包含：

truncated 属性：可选

businessEntity 元素：0..∞

如果传了多个 businessKey, 结果必须按照与这些 keys 被传递时的相同顺序而返回.

如果传递的 keys 数目太大,  node 可能(MAY)截断结果集. 当发生这种情况的时候, businessDetail 包含属性 “truncated” 且其值为 “true”.

使用 get_businessDetail 获取到的 businessEntity elements 能够包含服务投影. 被投影的服务和原本的服务可以通过出现这些服务中的 businessKey 加以区分. 原本包含这个服务的 businessEntity 的 businessKey 会出现在这个服务中. 被投影的服务所拥有的 businessKey 就是原本这个服务所在的 businessEntity 的 businessKey.

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

· E_invalidKeyPassed: 指出所传递的某个 uddi_key 值与现有任何已知的 businessKey 都不匹配. 如果所传递的任一 businessKey 值不是有效的, 那么这个错误将返回, 而不会返回任何部分结果. 错误文本要清楚地指出违法的 key.

get_operationalInfo：

get_operationalnfo API 用于获取实体级别的实体所固有的操作信息(例如数据结构被创建和最后修改的日期和时间, 实体所被发布到的 UDDI node 的标识符和发布者的身份). get_operationalInfo API 返回对应于给定 entityKey 的 operationalInfos 结构.

参数：

· authInfo: 可选.
· entityKey: 1..∞. 可以是 businessEntity, businessService, bindingTemplate or tModel 的 Keys.

返回值：

返回一个 operationalInfos 结构, 内含对应于(请求者所渴望得到的)每个实体的 operationalInfo element.

operationalInfos 元素包含：

truncated 属性：可选

operationalInfo 元素：0..∞.

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

· E_invalidKeyPassed: 同上.

get_serviceDetail：

根据每个给定的 serviceKey, get_serviceDetail API 返回 businessService 结构.

参数：

· authInfo: 同上.
· serviceKey: 1..∞. 要查找的 businessService 的 serviceKey.

返回值：

成功的话返回一个 serviceDetail.

truncated 属性：可选

businessService 元素：0..∞

如果传递多个 serviceKey 值, 结果将按照所传递的这些 keys 的同样顺序返回.
如果传递的 keys 的数量太大, node 可能(MAY)截断结果集. 当出现这种情形时, 响应包含属性 “truncated” 且其值设置为 “true”.

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

· E_invalidKeyPassed：同上

get_tModelDetail

根据给定的每个 tModelKey, get_tModelDetail API 返回 tModel 结构.

参数：

· authInfo: 同上
· tModelKey: 1..∞.

返回值：

成功的话返回一个 tModelDetail.

truncated 属性：同上

tModel 元素：1..∞

如果传递多个 serviceKey 值, 结果将按照所传递的这些 keys 的同样顺序返回.
如果传递的 keys 的数量太大, node 可能(MAY)截断结果集. 当出现这种情形时, 响应包含属性 “truncated” 且其值设置为 “true”.

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

· E_invalidKeyPassed：同上

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/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set

Inquiry API 支持 3 种方式的查询：

1. browse pattern

先进行宽泛查找, 得到大的结果集, 从中选择更具体的信息进行更细微的查找(drill-down).

规范通过提供 find_xxx APIs 支持这种查询. 这种查询得到的是比较粗略的信息. 比如, 调用 find_business, 传递给一个 business name, 或者 business name 的一部分, 也可以使用通配符.  然后会返回一个 businessList 结果, 包含的是一些概要信息, 如keys, names and descriptions.

2. drill-down pattern

核心数据结构的每个实例 – businessEntity, businessService, bindingTemplate and tModel – 都有一个 key, 当使用 find_xx APIs 时, 这个 key 也会出现在概要信息中. 通过把这个 key 传递给相关的 get_xx API, 很容易取得对应实例的全部注册信息.

3. invocation pattern

开发阶段用到, 不详述.

Find Qualifiers：

每个 find_xx APIs 都接受一个可选的 findQualifiers 参数, 可以包含多个 findQualifier 值.  Find qualifiers 可以是 tModelKeys, 也可以是一个包含简短名字的字符串. UDDI 中每个预定义的 findQualifiers 都能用适当的 tModelKey 或者它的简短名字(short name)而被引用. registry 必须支持这两种方式, 必须在接受 find qualifiers 时不区分大小写. 可以增加新的 find qualifiers, 但注册中心没有义务和责任去支持它们. 当 Find qualifiers 没有被 node 识别时, 会返回错误 E_unsupported.

当对 find_xx APIs 指定多个查询标准(multiple criteria)时, 默认的匹配行为是逻辑 “AND”. Find qualifiers 允许默认的搜索行为被覆盖.

无效的 Find Qualifier 组合：

当对一个 find_xx API 使用了不适用的 findQualifier 时, 通常会导致那个 qualifier 被忽略掉, 当有一些情况下,  特定 findQualifiers elements 间是相互排斥的, 如果将它们一起提供给 find_xx 将导致一个 E_invalidCombination 错误. 无效的组合包括:

·  andAllKeys, orAllKeys, and orLikeKeys 是相互排斥的
·  sortByNameAsc and sortByNameDesc 是相互排斥的
·  sortByDateAsc and sortByDateDesc 是相互排斥的
·  combineCategoryBags, serviceSubset and bindingSubset 是相互排斥的
·  exactMatch and approximateMatch 是相互排斥的
·  exactMatch and caseInsensitiveMatch 是相互排斥的
·  binarySort and UTS-10 是相互排斥的, as are all collation algorithm
tModels with each other
·  diacriticSensitiveMatch and diacriticInsensitiveMatch 是相互排斥的
·  exactMatch and diacriticInsensitiveMatch 是相互排斥的
·  caseSensitiveSort and caseInsensitiveSort 是相互排斥的
·  caseSensitiveMatch and caseInsensitiveMatch 是相互排斥的
findQualifier 的值既可以是一个 string (最大长度 255), 也可以是一个 tModelKey.

Node 必须实现以下全部的 find qualifier, 除非特别标明：

·  andAllKeys: 可以使用这个值将 identifierBag 改变为 AND 而不是 OR. 这个值也是 categoryBag and tModelBag 的默认值.

·  approximateMatch: 可以使用通配符进行搜索. “%” 表示任意个字符, “_” 表示任意单个字符, “” 可用来转义. 类似于 SQL 中的 like 语法.

·  binarySort: 可以按照 name 进行二进制排序(binary sort), as represented in Unicode codepoints.

·  bindingSubset:

·  caseInsensitiveMatch: 忽略大小写进行匹配

·  caseInsensitiveSort: 忽略大小写进行排序

·  caseSensitiveMatch: 匹配时大小写敏感的

·  caseSensitiveSort: 排序是大小写敏感的

·  combineCategoryBags: 只能用于 find_business and find_service. In the case of find_business, this qualifier makes the categoryBag entries for the full businessEntity element behave as though all categoryBag elements found at the businessEntity level and in all contained or referenced businessService elements and
bindingTemplate elements were combined. Searching for a category will yield a positive match on a registered business if any of the categoryBag elements contained within the full businessEntity element (including the categoryBag elements within contained or referenced businessService elements or bindingTemplate elements) contains the filter criteria. In the case of find_service, this qualifier makes the categoryBag entries for the full businessService element behave as though all categoryBag elements found at the businessService level and in all contained or referenced elements in the bindingTemplate elements were combined. Searching for a category will yield a positive match on a registered service if any of the categoryBag elements contained within the full businessService element (including the categoryBag elements within contained or referenced bindingTemplate elements) contains the filter criteria. This find qualifier does
not cause the keyedReferences in categoryBags to be combined with the keyedReferences in keyedReferenceGroups in categoryBags when performing the comparison. The keyedReferences are combined with each other, and the keyedReferenceGroups are combined with each other.

·  diacriticInsensitiveMatch: signifies that matching behavior for name, keyValue and keyName (where applicable) should be performed without regard to diacritics. 对这个qualifier的支持, 是可选的

·  diacriticSensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed with regard to diacritics. 这是默认的行为.

·  exactMatch: 精确匹配, 对大小写和读音(diacritics)敏感.

·  orAllKeys: 可以使用这个值将 tModelBag and categoryBag 的行为改变为 OR, 而不是 AND. 对一个 categoryBag 和一个 tModelBagUsing 使用这个 findQualifier, 会导致在 categoryBag and the tModelBag 中的所有 keys 被一起 OR, 而不是被 AND. keyedReferenceGroup 也一样, 也会被改变为对全部key进行OR.

·  orLikeKeys: 当一个 bag container (i.e. categoryBag or identifierBag) 包含多个 keyedReference elements, 来自相同 namespace (e.g. have the same tModelKey value) 的任何 keyedReference 将被一起进行 OR 运算而不是 AND 运算.
例如 “从这个 namespace 查找具有任意这4个值之一的结果, 从这个 namespace 查找具有任意这两个值之一的结果”. keyedReferenceGroups 的行为也类似于 keyedReferences, 就是, 那些具有相同 tModelKey 值的 keyedReferenceGroups 将被一块进行 OR 运算而不是 AND 运算.

·  serviceSubset: 只能用于find_business API, 且只能与 categoryBag 联合使用. It causes the component of the search that involves categorization to use only the categoryBag elements from contained or referenced
businessService elements within the registered data and ignores any entries found in the categoryBag which are not direct descendent elements of registered businessEntity elements. The resulting businessList structure contains those businesses that matched based on this modified behavior, in conjunction with any other search arguments provided. Additionally, the contained serviceInfos elements will only reflect summary data (in a serviceInfo element) for those services (contained or referenced) that matched on one of the supplied categoryBag arguments.

·  signaturePresent: 用于 find_xx API, 限制结果集中的实体或者包含一个 XML 数字签名元素, 或者该实体包含在一个含有数字签名的实体之内. Signature element 可使用 get_xx API 获取, 且应当被 client 验证. UDDI node 可以(或者也可不)验证这个 signature, 因此这个 find qualifier 的使用, 或者一个 Signature element 的存在, 只应当是为了 find_xx API 结果集的refinement, 不应该被 UDDI 客户端作为验证机制使用.

·  sortByNameAsc: 对 find_xx or get_xx inquiry 结果按照 name 进行升序排序. 这种排序优先于对结果集的其它排序方式(This sort is applied prior to any truncation of result sets). 这种排序方式只能应用于那些返回的结果集中最顶级元素有 name 元素的查询, 如果没有指定其它与之冲突的排序 qualifier, 那么这就是默认排序方式.
这个 findQualifier 优先于 sortByDateAsc and sortByDateDesc qualifiers, 但如果使用了一个 sortByDateXxx findQualifier, 但没有使用 sortByNameXxx qualifier, 排序将基于日期, 与 name 有(或无)关(with or without regard to name). 这句意思莫非是可能有的实现会先基于date排序, 然后再考虑对name排序？

·  sortByNameDesc: 对 find_xx or get_xx inquiry 结果按照 name 进行倒序排序. 这种排序优先于对结果集的其它排序方式(This sort is applied prior to any truncation of result sets). 这种排序方式只能应用于那些返回的结果集中最顶级元素有 name 元素的查询. 这是对默认排序方式的逆.
这个 findQualifier 优先于 sortByDateAsc and sortByDateDesc qualifiers, 但如果使用了一个 sortByDateXxx findQualifier, 但没有使用 sortByNameXxx qualifier, 排序将基于日期, 与 name 有(或无)关(with or without regard to name). 这句意思莫非是可能有的实现会先基于date排序, 然后再考虑对name排序？

·  sortByDateAsc: 对 find_xx or get_xx inquiry 结果按照最近修改时间来升序排序 (最早修改的会首先被返回oldest are returned first. 当 name 也包括在返回结果集中时, 这个 find qualifier 也可以跟 sortByNameAsc or sortByNameDesc find qualifiers 结合起来使用. 当这样结合使用的时候, 基于日期排序(date-based sort)的优先级将次于基于名称排序(name-based sort).

·  sortByDateDesc: 对 find_xx or get_xx inquiry 结果按照最近修改时间来倒序排序 (最近修改的会首先被返回. 当 name 也包括在返回结果集中时, 这个 find qualifier 也可以跟 sortByNameAsc or sortByNameDesc find qualifiers 结合起来使用. 当这样结合使用的时候, 基于日期排序(date-based sort)的优先级将次于基于名称排序(name-based sort).

·   suppressProjectedServices: 指出当对 find_service or find_business APIs 使用了这个 findQualifier 时, 务必不能返回(Must NOT)服务投影. 当使用 find_service 而不带 businessKey 时, 这个 findQualifier 默认会自动生效.

·  UTS-10: 对结果基于 Unicode Collation Algorithm 进行排序(this is used to cause sorting of results based on the Unicode Collation Algorithm on elements normalized according to Unicode Normalization Form C.). 这种支持是可选的.

以上只是 UDDI 所定义的 find qualifiers. UDDI registries 和各 nodes 可能会定义更多的 find qualifier 值 – 但所有 nodes 和完全兼容的软件必须支持以上这些 qualifiers, 除非特别标明.

默认排序顺序是 name element 大小写敏感(有的话), 或者最后修改时间 (当没有 name 时), 按照升序, 使用由 node policy 确定的 collation sequence.

Nodes 可能会选择执行额外的(secondary) 基于date 或者 name 的排序. 如果指定了 name-based findQualifier 但没指定date-based 排序, 那么 nodes 可能会在 name-based findQualifier 之上再执行 date-based 排序. 类似地, 当指定
date-based sort findQualifier 但没有 name-based sort, nodes 可能会执行额外的(secondary) name-based sort(当可行时).

指定一个不受支持的排序顺序将导致 E_unsupported 错误.

Support for sorting based tModels describing any collation sequences other than binary by a node is OPTIONAL.

listDescription 的使用：

在调用 inquiry API 的时候, 结果集中的 element 可能会含有 listDescription element.

·  includeCount: 响应中所返回的结果集数目
·  actualCount: 符合这次查询的结果集的数目
·  listHead: 结果集中第一个 element 的位置(起点是1).

使用 find_xx API 查询时, 可以指定 listHead 属性, 从而在符合查询条件的结果集中从某个特定的 element 开始返回结果集.

响应中所能返回的最大结果集数由查询时 maxRows 属性或者 node policy 决定. 当 node 发现结果集太大或者在查询时指定了 maxRows and listHead 而不能在一次查询就全部返回匹配的结果时, listDescription 就会很有用.

例如, 在一次查询时, 指定了 maxRows attribute 为10, 但匹配查询条件的结果集却有18个, 这时响应应该包含1到10, listDescription 中的 actualCount 值为18, listHead 值为1, includeCount 值为10.

如果查询条件和结果没有变化, 再次查询时, 设置了 listHead attribute 值为11, 结果集应该包含11-18, listDescription 的 actualCount 值应是18, listHead 值应该是11, includeCount 值应该是8. 如果 listHead 值小于1, 那么将使用值1. 如果 listHead 值超出了匹配查询条件的结果总数, 将返回一个空的结果集.

由于两次查询之间 registry 内容和结果集可能会有变化, 所以按照上面方式查询将会在后一次查询时出现重复的数据, 甚至错误.只有在结果集大于 node 所能够一次返回的最大数目前提下, 使用 find_xx API 得到的结果集才会包含 listDescription. 例如, 如果结果集包含20个结果且这20个结果都要一次返回, 那么使用 listDescription element 是允许的, 但不是必须的. 如果结果集有1000个且一次只能返回500个, 那么就必须使用 listDescription(如果没有使用 truncated attribute).

关于通配符(wildcards)：

UDDI 中默认的匹配方式是”精确匹配”. 许多 UDDI inquiry APIs 带有 “name,” “keyName,” and “keyValue” 等字符串类型的参数. 所有这样的参数都可以使用通配符实现”模糊匹配”. 可使用 tModelKey uddi:uddi.org:findqualifier:approximatematch 或者简写”approximateMatch”.

通配符可以在参数值中出现多次, “%”代表任意数目的字符, “_”代表一个字符, “”用于转义.

keyedReferences and keyedReferenceGroups 的匹配规则：

如何确定 categoryBag 和 identifierBag 中的 keyedReference 的匹配方式呢？

1. 查找所使用的 categoryBag 或 identifierBag 中引用的 tModelKeys 与 registry 中对应该实体所引用的是相同的 tModel. 这个 key 必须提供且不能为空.
2. 对 keyValues 进行匹配 (默认是 exact match, 但匹配方式可以适当改变); 且
3. 如果 tModelKey 是 “uddi:uddi-org:general_keywords”, 则必须对 keyName 进行匹配(如果使用了approximateMatch findQualifier, 那么将应用通配符匹配规则). 缺失 keyNames 将看作是空的 keyNames. 否则, keyNames 并不重要, 除非在各 API 中特殊说明.

对 keyedReferenceGroup 而言, 查询时的 keyedReferenceGroup 的 tModelKey 必须匹配 registry 中的对应的 keyedReferenceGroup 的 tModelKey, 查询时的 keyedReferenceGroup 中的 keyedReference 必须是 registry 中对应 keyedReferenceGroup 中的 keyedReference 的子集. 其中的 keyedReference 的匹配规则同上.

Inquiry API functions

· find_binding: 查找 bindings. 返回的是 bindingDetail 结构.
· find_business: 查找 businesses. 返回的是 businessList 结构.
· find_relatedBusinesses: 查找与参数 key 所属 businessEntity 有关系的商业实体.
· find_service: 查找 services. 返回的是 serviceList 结构.
· find_tModel: 查找 tModel 信息. 返回的是 tModelList 结构.
· get_bindingDetail: 获取 bindingTemplate 信息. 返回的是 bindingDetail 结构.
· get_businessDetail: 获取 businessEntity 信息. 返回的是 businessDetail 结构.
· get_operationalInfo: 获取操作信息. 返回的是 operationalInfos 结构.
· get_serviceDetail: 获取 businessService 的完整信息. 返回的是 serviceDetail 结构.
· get_tModelDetail: 获取 tModel 的完整信息. 返回的是 tModelDetail 结构.

几个 find_xx APIs (find_binding, find_business and find_service) 支持嵌套查询, 传递给这些 APIs 的参数本身就可以是另外的(内层)查询, 其(内层查询)结果用于过滤外层查询的所有结果. 应用于外(或内)层查询的 findQualifier 不会传播到内(外)层查询. 他们不会向内或向外传播.

find_business：

–maxRows 属性：可选.

这是一个整数值, 指定返回结果集的大小. 这个参数可以与 listHead 联合使用.

–listHead 属性：可选.

这是一个整数值, 标识应该将哪个结果作为结果集中的头一个返回. 客户端可以通过这个参数告诉服务器, 应当从哪个结果开始, 返回结果集的子集. listDescription element 与 truncated attribute 是互相排斥的.

–authInfo 元素: 可选.

包含一个认证 token. 当 Registries 需要限制何人可以执行查询时, 通常就需要在调用 API 时使用这个 authinfo.

–findQualifiers: 可选.

可以使用一组 findQualifier elements 改变搜索的默认方式.

–name 元素：可出现0次或n次.

name: 多个 name 可使用 xml:lang attribute. 因为 “exactMatch” 是默认方式, 所以对这个 name 的值将进行精确严格匹配. 如果既使用 “approximateMatch” findQualifier, name 中又含有通配符, 那么结果集将包含那些匹配这个带通配符的 name 和其它查询条件的 businessEntity. 返回的 businessList 包含 businessInfo 结构. 如果传递给 API 的 name 参数有多个, 匹配将基于逻辑 OR. 每个 name 可能会使用 xml:lang. 如果指定了 language, 符合条件的结果将是那些既匹配 name 又匹配 language 的. 对 language 的匹配将采用从左至右、大小写不敏感的比较方式.

–identifierBag 元素: 可选.

这是一列商业实体标识符引用, 由多个 keyedReference elements 组成. 返回的 businessList 包含符合任一标识符的 businessInfo 结构 (默认是逻辑 OR). 指定 appropriate findQualifiers 能够覆盖掉默认方式.

–categoryBag 元素: 可选.

这是一列 category 引用, 由一系列 keyedReference elements 和 keyedReferenceGroup 结构组成. 返回的 businessList 包含符合所有分类(category)的 businessInfo elements (默认是逻辑 AND). 指定 appropriate findQualifiers 能够覆盖默认方式.

–tModelBag 元素: 可选.

注册中心中 businessEntity 对外暴露的每个 Web service 实例是由包含在这个 businessEntity 中的 bindingTemplate 所表示的. 每个 bindingTemplate 包含一组 tModel 引用, 一般称之为 “技术指纹(technical
fingerprint)”, 表示 web service 的类型. tModelBag 参数是一组 tModelKey elements, 指出搜索结果应该限制在那些具有这些技术指纹的 Web services 的商业实体.

–find_tModel 元素：可选.

这个参数提供了另一个可供选用的或者说额外的方式去指定 tModelKeys, 查找那些具有 tModelBag element 中所描述的技术指纹的商业实体. 当指定了以后, find_tModel 参数将看作是内嵌的查询, 优先于对 business 的搜索. 所找到的 tModelKeys 应当是那些符合 find_tModel element 所包含查询条件的 tModels 的 tModelKey. 所找到的这些 tModelKeys 将被添加到tModelBag 所指定的(也可能是空的)集合中. 应当注意的是, find_tModel 参数中的 authInfo 参数总是被忽略掉. 大结果集的一些行为包括返回一个 listDescription 这样的行为不会应用于一个内嵌的参数. 如果中间(也就是内嵌)查询结果太大, 那么所有的查询将返回 E_resultSetTooLarge, 并带有一个标识: 内嵌的查询返回太多的结果集. 如果在处理这个内嵌参数时出现 E_unsupported 错误, 这个错误将传播到上一级的 API(containing API).

–discoveryURLs 元素: 可选.

这是一列 discoveryURL 结构, 用于匹配那些具有这些 discoveryURL 数据的 businessEntity. 如果想要忽略 useType 属性值而查找 URL, 那么就省略掉 useType attribute 或传给它一个空的值. 如果包含了 useType, 那么将同时匹配 useType 和 URL 值. 返回的 businessList 包含那些匹配任意(逻辑OR) URL 的 businessInfo 结构.

–find_relatedBusinesses 元素：

这个参数是一个内嵌查询, 限制搜索结果集只能是那些与指定商业实体有关系的商业实体. 结果由内层嵌套查询和外层查询结果的交集构成. 需要注意的是, 为这个内嵌的 find_relatedBusinesses 参数指定的 authInfo 参数将被忽略. 大结果集的一些行为包括返回一个 listDescription 不会应用于一个内嵌的参数. 如果产生的中间结果集太大, 那么所有的查询将返回 E_resultSetTooLarge 错误, 带有一个表示：内嵌查询返回太多结果. 如果在处理这个内嵌参数时发生一个 E_unsupported 错误, 这个错误将传播到上级API(containing API).

–返回值：

如果成功的话, 这个 API 将返回一个 businessList.

truncated 属性：可选.

listDescription 元素：可选.

businessInfos 元素：可选.  包含一个或多个businessInfo.

businessInfo 元素：1..∞

businessKey 属性：必须

name 元素: 1..∞

description 元素: 0..∞

serviceInfos 元素: 0..1

如果没有符合查询条件的结果, businessList 结构将是空的 (也就是, 它不包含 businessInfos). 如果没有传递任何参数, 将返回一个零匹配的结果集.

如果符合查询条件的结果集太大, 或者结果集大小超过了 maxRows 属性值, UDDI node 可能会截取这个结果集. 如果发生这种情况,  businessList 将包含属性 “truncated”, 且值为 “true”.

第二级 elements (serviceInfos) 将按照它们被保存时的顺序进行排序.
作为 truncated 属性的替代, registry 可能会返回一个 listDescription element.

错误警告：

当处理这个 API 调用时发生错误, 将会在 SOAP Fault 中返回一个 dispositionReport 结构. 除了对所有 API 都非常常见的错误外, 还有如下与这个 API 相关的错误信息:

· E_invalidCombination: 指定的 findQualifiers 发生冲突. 错误信息需清楚的指出导致出现问题的 findQualifiers.
· E_unsupported: 某个 findQualifier值是无效的. 在错误文本中应清楚地指出不被支持的 findQualifier 值.
· E_invalidKeyPassed: 传递的 uddi_key 或 tModelKey 值不与现有已知的任一 businessKey key 或 tModelKey 值相匹配. 错误结构应该指出发生这个错误的条件, 错误文本应该清楚地指出这个非法的 key.
· E_resultSetTooLarge: node 认为查询结果集太大, 不支持为这次查询请求返回这么大的结果集, 甚至子集. 发生这个错误的查询应该重新提炼并重新发起请求.

find_binding：

查找 bindingTemplate.

find_binding 的 XML 结构如下：

–maxRows 属性：可选. 解释同上

–serviceKey 属性：可选.

查找这个 serviceKey 的 businessService 下的 bindingTemplate. 如果在 find_binding 中不提供这个 serviceKey 属性或者将该属性值留为空, 那么将搜索 registry 中的所有的 businessService, 但投影服务除外(因为可能会重复).

–listHead 属性：可选. 解释同上

–authInfo 元素：可选. 解释同上

–findQualifiers 元素：可选. 解释同上

–tModelBag 元素：可选.

要搜索那些具有这个 tModelKey elements 集合的技术指纹的 bindingTemplate 结构(注意, 符合条件的 bindingTemplate 的技术指纹集合大于等于用于搜索的技术指纹集合). 应当至少提供一个 tModelBag 或 find_tModel 参数, 除非使用 categoryBag 进行搜索.

–find_tModel 元素：可选.

这个参数提供了另一种可选用的方式去指定 tModelKeys 进而查找 bindingTemplate elements. 当指定后, find_tModel 参数将被看成是一个内嵌查询, 且优先级高于对 bindingTemplate elements 的搜索. 找到的 tModelKeys 应该是符合 find_tModel element 中查询条件的 tModels 的 tModelKey. 找到的那些 tModelKeys 会(先于对 bindingTemplates 的查询)被加到由 tModelBag 指定的(可能是空的)集合中. 需注意的是, 这个内嵌的 find_tModel 参数中的 authInfo 参数总是被忽略. 大结果集的一些行为如返回一个 listDescription 将不会应用于内嵌参数. 如果产生的中间结果集太大, 那么所有的查询将返回一个 E_resultSetTooLarge, 带有一个标识：内嵌查询返回了太多的结果. 如果在处理这个内嵌参数时发生一个 E_unsupported 错误, 这个错误将传播到这个内嵌参数的上级 API(containing API, 即外层查询).

–categoryBag 元素：可选.

这是一列 category 引用, 由一系列 keyedReference elements 和 keyedReferenceGroup 结构组成. 返回的 bindingDetail 包含符合所有分类(category)的 bindingTemplate elements (默认是逻辑 AND). 指定 appropriate findQualifiers 能够覆盖默认方式.

如果指定了一个 find_tModel 参数, 它将被看作是一个内嵌查询. 这个内嵌 find_tModel 参数查询出来的 tModelKeys 就好像它们是在一个 tModelBag 参数中提供的一样. 改变集合中这些 keys 的顺序或者对同一个 tModelKey 指定了多次, 都不会改变查找行为和结果.
默认的, 只有那些包含所有这些 tModelKey 所属的技术指纹的 bindingTemplates 才是符合查询条件的(逻辑 AND). 指定适当的 findQualifiers 可以覆盖掉这个行为, 这样只要 bindingTemplate 具有任一技术指纹(具有指定的某一tModelKey)就会被返回(逻辑 OR).

返回值：

成功的话, 返回一个 bindingDetail.

包含：

—truncated属性：可选

—listDescription 元素：可选

—bindingTemplate 元素：0..∞

如果没有符合查询条件的结果, 或者没有传递查询参数, 都将返回一个空的 bindingDetail, 即没有bindingTemplate.

如果符合条件的结果数量超过了 maxRows 属性的值, 结果集可能会被截断. 如果出现这种情况, 响应中包含属性 “truncated” 且值为 “true”.

作为 “truncated” 属性的替代, registry 可能会返回一个 listDescription element.

错误警告：

如果发生错误, 将在 SOAP Fult 中返回一个 dispositionReport element.

· E_invalidCombination: 指定了冲突的 findQualifiers . 错误文本应该清楚地标识出导致这个问题的findQualifiers.
· E_invalidKeyPassed: key无效. 错误结构指出发生的环境, 错误文本清楚地指出不符规则的 key.
· E_resultSetTooLarge: 发生这个查询操作的特定的 node 认为整个结果集太大了. 因此, 结果集不可用. 搜索条件必须进行调整.
· E_unsupported: 某个 findQualifier 值是无效的. 无效的 qualifier 会在文本中清楚地标识出来.

find_relatedBusinesses：

查找与给定 businessEntity 有关系的那些 businessEntity.

maxRows 属性：同上

listHead 属性：同上

authInfo 元素：同上

businessKey 元素：查找与拥有这个 key 的 businessEntity 有关系(这个businessKey可能是作为fromKey, 也可能是作为toKey出现)的 businessEntity, 不能与 fromKey or toKey 同时使用.

findQualifiers 元素：同上

fromKey 元素：查找以这个key为from关系中的businessEntity, 不能与 businessKey 和 toKey 同时使用

keyedReference 元素：0..1. 表述一个relationship类型, 只有匹配这个relationship的businessEntity才会被返回.

keyedReferences and keyedReferenceGroups 的匹配规则前面已经介绍过, 不过例外的是, 如果在查询条件中, 他们是非空的话, keyNames 必须也需要进行比较、匹配. 省略的 keyNames 看作是空的 keyNames.

listHead 元素：同上

maxRows 元素：同上

toKey 元素：查询那些具有关系(relationshit)且该关系含有这个 toKey 的 businessEntity. 这个 toKey 不能与 businessKey or fromKey 同时使用.

返回值：

返回一个 relatedBusinessesList element.

truncated 属性：同上

businessKey 元素：查询时所提供的 businessKey, 可能是 businessKey, fromKey, toKey.

listDescription 元素：同上

relatedBusinessInfos 元素：包含一列 relatedBusinessInfo element

relatedBusinessInfo 元素：

-businessKey 元素：找到的businessEntity的businessKey

-name 元素：找到的businessEntity的name

-description 元素：找到的businessEntity的description

-sharedRelationships 元素：1..2. 跟作为查找条件的businessEntity的关系

-direction 属性：当前找到的这个businessEntity与作为查找条件的businessEntity的关系.

如果作为查找条件的businessEntity的businessKey在关系中是fromKey, 那么这个direction的值是fromKey.

如果作为查找条件的businessEntity的businessKey在关系中是toKey, 那么这个direction的值是toKey.

如果作为查找条件的businessEntity的businessKey在关系中是businessKey, 那么这个direction的值可能是fromKey, 也可能是toKey, 如果作为查找条件的businessEntity的businessKey在关系中是fromKey, 那么direction的值是fromKey; 如果作为查找条件的businessEntity的businessKey在关系中是toKey, 那么direction的值是toKey.

如果在relatedBusinessInfo中有2个sharedRelationships elements, direction属性值为”fromKey”的sharedRelationships element 优先于direction属性值为”toKey”的sharedRelationships element.

-keyedReference 元素：同上

-publisherAssertion 元素：只有在 publisherAssertion 包含 signature 时, 才会返回这个publisherAssertion

如果最终没有找到结果, 那么relatedBusinessesList不会包含relatedBusinessInfos.

如果最终找到的结果集特别大 (由 node 确定是否太大), 或者如果结果集超出了 maxRows 属性所设置的值,  node 可能(MAY) 会截断这个结果集. 当发生这种情况的时候, relatedBusinessesList 包含属性 “truncated” 且值设置为 “true”.
作为 truncated 属性的替代做法, registry 可能(MAY) 返回一个 listDescription element.

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

· E_invalidCombination: 指定了互相冲突的 findQualifiers. 错误文本需清晰的标识出导致这个问题的 findQualifiers.
· E_invalidKeyPassed: 作为参数的 uddi_key or tModelKey 值不匹配现有的任何的 businessKey key or tModelKey 值. 错误结构当指出发生这个错误的条件, 错误文本需清楚的给出这个违法的 key.
· E_unsupported: 某个 findQualifier 值是无效的. 错误文本需清楚地标识出不被识别的 findQualifier 值.
· E_resultSetTooLarge: node 认为查询的结果集太大, 不支持为这个查询请求返回这么大的结果集, 甚至是返回子集. 触发了这个错误的查询应该(SHOULD)加以美化修饰(refined)并重新抛出(re-issued).

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/13 -- UDDI 规范 v3.0.2 – UDDI Programmers APIs 之 Security Policy API Set