1 /* 2 * Copyright 2001-2008 The Apache Software Foundation. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 * 16 */ 17 package org.uddi.v3_service; 18 19 import java.math.BigInteger; 20 import java.rmi.Remote; 21 import java.rmi.RemoteException; 22 import java.util.List; 23 import javax.jws.WebMethod; 24 import javax.jws.WebParam; 25 import javax.jws.WebResult; 26 import javax.jws.WebService; 27 import javax.jws.soap.SOAPBinding; 28 import javax.xml.bind.annotation.XmlSeeAlso; 29 import javax.xml.ws.RequestWrapper; 30 import javax.xml.ws.ResponseWrapper; 31 import org.uddi.repl_v3.ChangeRecord; 32 import org.uddi.repl_v3.ChangeRecordIDType; 33 import org.uddi.repl_v3.DoPing; 34 import org.uddi.repl_v3.HighWaterMarkVectorType; 35 import org.uddi.repl_v3.NotifyChangeRecordsAvailable; 36 import org.uddi.repl_v3.TransferCustody; 37 38 /** 39 * This portType defines all of the UDDI replication operations. 40 * 41 * This class was generated by the JAX-WS RI. JAX-WS RI 2.1.5-b03- Generated 42 * source version: 2.1 43 * 44 * <p class="MsoBodyText">UDDI Replication defines four APIs. The first two 45 * presented here are used to perform replication and issue notifications. The 46 * latter ancillary APIs provide support for other aspects of UDDI 47 * Replication.</p> 48 * 49 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 50 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 51 * Roman""> 52 * </span></span>get_changeRecords</p> 53 * 54 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 55 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 56 * Roman""> 57 * </span></span>notify_changeRecordsAvailable</p> 58 * 59 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 60 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 61 * Roman""> 62 * </span></span>do_ping</p> 63 * 64 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 65 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 66 * Roman""> 67 * </span></span>get_highWaterMarks</p> 68 */ 69 @WebService(name = "UDDI_Replication_PortType", targetNamespace = "urn:uddi-org:api_v3_portType") 70 @XmlSeeAlso({ 71 org.uddi.custody_v3.ObjectFactory.class, 72 org.uddi.repl_v3.ObjectFactory.class, 73 org.uddi.subr_v3.ObjectFactory.class, 74 org.uddi.api_v3.ObjectFactory.class, 75 org.uddi.vscache_v3.ObjectFactory.class, 76 org.uddi.vs_v3.ObjectFactory.class, 77 org.uddi.sub_v3.ObjectFactory.class, 78 org.w3._2000._09.xmldsig_.ObjectFactory.class, 79 org.uddi.policy_v3.ObjectFactory.class, 80 org.uddi.policy_v3_instanceparms.ObjectFactory.class 81 }) 82 public interface UDDIReplicationPortType extends Remote { 83 84 /** 85 * The get_changeRecords message is used to initiate the replication of 86 * change records from one node to another. The caller, who wishes to 87 * receive new change records, provides as part of the message a high water 88 * mark vector. This is used by the replication source node to determine 89 * what change records satisfy the caller’s request. <p 90 * class="MsoBodyText">More specifically, the recipient determines the 91 * particular change records that are returned by comparing the originating 92 * USNs in the caller’s high water mark vector with the originating USNs of 93 * each of the changes the recipient has seen from others or generated by 94 * itself. The recipient SHOULD only return change records that have 95 * originating USNs that are greater than those listed in the 96 * changesAlreadySeen highWaterMarkVector and less than the limit required 97 * by either the responseLimitCount or the responseLimitVector.</p> 98 * 99 * <p class="MsoBodyText">In nodes that support pre-bundled replication 100 * responses, the recipient of the get_changeRecords message MAY return more 101 * change records than requested by the caller. In this scenario, the 102 * caller MUST also be prepared to deal with such redundant changes where a 103 * USN is less than the USN specified in the changesAlreadySeen 104 * highWaterMarkVector. </p> 105 * 106 * <p class="MsoBodyText">The response to a get_changeRecords message is a 107 * changeRecords element. Under all circumstances, all change records 108 * returned therein by the message recipient MUST be returned sorted in 109 * increasing order according to the recipient’s local USN.</p> 110 * 111 * <p><b>A node that is ready to initiate replication of change records held 112 * at another node within the registry uses the get_changeRecords message. 113 * Part of the message is a high water mark vector that contains for each 114 * node of the registry the originating USN of the most recent change record 115 * that has been successfully processed by the invocating node. The effect 116 * of receiving a get_changeRecords message causes a node to return to the 117 * calling node change records it has generated locally and processed from 118 * other nodes constrained by the directives of the high water mark vector 119 * specified. As such, by invoking get_changeRecords a node obtains from its 120 * adjacent node all change records (constrained by the high water mark 121 * vector) the adjacent node has generated locally or successfully processed 122 * from other nodes participating in the replication topology. What 123 * constitutes an adjacent node is governed by the replication communication 124 * graph. Replication topology is controlled via a Replication Configuration 125 * Structure. Amongst other parameters, the Replication Configuration 126 * Structure identifies one unique URL to represent the replication point, 127 * soapReplicationURL, of each of the nodes of the registry. 128 * </b></p> 129 * 130 * @param responseLimitVector responseLimitCount or responseLimitVector: A 131 * caller MAY place an upper bound on the number of change records he wishes 132 * to receive in response to this message by either providing a integer 133 * responseLimitCount, or, using responseLimitVector, indicating for each 134 * node in the graph the first change originating there that he does not 135 * wish to be returned. 136 * @param requestingNode requestingNode: The requestingNode element provides 137 * the identity of the calling node. This is the unique key for the calling 138 * node and SHOULD be specified within the Replication Configuration 139 * Structure. 140 * @param changesAlreadySeen changesAlreadySeen: The changesAlreadySeen 141 * element, if present, indicates changes from each node that the requestor 142 * has successfully processed, and thus which should not be resent, if 143 * possible. 144 * @param responseLimitCount responseLimitCount or responseLimitVector: A 145 * caller MAY place an upper bound on the number of change records he wishes 146 * to receive in response to this message by either providing a integer 147 * responseLimitCount, or, using responseLimitVector, indicating for each 148 * node in the graph the first change originating there that he does not 149 * wish to be returned. 150 * @return returns java.util.List<org.uddi.repl_v3.ChangeRecord> A node will 151 * respond with the corresponding changeRecords. 152 * @throws DispositionReportFaultMessage, RemoteException Processing an 153 * inbound replication message may fail due to a server internal error. The 154 * common behavior for all error cases is to return an E_fatalError error 155 * code. Error reporting SHALL be that specified by Section 4.8 – Success 156 * and Error Reporting of this specification. 157 */ 158 @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) 159 @WebResult(name = "changeRecords", targetNamespace = "urn:uddi-org:repl_v3", partName = "body") 160 @WebMethod(operationName = "get_changeRecords", action = "get_changeRecords") 161 public org.uddi.repl_v3.ChangeRecords getChangeRecords( 162 @WebParam(partName = "body", name = "get_changeRecords", targetNamespace = "urn:uddi-org:repl_v3") 163 org.uddi.repl_v3.GetChangeRecords body 164 ) throws DispositionReportFaultMessage,RemoteException; 165 /* 166 @WebMethod(operationName = "get_changeRecords", action = "get_changeRecords") 167 @WebResult(name = "changeRecord", targetNamespace = "urn:uddi-org:repl_v3") 168 @RequestWrapper(localName = "get_changeRecords", targetNamespace = "urn:uddi-org:repl_v3", className = "org.uddi.repl_v3.GetChangeRecords") 169 @ResponseWrapper(localName = "changeRecords", targetNamespace = "urn:uddi-org:repl_v3", className = "org.uddi.repl_v3.ChangeRecords") 170 public List<ChangeRecord> getChangeRecords( 171 @WebParam(name = "requestingNode", targetNamespace = "urn:uddi-org:repl_v3") 172 String requestingNode, 173 @WebParam(name = "changesAlreadySeen", targetNamespace = "urn:uddi-org:repl_v3") 174 HighWaterMarkVectorType changesAlreadySeen, 175 @WebParam(name = "responseLimitCount", targetNamespace = "urn:uddi-org:repl_v3") 176 BigInteger responseLimitCount, 177 @WebParam(name = "responseLimitVector", targetNamespace = "urn:uddi-org:repl_v3") 178 HighWaterMarkVectorType responseLimitVector) 179 throws DispositionReportFaultMessage, RemoteException; 180 */ 181 /** 182 * <p class="MsoBodyText">Nodes can inform other nodes that they have new 183 * change records available for consumption by replication by using this 184 * message. This provides a proactive means through which replication can be 185 * initiated, potentially reducing the latency of the dissemination of 186 * changes throughout the set of UDDI nodes. The 187 * notify_changeRecordsAvailable message is the predecessor to the 188 * get_changeRecords message.</p> 189 * 190 * <p class="MsoBodyText">Each node MUST respond with the message defined 191 * within the Section <a href="#_Ref8980611 ">7.4.2.3</a> <i>Returns</i> 192 * when a valid notify_changeRecordsAvailable message is received. 193 * </p> 194 * 195 * <p class="MsoBodyText">At an interval set by policy after the origination 196 * of new change records within its node, a node SHOULD send this message to 197 * each of the other nodes with which it is configured to communicate this 198 * message according to the currently configured communication graph. It 199 * SHOULD ignore any response (errors or otherwise) returned by such 200 * invocations.</p> 201 * 202 * @param body <p class="MsoBodyText" 203 * style="margin-left:1.0in;text-indent:-.25in"><span 204 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 205 * Roman""> 206 * </span></span><b><i>notifyingNode</i></b>: The parameter to this message 207 * indicates that the notifyingNode has available the indicated set of 208 * changes for request via get_changeRecords. </p> 209 * 210 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 211 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 212 * Roman""> 213 * </span></span><b><i>changesAvailable</i></b>: When sending the 214 * notify_changeRecordsAvailable message, a node shall provide a high water 215 * mark vector identifying what changes it knows to exist both locally and 216 * on other nodes with which it might have had communications. Typically, no 217 * communication graph restrictions are present for the 218 * notify_changeRecordsAvailable message. In the event that the 219 * sending node does not know the USN for a specific node within the 220 * CommunicationGraph, the changesAvailable element MAY contain a 221 * highWaterMark for that node with an unspecified nodeID element. </p> 222 * 223 * <span 224 * style="font-size:10.0pt;font-family:Arial;letter-spacing:-.25pt"></span> 225 * Success reporting SHALL be that specified by Section 4.8 – 226 * Success and Error Reporting of this specification. 227 * @throws DispositionReportFaultMessage, RemoteException Processing an 228 * inbound replication message may fail due to a server internal error. The 229 * common behavior for all error cases is to return an E_fatalError error 230 * code. Error reporting SHALL be that specified by Section 4.8 – Success 231 * and Error Reporting of this specification. 232 */ 233 @WebMethod(operationName = "notify_changeRecordsAvailable", action = "notify_changeRecordsAvailable") 234 @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) 235 public void notifyChangeRecordsAvailable( 236 @WebParam(name = "notify_changeRecordsAvailable", targetNamespace = "urn:uddi-org:repl_v3", partName = "body") 237 NotifyChangeRecordsAvailable body) 238 throws DispositionReportFaultMessage,RemoteException; 239 240 /** 241 * This UDDI API message provides the means by which the current existence 242 * and replication readiness of a node may be obtained. 243 * 244 * @param body 245 * @return returns java.lang.String The response to this message must 246 * contain the operatorNodeID element of the pinged node. 247 * @throws DispositionReportFaultMessage, RemoteException Processing an 248 * inbound replication message may fail due to a server internal error. The 249 * common behavior for all error cases is to return an E_fatalError error 250 * code. Error reporting SHALL be that specified by Section 4.8 – Success 251 * and Error Reporting of this specification. 252 */ 253 @WebMethod(operationName = "do_ping", action = "do_ping") 254 @WebResult(name = "operatorNodeID", targetNamespace = "urn:uddi-org:repl_v3", partName = "body") 255 @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) 256 public String doPing( 257 @WebParam(name = "do_ping", targetNamespace = "urn:uddi-org:repl_v3", partName = "body") 258 DoPing body) 259 throws DispositionReportFaultMessage, RemoteException; 260 261 /** 262 * This UDDI API message provides a means to obtain a list of highWaterMark 263 * element containing the highest known USN for all nodes in the replication 264 * graph. 265 * 266 * @return returns java.util.List<org.uddi.repl_v3.ChangeRecordIDType> <p 267 * class="MsoBodyText">A highWaterMarks element is returned that contains a 268 * list of highWaterMark elements listing the highest known USN for all 269 * nodes in the replication communication graph. See Section <a 270 * href="#_Ref52863431 ">7.2.4</a> <i>High Water Mark Vector</i> for 271 * details.</p> 272 * 273 * <p class="MsoBodyText"><img 274 * src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image129.gif" 275 * border="0" height="88" width="349"></p> 276 * 277 * <p class="MsoBodyText">If the highest originatingUSN for a specific node 278 * within the registry is not known, then the responding node MUST return a 279 * highWaterMark for that node with an originatingUSN of 0 (zero).</p> 280 * 281 * <p class="codeSample"><highWaterMark></p> 282 * 283 * <p class="codeSample"> <nodeID>…</nodeID></p> 284 * 285 * <p class="codeSample"> 286 * <originatingUSN><b>0</b></originatingUSN></p> 287 * 288 * <p class="codeSample"></highWaterMark></p> 289 * @throws DispositionReportFaultMessage, RemoteException Processing an 290 * inbound replication message may fail due to a server internal error. The 291 * common behavior for all error cases is to return an E_fatalError error 292 * code. Error reporting SHALL be that specified by Section 4.8 – Success 293 * and Error Reporting of this specification. 294 */ 295 @WebMethod(operationName = "get_highWaterMarks", action = "get_highWaterMarks") 296 @WebResult(name = "highWaterMark", targetNamespace = "urn:uddi-org:repl_v3") 297 @RequestWrapper(localName = "get_highWaterMarks", targetNamespace = "urn:uddi-org:repl_v3", className = "org.uddi.repl_v3.GetHighWaterMarks") 298 @ResponseWrapper(localName = "highWaterMarks", targetNamespace = "urn:uddi-org:repl_v3", className = "org.uddi.repl_v3.HighWaterMarkVectorType") 299 public List<ChangeRecordIDType> getHighWaterMarks() 300 throws DispositionReportFaultMessage, RemoteException; 301 302 /** 303 * Invoked by the target node in a custody transfer operation in response to 304 * transfer_entities, this API is used by the custodial node to ensure that 305 * permission has been granted to transfer custody of the entities that the 306 * target publisher has requested. The transfer_custody API is in the 307 * replication namespace since it is sent from one node to another node in a 308 * registry using replication. 309 * 310 * @param body <p class="MsoBodyText" 311 * style="margin-left:1.0in;text-indent:-.25in"><span 312 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 313 * Roman""> 314 * </span></span><b><i>transferToken</i></b>: Required argument obtained 315 * from the custodial node via a call to get_transferToken by the publisher 316 * requesting a transfer of custody. The transferToken contains an opaque 317 * token, an expiration date, and the identity of the custodial node. 318 * The transferToken represents permission to transfer the entities that 319 * have been identified via a prior call to the get_transferToken API. The 320 * custodial node MUST verify that the transferToken has not expired and 321 * that the businessKey and tModelKey elements that the target publisher has 322 * provided in transfer_entities are allowed to be transferred as captured 323 * in the transfer token’s opaqueToken.</p> 324 * 325 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 326 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 327 * Roman""> 328 * </span></span><b><i>keyBag</i></b>: One or more uddiKeys associated with 329 * businessEntity or tModel entities that the target publisher is requesting 330 * ownership of at the target node in the registry. The set of keys must be 331 * the same as the set of keys in the keyBag of the get_transferToken API 332 * call from which the given transferToken was once obtained.</p> 333 * 334 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 335 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 336 * Roman""> 337 * </span></span><b><i>transferOperationalInfo</i></b>: Required argument. 338 * The accepting publisher’s authorizedName and the accepting node’s nodeID 339 * are provided on input to the relinquishing custodial node to allow it to 340 * update the operationalInfo associated with the entities whose custody is 341 * being transferred. The authorizedName and nodeID elements are both 342 * required. The accepting node’s nodeID is obtained via the Replication 343 * Configuration structure as described in Section <a href="#_Ref8979701 344 * ">7.5.2</a> <i>Configuration of a UDDI Node – operator element</i>. The 345 * authorizedName is obtained from the call to transfer_entities by the 346 * requesting publisher.</p> 347 * 348 * <p class="MsoBodyText">The custodial node must verify that it has 349 * granted permission to transfer the entities identified and that this 350 * permission is still valid. This operation is comprised of two 351 * steps:</p> 352 * 353 * <p class="MsoBodyText" 354 * style="margin-left:1.0in;text-indent:-.25in">1.<span style="font:7.0pt 355 * "Times New Roman""> 356 * </span>Verification that the transferToken was issued by it, that it has 357 * not expired, that it represents the authority to transfer no more and no 358 * less than those entities identified by the businessKey and tModelKey 359 * elements and that all these entities are still valid and not yet 360 * transferred. The transferToken is invalidated if any of these conditions 361 * are not met.</p> 362 * 363 * <p class="MsoBodyText" 364 * style="margin-left:1.0in;text-indent:-.25in">2.<span style="font:7.0pt 365 * "Times New Roman""> 366 * </span>If the conditions above are met, the custodial node will prevent 367 * any further changes to the entities identified by the businessKey and 368 * tModelKey elements identified. The entity will remain in this state until 369 * the replication stream indicates it has been successfully processed via 370 * the replication stream. </p> 371 * 372 * <p class="MsoBodyText">Upon successful verification of the custody 373 * transfer request by the custodial node, an empty message is returned by 374 * it indicating the success of the request and acknowledging the custody 375 * transfer. </p> 376 * 377 * <p class="MsoBodyText">Following the issue of the empty message, the 378 * custodial node will submit into the replication stream a 379 * changeRecordNewData providing in the operationalInfo, the nodeID 380 * accepting custody of the datum and the authorizedName of the publisher 381 * accepting ownership. The acknowledgmentRequested attribute of this change 382 * record MUST be set to "true".</p> 383 * 384 * <p class="MsoBodyText">Finally, the custodial node invalidates the 385 * transferToken in order to prevent additional calls of the 386 * transfer_entities API.</p> 387 * @throws DispositionReportFaultMessage, RemoteException <p 388 * class="MsoBodyText">If an error occurs in processing this API call, a 389 * dispositionReport structure MUST be returned to the caller in a SOAP 390 * Fault. See Section <a href="#_Ref8979747 ">4.8</a> <i>Success and Error 391 * Reporting. </i>In addition to the errors common to all APIs, the 392 * following error information is relevant here:</p> 393 * 394 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span 395 * style="font-family:Symbol">·<span style="font:7.0pt "Times New 396 * Roman""> 397 * </span></span><b>E_transferNotAllowed</b>: signifies that the transfer of 398 * one or more entities has been rejected by the custodial node. 399 * Reasons for rejection include expiration of the transferToken and 400 * attempts to transfer a set of entities that does not match the one 401 * represented by the transferToken. The reason for rejecting the custody 402 * transfer SHOULD be clearly indicated in the error text.<a 403 * name="_Toc528997532"></a><a name="_Toc525464292"></a><a 404 * name="_Toc535517200"></a></p> 405 * 406 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><a 407 * name="_Toc42047326"><span style="font-family:Symbol">·<span 408 * style="font:7.0pt "Times New 409 * Roman""> 410 * </span></span><b>E_invalidKeyPassed</b>: signifies that one of the 411 * <i>uddiKey</i> values passed for entities to be transferred did not match 412 * with any known businessKey or tModelKey values. The key and element or 413 * attribute that caused the problem SHOULD be clearly indicated in the 414 * error text.</a></p> 415 * 416 * <h3><a name="_Toc45095949">Security Configuration for 417 * transfer_custody</a></h3> 418 * 419 * <p class="MsoBodyText">The use of mutual authentication of UDDI nodes in 420 * conjunction with the transfer_custody API is RECOMMENDED. This MAY be 421 * achieved using mutual X.509v3 certificate-based authentication as 422 * described in the Secure Sockets Layer (SSL) 3.0 protocol. SSL 3.0 423 * with mutual authentication is represented by the tModel 424 * uddi-org:mutualAuthenticatedSSL3 as described within Section <a 425 * href="#_Ref8980795 ">11.3.2</a> <i>Secure Sockets Layer Version 3 with 426 * Mutual Authentication</i>.</p> 427 */ 428 @WebMethod(operationName = "transfer_custody", action = "transfer_custody") 429 @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) 430 public void transferCustody( 431 @WebParam(name = "transfer_custody", targetNamespace = "urn:uddi-org:repl_v3", partName = "body") 432 TransferCustody body) 433 throws DispositionReportFaultMessage, RemoteException; 434 }