org.uddi.v3_service

Interface UDDIReplicationPortType

All Superinterfaces:

Remote

All Known Implementing Classes:

UDDIReplicationImpl

public interface UDDIReplicationPortType
extends Remote

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

UDDI Replication defines four APIs. The first two presented here are used to perform replication and issue notifications. The latter ancillary APIs provide support for other aspects of UDDI Replication.

· get_changeRecords

· notify_changeRecordsAvailable

· do_ping

· get_highWaterMarks

Method Summary

Modifier and Type	Method and Description
String	doPing(DoPing body) This UDDI API message provides the means by which the current existence and replication readiness of a node may be obtained.
ChangeRecords	getChangeRecords(GetChangeRecords body) The get_changeRecords message is used to initiate the replication of change records from one node to another.
List<ChangeRecordIDType>	getHighWaterMarks() This UDDI API message provides a means to obtain a list of highWaterMark element containing the highest known USN for all nodes in the replication graph.
void	notifyChangeRecordsAvailable(NotifyChangeRecordsAvailable body) Nodes can inform other nodes that they have new change records available for consumption by replication by using this message.
void	transferCustody(TransferCustody body) Invoked by the target node in a custody transfer operation in response to transfer_entities, this API is used by the custodial node to ensure that permission has been granted to transfer custody of the entities that the target publisher has requested.

Method Detail

getChangeRecords

ChangeRecords getChangeRecords(GetChangeRecords body)
                        throws DispositionReportFaultMessage,
                               RemoteException

The get_changeRecords message is used to initiate the replication of change records from one node to another. The caller, who wishes to receive new change records, provides as part of the message a high water mark vector. This is used by the replication source node to determine what change records satisfy the caller’s request.

More specifically, the recipient determines the particular change records that are returned by comparing the originating USNs in the caller’s high water mark vector with the originating USNs of each of the changes the recipient has seen from others or generated by itself. The recipient SHOULD only return change records that have originating USNs that are greater than those listed in the changesAlreadySeen highWaterMarkVector and less than the limit required by either the responseLimitCount or the responseLimitVector.

In nodes that support pre-bundled replication responses, the recipient of the get_changeRecords message MAY return more change records than requested by the caller. In this scenario, the caller MUST also be prepared to deal with such redundant changes where a USN is less than the USN specified in the changesAlreadySeen highWaterMarkVector.

The response to a get_changeRecords message is a changeRecords element. Under all circumstances, all change records returned therein by the message recipient MUST be returned sorted in increasing order according to the recipient’s local USN.

A node that is ready to initiate replication of change records held at another node within the registry uses the get_changeRecords message. Part of the message is a high water mark vector that contains for each node of the registry the originating USN of the most recent change record that has been successfully processed by the invocating node. The effect of receiving a get_changeRecords message causes a node to return to the calling node change records it has generated locally and processed from other nodes constrained by the directives of the high water mark vector specified. As such, by invoking get_changeRecords a node obtains from its adjacent node all change records (constrained by the high water mark vector) the adjacent node has generated locally or successfully processed from other nodes participating in the replication topology. What constitutes an adjacent node is governed by the replication communication graph. Replication topology is controlled via a Replication Configuration Structure. Amongst other parameters, the Replication Configuration Structure identifies one unique URL to represent the replication point, soapReplicationURL, of each of the nodes of the registry.

Parameters:

responseLimitVector - responseLimitCount or responseLimitVector: A caller MAY place an upper bound on the number of change records he wishes to receive in response to this message by either providing a integer responseLimitCount, or, using responseLimitVector, indicating for each node in the graph the first change originating there that he does not wish to be returned.

requestingNode - requestingNode: The requestingNode element provides the identity of the calling node. This is the unique key for the calling node and SHOULD be specified within the Replication Configuration Structure.

changesAlreadySeen - changesAlreadySeen: The changesAlreadySeen element, if present, indicates changes from each node that the requestor has successfully processed, and thus which should not be resent, if possible.

responseLimitCount - responseLimitCount or responseLimitVector: A caller MAY place an upper bound on the number of change records he wishes to receive in response to this message by either providing a integer responseLimitCount, or, using responseLimitVector, indicating for each node in the graph the first change originating there that he does not wish to be returned.

Returns:

returns java.util.List A node will respond with the corresponding changeRecords.

Throws:

DispositionReportFaultMessage, - RemoteException Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8 – Success and Error Reporting of this specification.

DispositionReportFaultMessage

RemoteException

notifyChangeRecordsAvailable

void notifyChangeRecordsAvailable(NotifyChangeRecordsAvailable body)
                           throws DispositionReportFaultMessage,
                                  RemoteException

Nodes can inform other nodes that they have new change records available for consumption by replication by using this message. This provides a proactive means through which replication can be initiated, potentially reducing the latency of the dissemination of changes throughout the set of UDDI nodes. The notify_changeRecordsAvailable message is the predecessor to the get_changeRecords message.

Each node MUST respond with the message defined within the Section 7.4.2.3 Returns when a valid notify_changeRecordsAvailable message is received.

At an interval set by policy after the origination of new change records within its node, a node SHOULD send this message to each of the other nodes with which it is configured to communicate this message according to the currently configured communication graph. It SHOULD ignore any response (errors or otherwise) returned by such invocations.

Parameters:

body -

· notifyingNode: The parameter to this message indicates that the notifyingNode has available the indicated set of changes for request via get_changeRecords.

· changesAvailable: When sending the notify_changeRecordsAvailable message, a node shall provide a high water mark vector identifying what changes it knows to exist both locally and on other nodes with which it might have had communications. Typically, no communication graph restrictions are present for the notify_changeRecordsAvailable message. In the event that the sending node does not know the USN for a specific node within the CommunicationGraph, the changesAvailable element MAY contain a highWaterMark for that node with an unspecified nodeID element.

Success reporting SHALL be that specified by Section 4.8 – Success and Error Reporting of this specification.

Throws:

DispositionReportFaultMessage, - RemoteException Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8 – Success and Error Reporting of this specification.

DispositionReportFaultMessage

RemoteException

doPing

String doPing(DoPing body)
       throws DispositionReportFaultMessage,
              RemoteException

This UDDI API message provides the means by which the current existence and replication readiness of a node may be obtained.

Parameters:

body -

Returns:

returns java.lang.String The response to this message must contain the operatorNodeID element of the pinged node.

Throws:

DispositionReportFaultMessage, - RemoteException Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8 – Success and Error Reporting of this specification.

DispositionReportFaultMessage

RemoteException

getHighWaterMarks

@RequestWrapper(localName="get_highWaterMarks",
                targetNamespace="urn:uddi-org:repl_v3",
                className="org.uddi.repl_v3.GetHighWaterMarks")
 @ResponseWrapper(localName="highWaterMarks",
                 targetNamespace="urn:uddi-org:repl_v3",
                 className="org.uddi.repl_v3.HighWaterMarkVectorType")
List<ChangeRecordIDType> getHighWaterMarks()
                                                                                                                                                                                                                                                                                                                                                                                                throws DispositionReportFaultMessage,
                                                                                                                                                                                                                                                                                                                                                                                                       RemoteException

This UDDI API message provides a means to obtain a list of highWaterMark element containing the highest known USN for all nodes in the replication graph.

Returns:

returns java.util.List

A highWaterMarks element is returned that contains a list of highWaterMark elements listing the highest known USN for all nodes in the replication communication graph. See Section 7.2.4 High Water Mark Vector for details.

If the highest originatingUSN for a specific node within the registry is not known, then the responding node MUST return a highWaterMark for that node with an originatingUSN of 0 (zero).

<highWaterMark>

<nodeID>…</nodeID>

<originatingUSN>0</originatingUSN>

</highWaterMark>

Throws:

DispositionReportFaultMessage, - RemoteException Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8 – Success and Error Reporting of this specification.

DispositionReportFaultMessage

RemoteException

transferCustody

void transferCustody(TransferCustody body)
              throws DispositionReportFaultMessage,
                     RemoteException

Invoked by the target node in a custody transfer operation in response to transfer_entities, this API is used by the custodial node to ensure that permission has been granted to transfer custody of the entities that the target publisher has requested. The transfer_custody API is in the replication namespace since it is sent from one node to another node in a registry using replication.

Parameters:

body -

· transferToken: Required argument obtained from the custodial node via a call to get_transferToken by the publisher requesting a transfer of custody. The transferToken contains an opaque token, an expiration date, and the identity of the custodial node. The transferToken represents permission to transfer the entities that have been identified via a prior call to the get_transferToken API. The custodial node MUST verify that the transferToken has not expired and that the businessKey and tModelKey elements that the target publisher has provided in transfer_entities are allowed to be transferred as captured in the transfer token’s opaqueToken.

· keyBag: One or more uddiKeys associated with businessEntity or tModel entities that the target publisher is requesting ownership of at the target node in the registry. The set of keys must be the same as the set of keys in the keyBag of the get_transferToken API call from which the given transferToken was once obtained.

· transferOperationalInfo: Required argument. The accepting publisher’s authorizedName and the accepting node’s nodeID are provided on input to the relinquishing custodial node to allow it to update the operationalInfo associated with the entities whose custody is being transferred. The authorizedName and nodeID elements are both required. The accepting node’s nodeID is obtained via the Replication Configuration structure as described in Section 7.5.2 Configuration of a UDDI Node – operator element. The authorizedName is obtained from the call to transfer_entities by the requesting publisher.

The custodial node must verify that it has granted permission to transfer the entities identified and that this permission is still valid. This operation is comprised of two steps:

1. Verification that the transferToken was issued by it, that it has not expired, that it represents the authority to transfer no more and no less than those entities identified by the businessKey and tModelKey elements and that all these entities are still valid and not yet transferred. The transferToken is invalidated if any of these conditions are not met.

2. If the conditions above are met, the custodial node will prevent any further changes to the entities identified by the businessKey and tModelKey elements identified. The entity will remain in this state until the replication stream indicates it has been successfully processed via the replication stream.

Upon successful verification of the custody transfer request by the custodial node, an empty message is returned by it indicating the success of the request and acknowledging the custody transfer.

Following the issue of the empty message, the custodial node will submit into the replication stream a changeRecordNewData providing in the operationalInfo, the nodeID accepting custody of the datum and the authorizedName of the publisher accepting ownership. The acknowledgmentRequested attribute of this change record MUST be set to "true".

Finally, the custodial node invalidates the transferToken in order to prevent additional calls of the transfer_entities API.

Throws:

DispositionReportFaultMessage, - RemoteException

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section 4.8 Success and Error Reporting. In addition to the errors common to all APIs, the following error information is relevant here:

· E_transferNotAllowed: signifies that the transfer of one or more entities has been rejected by the custodial node. Reasons for rejection include expiration of the transferToken and attempts to transfer a set of entities that does not match the one represented by the transferToken. The reason for rejecting the custody transfer SHOULD be clearly indicated in the error text.

· E_invalidKeyPassed: signifies that one of the uddiKey values passed for entities to be transferred did not match with any known businessKey or tModelKey values. The key and element or attribute that caused the problem SHOULD be clearly indicated in the error text.

Security Configuration for transfer_custody

The use of mutual authentication of UDDI nodes in conjunction with the transfer_custody API is RECOMMENDED. This MAY be achieved using mutual X.509v3 certificate-based authentication as described in the Secure Sockets Layer (SSL) 3.0 protocol. SSL 3.0 with mutual authentication is represented by the tModel uddi-org:mutualAuthenticatedSSL3 as described within Section 11.3.2 Secure Sockets Layer Version 3 with Mutual Authentication.

DispositionReportFaultMessage

RemoteException