org.uddi.v3_service
Interface UDDIValueSetCachingPortType

All Superinterfaces:

Remote

All Known Implementing Classes:

UDDIValueSetCachingImpl

public interface UDDIValueSetCachingPortType
extends Remote

This portType defines all of the UDDI value set caching operations. This class was generated by the JAX-WS RI. JAX-WS RI 2.1.5-b03- Generated source version: 2.1

Whenever a keyedReference is involved in a save operation it may be checked to see that it is valid. Similarly, a keyedReferenceGroup element that is involved in a save operation may also be checked to ensure that it is valid. Checking is performed for tModels that are deemed to be "checked", as determined by the policy of the UDDI registry.

UDDI provides the ability for third parties to register value sets, and then control the validation process used by UDDI to perform such checks. UDDI registries MAY support caching of these external value sets. UDDI registries MAY also support external validation. Node and registry policies determine the manner in which validation of references to external value sets is performed. The APIs in this section can be used by UDDI registries and nodes in their validation policies.

Third parties that want to provide an external checking capability may be required by the UDDI registry to implement a Web service in the same manner that UDDI does (e.g. using SOAP for message passing using literal encoding) that exposes a single method named validate_values. The interface for validate_values is described here.

In some cases a node may desire to eliminate or minimize the number of calls to external validation Web services. It can do so by caching valid values for those external value sets that allow caching of their values. A node has two normative options for obtaining the set of valid values. One is to periodically obtain the set of valid values from those value set providers that implement a Web service that handles the get_allValidValues API. This API is described below. The other method of obtaining a cache of valid values is to accumulate the valid values from successful calls to validate_values.

The Application Programming Interfaces in this section represent capabilities that a UDDI registry MAY use to enable validation of references to value sets. Registry policy determines which external value sets are supported and how. See Section 9.4.19 Value Set Policies and Section 9.6.5Value Sets for more information on registry support of external value sets. These SOAP messages all behave synchronously.

The publicly accessible APIs that are used to support external value set validation are:

· validate_values: Used by nodes to allow external providers of value set validation Web services to assess whether keyedReferences or keyedReferenceGroups are valid. Returns a dispositionReport structure.

· get_allValidValues: Used by nodes that support caching of valid values from cacheable checked value sets to obtain the set of valid values. Returns an empty message or a dispositionReport structure.

Registry policy may require value set providers that offer one of these Web services to publish the bindingTemplate for the service and the tModel for the value set in a particular way so that the proper Web service can be discovered. See Section 9.6.5 Value sets for more information. When a value set provider offers one of these Web services, a tModel for the checked value set SHOULD be published in any registry the provider wishes to offer it, and a bindingTemplate SHOULD be published for the Web service(s) the value set provider offers for the checked value set. The tModel SHOULD have categorizations from the uddi-org:types category system to indicate the type of value set (categorization, identifier, relationship, categorizationGroup), that it is checked (checked), and, if the value set provider allows validation to occur against node caches of valid values, the cacheable categorization should also be provided.

In order for a value set to be considered checked, the tModel MUST first be categorized with the checked value from the uddi-org:types category system. The decision to check such value sets is a registry and node policy decision.

If a value set tModel is categorized as checked, then in response to attempts to publish a keyedReference which uses the checked tModel, nodes MUST either perform the required validation, or return E_unsupported.

The tModel should also have a categorization reference to the bindingTemplate of the get_allValidValues or validate_values Web service that the value set provider designates, using the uddi-org:validatedBy category system. See Section 11.1.1 UDDI Types Category System and Section 11.1.7 Validated By Category System for more information.

The bindingTemplate for the get_allValidValues or the validate_values Web service SHOULD reference in its tModelInstanceDetails the appropriate value set API tModel (Section 11.2.7 Value Set Caching API tModel or Section 11.2.8 Value Set Validation API tModel) as well tModels for all of the value sets the service applies to.

Method Summary

void

getAllValidValues(String authInfo, String tModelKey, javax.xml.ws.Holder<String> chunkToken, javax.xml.ws.Holder<List<ValidValue>> validValue) A UDDI node that supports external value sets MAY invoke a get_allValidValues Web service offered by a value set provider that has granted permission to that registry to cache the valid values for that value set. The external value set provider MAY offer the get_allValidValues Web service and the UDDI node MAY use it. The normal use is to return a full set of valid values for the identified value set. If the value set provider determines there are too many values to return in one chunk, the set of valid values may be returned in chunks.

Method Detail

getAllValidValues

@RequestWrapper(localName="get_allValidValues",
                targetNamespace="urn:uddi-org:vscache_v3",
                className="org.uddi.vscache_v3.GetAllValidValues")
@ResponseWrapper(localName="validValuesList",
                 targetNamespace="urn:uddi-org:vscache_v3",
                 className="org.uddi.vscache_v3.ValidValuesList")
void getAllValidValues(String authInfo,
                                                      String tModelKey,
                                                      javax.xml.ws.Holder<String> chunkToken,
                                                      javax.xml.ws.Holder<List<ValidValue>> validValue)
                       throws DispositionReportFaultMessage,
                              RemoteException

A UDDI node that supports external value sets MAY invoke a get_allValidValues Web service offered by a value set provider that has granted permission to that registry to cache the valid values for that value set. The external value set provider MAY offer the get_allValidValues Web service and the UDDI node MAY use it. The normal use is to return a full set of valid values for the identified value set. If the value set provider determines there are too many values to return in one chunk, the set of valid values may be returned in chunks.

Registry policy may require the value set provider that offers a get_allValidValues Web service to republish its value set tModel when the cache should be re-acquired by participating nodes. See Section 9.6.5 Value Sets for more information.

get_allValidValues can similarly be used to obtain the set of tModelKeys for value sets that can participate in a cached category group system.

The called Web service returns the set of valid values in a validValuesList on success. This structure lists every valid value associated with the value set or category group system that is described by the tModelKey provided. In the event too many values exist to be returned in a single response (i.e., the message size exceeds the maximum number of bytes allowed by the UDDI registry), or the value set provider wants to supply the values in multiple packets, then the validValueList includes the chunkToken element and the API can be re-issued to get the remaining valid values.

Chunking of valid values

If the value set provider determines that there are too many values to be returned in a single group, then the provider SHOULD provide a chunkToken with the results. The chunkToken is a string based token which is used by the value set provider to maintain the state of the set of values for a particular caller, when these results are chunked across multiple responses. Providers should establish their own policies for determining the content and format of the chunkToken. The chunkToken returned with a particular value set result set SHOULD be used to retrieve subsequent results. If no more results are pending, the value of the chunkToken will be "0" or the chunkToken will be absent.

A chunkToken is intended as a short-term aid in obtaining contiguous results across multiple API calls and is therefore likely to remain valid for only a short time. Value set providers may establish policies on how long a chunkToken remains valid.

Parameters:

tModelKey - tModelKey: A required uddiKey value that identifies the specific instance of the tModel which describes the value set or category group system for which a Web service to get all valid values has been provided. It uniquely identifies the category, identifier, or category group system for which valid values are being requested.

authInfo - · authInfo: An optional element that contains an authentication token. Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Providers of get_allValidValues Web services that serve multiple registries and providers that restrict who can use their service may require authInfo for this API.

validValue - RETURN TYPE

A validValuesList structure is returned containing the set of valid values for the external category or identifier system. The list MUST contain a chunkToken if the Web service provider wishes to provide the data in packets. The validValuesList has the form:

And its contained validValue element has the form:

chunkToken - · chunkToken: Optional element used to retrieve subsequent groups of data when the first invocation of this API indicates more data is available. This occurs when a chunkToken is returned whose value is not "0" in the validValuesList structure described in the next section. To retrieve the next chunk of data, the chunkToken returned should be used as an argument to the next invocation of this API.

Throws:

DispositionReportFaultMessage -

If any error occurs in processing this API, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section 4.8 Success and Error Reporting. The following error information is relevant:

· E_invalidKeyPassed: Signifies that the tModelKey passed did not match with the uddiKey of any known tModels. The details on the invalid key SHOULD be included in the dispositionReport element.

· E_noValuesAvailable: Signifies that no values could be returned.

· E_unsupported: Signifies that the Web service does not support this API.

· E_invalidValue: Signifies that the chunkToken value supplied is either invalid or has expired.

RemoteException