UDDI Spec TC Change Request Nnn

/ UDDI Spec TC

UDDI Spec TC Change Request 092

Large Result Handling in Publication APIs

Revision: 1.0

Document identifier:

uddi-spec-tc-cr-nnn-largeResultHandlingInPub-20060824.doc

Location:

Document Control:

Administration Block

Change Request ID / CR-092

Document Identification Block

Title / Large Result Handling in Publication APIs
Spec Versions Affected by this Change Request / V1
V2
V3 / X

Author:

Claus von Riegen

Contributors:

Thierry Tung

Abstract:

The Publication API calls in UDDI 3.0.2 donot provide the capability to manage large result sets. These calls are:

get_assertionStatusReport
get_publisherAssertions
get_registeredInfo

They must be changed to provide the same large result set handling as the Inquiry API calls provide.

Status:

This document is updated periodically on no particular schedule.

Committee members should send comments on this change request to the list. Others should comment at

For information on whether any intellectual property claims have been disclosed that may be essential to implementing this change request, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the UDDI Spec TC web page (

Table of Contents

1Problem Outline

1.1 Terminology

2Solution Outline

3Impact Statement

4Spec Change Detail

4.1 Changes for get_assertionStatusReport (UDDI 3.0.2 section 5.2.12)

4.1.1 XML Schema

4.1.2 Specification “Syntax“ section (5.2.12.2)

4.1.3 Specification “Arguments” section (5.2.12.2)

4.1.4 Specification “Returns” section (5.2.12.3)

4.2 Changes for get_publisherAssertions (UDDI 3.0.2 section 5.2.13)

4.2.1 XML Schema

4.2.2 Specification “Syntax“ section (5.2.13.1)

4.2.3 Specification “Arguments” section (5.2.13.2)

4.2.4 Specification “Returns” section (5.2.13.3)

4.3 Changes for get_registeredInfo (UDDI 3.0.2 section 5.2.14)

4.3.1 XML Schema

4.3.2 Specification “Syntax“ section (5.2.14.1)

4.3.3 Specification “Arguments” section (5.2.14.2)

4.3.4 Specification “Returns” section (5.2.14.3)

5References

5.1 Normative

Appendix A. Acknowledgments

Appendix B. Revision History

Appendix C. Notices

1Problem Outline

There are some Publication API calls in UDDI 3.0.2 that donot provide the capability to manage large result sets, particularly

get_assertionStatusReport
get_publisherAssertions
get_registeredInfo

All these API calls return lists of entities published by an individual publisher. Since an individual publisher can publish a large number of entities, large result set handling for these API calls is necessary.

A UDDI node can apply publication limits to individual publishersas described in section 9.5.6 Node Publication Limits, but this does not make superfluous the need for large result set handling since the size of these limits, and whether there are any limits at all, is node policy.

One example when such limits should not apply is the need for the publication of a large set of tModels, let's say something between 1k and 10k, and the publication needs to be done by a technical user in order to guarantee consistency and up-to-dateness. Calling the get_registeredInfo API with the technical user would represent a problem since the result set is too large and there would be no capability to retrieve the result set in chunks.

1.1Terminology

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].

2Solution Outline

The solution is to make large result set handling in the Publicaiton API the same as in the Inquiry API by adding the maxRows and listHead attributes to the Publicaiton API calls

get_assertionStatusReport
get_publisherAssertions
get_registeredInfo

and by adding the listDescription element and the truncated attribute to their return structures.

3Impact Statement

This is an incompatible API change for clients which, in the case of a large result set, could receive either an extra element or an extra attribute in the structures returned by each of the above API calls.

Note that the minimum impact implementation of this change request for servers would be to ignore the maxRows and listHead attributes in the request and otherwise remain unchanged (i.e. always return the full result set). Such an implementation would have no impact on clients.

As the proposed changes are not without impact, the changes to the API messages will be defined under a new namespace : “urn:uddi-org:api_v3_0_3”.

4Spec Change Detail

4.1Changes for get_assertionStatusReport (UDDI 3.0.2 section 5.2.12)

4.1.1XML Schema

The XML schema’s two complex types for the request and the response must be modifed as shown (changes highlighted)

<xsd:complexType name="get_assertionStatusReport" final="restriction">

<xsd:sequence>

<xsd:element ref="uddi:authInfo" minOccurs="0"/>

<xsd:element ref="uddi:completionStatus" minOccurs="0"/>

</xsd:sequence>

<xsd:attribute name="maxRows" type="xsd:int" use="optional"/>

<xsd:attribute name="listHead" type="xsd:int" use="optional"/>

</xsd:complexType>

<xsd:complexType name="assertionStatusReport" final="restriction">

<xsd:sequence>

<xsd:element ref="uddi:listDescription" minOccurs="0"/>

<xsd:element ref="uddi:assertionStatusItem" minOccurs="0" maxOccurs="unbounded"/>

</xsd:sequence>

<xsd:attribute name="truncated" type="uddi:truncated" use="optional"/>

</xsd:complexType>

4.1.2Specification “Syntax“ section (5.2.12.2)

Add to end the end of the section:

Attributes

Name / Use
maxRows / optional
listHead / optional

4.1.3Specification “Arguments” section (5.2.12.2)

Add to end of section, at the first level of bullet indentation.

listHead: This optional integer value is used to indicate which item SHOULD be returned as the head of the list. The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data. The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5Use of listDescription, for a detailed description of the listHead argument.

maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

4.1.4Specification “Returns” section (5.2.12.3)

Update the diagram following the text “The assertionStatusReport has the form:”as shown (but without the attributes box).

Immediately after the updated diagram, add

Attributes

Name / Use
truncated / optional

Add to the end of section

In the event of a large number of matches (as determined by the node), or if the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated. When this occurs, the assertionStatusReport contains the attribute "truncated" with the value "true".

As an alternative to the truncated attribute, a registry MAY return a listDescription element. See Section 5.1.5Use of listDescription for additional information.

4.2Changes for get_publisherAssertions (UDDI 3.0.2 section 5.2.13)

4.2.1XML Schema

The XML schema’s two complex types for the request and the response must be modifed as shown (changes highlighted)

<xsd:complexType name="get_publisherAssertions" final="restriction">

<xsd:sequence>

<xsd:element ref="uddi:authInfo" minOccurs="0"/>

</xsd:sequence>

<xsd:attribute name="maxRows" type="xsd:int" use="optional"/>

<xsd:attribute name="listHead" type="xsd:int" use="optional"/>

</xsd:complexType>

<xsd:complexType name="publisherAssertions" final="restriction">

<xsd:sequence>

<xsd:element ref="uddi:listDescription" minOccurs="0"/>

<xsd:element ref="uddi:publisherAssertion" minOccurs="0" maxOccurs="unbounded"/>

</xsd:sequence>

<xsd:attribute name="truncated" type="uddi:truncated" use="optional"/>

</xsd:complexType>

4.2.2Specification “Syntax“ section (5.2.13.1)

Add to end the end of the section

Attributes

Name / Use
maxRows / optional
listHead / optional

4.2.3Specification “Arguments” section (5.2.13.2)

Add to end of section, at the first level of bullet indentation.

maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

4.2.4Specification “Returns” section (5.2.13.3)

Update the diagram following the text “The publisherAssertons structure has the form:” as shown (but without the attributes box).

Immediately after the updated diagram, add

Attributes

Name / Use
truncated / optional

Add to the end of section

In the event of a large number of matches (as determined by the node), or if the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated. When this occurs, the publisherAssertions contains the attribute "truncated" with the value "true".

As an alternative to the truncated attribute, a registry MAY return a listDescription element. See Section 5.1.5Use of listDescription for additional information.

4.3Changes for get_registeredInfo (UDDI 3.0.2 section 5.2.14)

4.3.1XML Schema

The XML schema’s two complex types for the request and the response must be modifed as shown (changes highlighted)

<xsd:complexType name="get_registeredInfo" final="restriction">

<xsd:sequence>

<xsd:element ref="uddi:authInfo" minOccurs="0"/>

</xsd:sequence>

<xsd:attribute name="infoSelection" type="uddi:infoSelection" use="required"/>

<xsd:attribute name="maxRows" type="xsd:int" use="optional"/>

<xsd:attribute name="listHead" type="xsd:int" use="optional"/>

</xsd:complexType>

<xsd:complexType name="registeredInfo" final="restriction">

<xsd:sequence>

<xsd:element ref="uddi:listDescription" minOccurs="0"/>

<xsd:element ref="uddi:businessInfos" minOccurs="0"/>

<xsd:element ref="uddi:tModelInfos" minOccurs="0"/>

</xsd:sequence>

<xsd:attribute name="truncated" type="uddi:truncated" use="optional"/>

</xsd:complexType>

4.3.2Specification “Syntax“ section (5.2.14.1)

Replace the Attributes table at the end of the section with:

Attributes

Name / Use
infoSelection / Required
maxRows / optional
listHead / optional

4.3.3Specification “Arguments” section (5.2.14.2)

Add to end of section, at the first level bullet indentation.

maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

4.3.4Specification “Returns” section (5.2.14.3)

Update the diagram following the text “The registeredInfo structure has the form:” as shown (but without the attributes box).

Immediately after the updated diagram, add

Attributes

Name / Use
truncated / optional

Add to the end of section

In the event of a large number of matches (as determined by the node), or if the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated. When this occurs, the registeredInfo contains the attribute "truncated" with the value "true".

As an alternative to the truncated attribute, a registry MAY return a listDescription element. See Section 5.1.5Use of listDescription for additional information.

5References

5.1Normative

[RFC2119]S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, March 1997.

Appendix A.Acknowledgments

The following individuals were members of the committee during the development of this change request:

Appendix B.Revision History

[This appendix is optional]

Rev / Date / By Whom / What

Appendix C.Notices

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

uddi-spec-tc-cr-092-largeresulthandlinginpub-20061130.doc