View Javadoc
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.rmi.Remote;
20  import java.rmi.RemoteException;
21  import java.util.List;
22  import javax.jws.WebMethod;
23  import javax.jws.WebParam;
24  import javax.jws.WebResult;
25  import javax.jws.WebService;
26  import javax.jws.soap.SOAPBinding;
27  import javax.xml.bind.annotation.XmlSeeAlso;
28  import javax.xml.ws.Holder;
29  import javax.xml.ws.RequestWrapper;
30  import javax.xml.ws.ResponseWrapper;
31  import org.uddi.sub_v3.DeleteSubscription;
32  import org.uddi.sub_v3.GetSubscriptionResults;
33  import org.uddi.sub_v3.Subscription;
34  import org.uddi.sub_v3.SubscriptionResultsList;
35  
36  /**
37   * This portType defines all of the UDDI subscription operations.
38   *
39   * This class was generated by the JAX-WS RI. JAX-WS RI 2.1.5-b03- Generated
40   * source version: 2.1
41   *
42   * Subscription provides clients, known as subscribers, with the ability to register their interest in receiving information concerning changes made in a UDDI registry.  These changes can be scoped based on preferences provided with the request.  The APIs described below support this capability.  Usage scenarios and examples are provided in Appendix C Supporting Subscribers.  Each of the subscription APIs described here are OPTIONAL for UDDI implementations and MAY be implemented entirely at the discretion of a Node.<br><br>
43   * 
44   * <p class="MsoBodyText">The subscription API set satisfies a variety of
45  requirements.&nbsp; The flexibility of the subscription API allows monitoring of activity
46  in a registry by registering to track new, changed and deleted entries for each
47  of these entities:</p>
48  
49  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
50  </span></span>businessEntity</p>
51  
52  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
53  </span></span>businessService</p>
54  
55  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
56  </span></span>bindingTemplate</p>
57  
58  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
59  </span></span>tModel</p>
60  
61  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
62  </span></span>related businessEntity</p>
63  
64  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
65  </span></span>publisherAssertion (limited to those publisherAssertions for
66  which the subscriber owns at least one of the businesses referenced)</p>
67  
68  <p class="MsoBodyText">With the exception of single publisher registries
69  subscription typically is limited to authorized clients as a matter of node
70  policy.&nbsp; Therefore, subscribers MUST typically authenticate with the node
71  before saving subscription requests.&nbsp; Individual nodes, including those in the
72  UDDI Business Registry, MAY establish policies concerning the use of the
73  subscription APIs they choose to offer. Such policies might include restricting
74  the use of subscription, defining which APIs are supported, establishing
75  whether subscriptions require authentication, defining special rules affecting
76  different classes of subscriptions, or even imposing fees for the use of these
77  services.&nbsp; The use of the authInfo argument is OPTIONAL throughout the
78  subscription APIs, although registries which support multiple users or which
79  require authentication for publishing operations typically require it.&nbsp; </p>
80  
81  <p class="MsoBodyText">Subscription allows subscribers to "monitor" a
82  particular subset of data within a registry.&nbsp; Two patterns are defined.&nbsp; Nodes MAY support either or both:</p>
83  
84  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
85  </span></span>Asynchronous notification – subscribers choose to be
86  asynchronously notified by the node when registry data of interest changes via
87  calls to the notify_subscriptionListener API, which they implement as a "subscription
88  listener" service.</p>
89  
90  <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
91  </span></span>Synchronous change tracking – subscribers issue a synchronous
92  request using the get_subscriptionResults API to obtain information on activity
93  in the registry which matches their subscription preferences.</p>
94  
95  <p class="MsoBodyText">A subscription request establishes criteria for the
96  subscription and specifies how and if the subscriber is to be notified of
97  changes matching the specified criteria.&nbsp; Any of the existing standard inquiry
98  APIs (find_xx and get_xx) may be used within a subscription request to define
99  the criteria, although nodes are free to restrict which inquiry APIs are
100 supported in subscription as a matter of policy.&nbsp; The duration, or life of a
101 subscription is also a matter of node policy, but subscribers can renew existing
102 subscriptions periodically instead of having to create new ones.&nbsp; Subscribers
103 may also create multiple subscriptions.&nbsp; Each subscription request is treated
104 independently.&nbsp; The level of detail provided for the data returned is
105 controlled by the subscription request.</p>
106 
107 <p class="MsoBodyText">When asynchronous notifications are requested,
108 subscriptions provide information on new, changed or deleted entities within a
109 registry that occur <i>after</i> the point in time that the subscription is
110 registered.&nbsp; A node notifies subscribers based upon its identification of data
111 matching the requested subscription criteria.&nbsp; Subscribers can choose to have
112 these notifications provided via email or an HTTP/SOAP-based Web service, which
113 the subscriber MAY implement. Such services are called "subscription
114 listeners."&nbsp; Notifications are made periodically rather than in response
115 to the continuous stream of changes that normally occur within the registry.&nbsp;
116 This means that subscription results provided via notifications pertain only to
117 the <i>current</i> state of the entities at the time they are reported –
118 intermediate state changes are not provided.&nbsp; While subscribers can specify a
119 frequency for these notifications, nodes MAY choose to restrict this as a
120 matter of policy.</p>
121 
122 <p class="MsoBodyText">When synchronous requests are made for subscription
123 results, the <i>current</i> state of the registry data, which matches the
124 subscription criteria, is returned for entries that were last created, changed
125 or deleted within a specified date range.&nbsp; Prior states of the registry data
126 are not available and are not returned.</p>
127 
128 <p class="MsoBodyText">Subscriptions are owned by the subscriber who creates
129 them.&nbsp; A subscriptionKey, which distinguishes each individual subscription, is
130 not visible to anyone except the subscriber.&nbsp; While node policy MAY permit others besides the subscription’s owner to receive or retrieve subscription results,
131 such interested parties require knowledge of the relevant subscriptionKey from
132 the subscription owner in order to do so.</p>
133 
134 <h4 style="margin-left:0in;text-indent:0in"><a name="_Toc42047329"></a><a name="_Ref535515666">5.5.1.1 Definition of Changed Entities</a></h4>
135 
136 <p class="MsoBodyText">As stated above, the subscription API allows monitoring of
137 new, changed and deleted entities. This section provides the definition of
138 changed entities.&nbsp; The following are the criteria for considering an entity to
139 have been "changed":</p>
140 
141 <p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
142 margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
143 </span></span>For businessEntity, businessService, bindingTemplate, and tModel:
144 <br>
145 The entity is considered to be changed if the modifiedIncludingChildren element
146 of the operationalInfo element of the entity has been changed.</p>
147 
148 <p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
149 margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
150 </span></span>For publisherAssertion:<br>
151 A publisherAssertion is considered to be changed if the publisher has updated
152 the publisherAssertion via the set_publisherAssertions,&nbsp; or
153 add_publisherAssertions APIs.</p>
154 
155 <p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
156 margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
157 </span></span>For related businessEntity: <br>
158 A related businessEntity (related to the business specified in the businessKey
159 argument of find_relatedBusinesses API) is considered to be changed if either:</p>
160 
161 <p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
162 margin-left:1.5in;text-indent:-.25in">1.<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
163 </span>the related businessEntity is changed, or</p>
164 
165 <p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
166 margin-left:1.5in;text-indent:-.25in">2.<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
167 </span>at least one of the two reciprocal publisherAssertions that represents
168 the relationship is changed.</p>
169 
170 <h3><a name="_Toc85908130"></a><a name="_Toc53709324"></a><a name="_Toc45096409"></a><a name="_Toc45095952">5.5.2 Specifying Durations</a></h3>
171 
172 <p class="MsoBodyText">Time durations used in the subscription APIs are of type
173 xsd:duration defined in XML Schema from <a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#ISO8601"><span style="color:windowtext;text-decoration:none">[ISO 8601]</span></a>.&nbsp; Any form
174 supported by this data type is permitted.&nbsp; For example, the lexical
175 representation extended format can be used, which is of the form PnYnMnDTnHnMnS,
176 where nY represents the number of years, nM the number of months, nD the number
177 of days, 'T' is the date/time separator, nH the number of hours, nM the number
178 of minutes and nS the number of seconds. The "P" identifies the field
179 as duration.&nbsp; The number of seconds can include decimal digits to arbitrary
180 precision.</p>
181 
182 <h3><a name="_Toc85908131"></a><a name="_Toc53709325"></a><a name="_Toc45096410"></a><a name="_Toc45095953"></a><a name="_Toc42047330">5.5.3 Specifying Points in Time</a></h3>
183 
184 <p class="MsoBodyText">Points in time used in the subscription APIs are all of
185 the XML Schema type, xsd:dateTime.&nbsp; Two points in time are used to specify a
186 period of time.</p>
187 
188 <h3><a name="_Toc85908132"></a><a name="_Toc53709326"></a><a name="_Toc45096411"></a><a name="_Toc45095954"></a><a name="_Toc42047331"></a><a name="_Ref3402225">5.5.4 Subscription
189 Coverage Period</a></h3>
190 
191 <p class="MsoBodyText">The APIs, which support each of the patterns previously
192 described for obtaining subscription results, accept a coveragePeriod argument,
193 which is composed of two points in time.&nbsp; Each of these corresponds to the last
194 point in time which any given entity in the registry was modified (i.e.,
195 created, deleted or changed).&nbsp; The syntax of this element is:</p>
196 
197 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image094.gif" border="0" height="104" width="357"></p>
198 
199 <p class="MsoBodyText">Where<b><i>:</i></b></p>
200 
201 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
202 </span></span><b>startPoint</b>: Signifies the point in time after which
203 subscription results are to be collected and/or returned. The startPoint is
204 optional. If it is not specified, this indicates that all available results are
205 to be returned from the beginning of the registry.</p>
206 
207 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
208 </span></span><b>endPoint</b>:&nbsp; Signifies the point in time corresponding to
209 the last activity date for entities matching subscription results.&nbsp; No activity
210 among matching entities, which occurred after this point in time, is returned.
211 The endPoint is optional. If not provided, it signifies that the latest changes
212 available, which match the subscription criterions that are to be returned. </p>
213 
214 <p class="MsoBodyText">With respect to notifications, the startPoint of a given
215 notification SHOULD align with the endPoint of the previous notification.&nbsp; If
216 this is not the case, the subscriber SHOULD assume a notification was missed,
217 or lost.&nbsp; The subscriber can then take corrective action by using the
218 get_subscriptionResults API. Note that it is permissible for nodes to send the
219 same data more than once, depending on overlaps in these times.</p>
220 
221 <h3><a name="_Toc85908133"></a><a name="_Toc53709327"></a><a name="_Toc45096412"></a><a name="_Toc45095955"></a><a name="_Toc42047332"></a><a name="_Ref4234690">5.5.5 Chunking
222 of Returned Subscription Data</a><a name="_Ref535517771"></a></h3>
223 
224 <p class="MsoBodyText">If a subscriber specifies a maximum number of entries to
225 be returned with a subscription and the amount of data to be returned exceeds
226 this limit, or if the node determines based on its policy that there are too
227 many entries to be returned in a single group, then the node SHOULD provide a
228 chunkToken with results.&nbsp; The chunkToken is a string based token which is used
229 by the node to maintain the state of the subscription results for a particular
230 caller, when these results are chunked across multiple responses.&nbsp; The format
231 and content of the chunkToken is a matter of implementation choice by
232 individual nodes. The chunkToken returned with a particular subscription result
233 set SHOULD be used to retrieve subsequent results when subscription results are
234 requested in a synchronous manor.&nbsp; If no more results are pending, the value of
235 the chunkToken MUST be "0".</p>
236 
237 <p class="MsoBodyText">A chunkToken is intended as a short-term aid in obtaining
238 contiguous results across multiple API calls and is therefore likely to remain
239 valid for only a short time.&nbsp; Nodes MAY establish policies on how long a
240 chunkToken remains valid.</p>
241 
242 <h3><a name="_Toc85908134"></a><a name="_Toc53709328"></a><a name="_Toc45096413"></a><a name="_Toc45095956"></a><a name="_Toc42047333"></a><a name="_Ref3401043">5.5.6 Use
243 of keyBag in Subscription</a></h3>
244 
245 <p class="MsoBodyText">The subscription results returned by the subscription APIs
246 allow for the use of a structure called a keyBag.&nbsp; A keyBag contains a list of
247 entity keys, which correspond to any of the core data structures
248 (businessEntity, businessService, bindingTemplate or tModel).&nbsp; The keyBag has
249 two uses.&nbsp; </p>
250 
251 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
252 </span></span>Returning results when a "brief" format is selected,
253 which minimizes returned information.&nbsp; </p>
254 
255 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
256 </span></span>Indicating entities which have been deleted, or which no longer
257 match the subscription criteria provided with the subscription.&nbsp; This later
258 situation is referred to as a "virtual delete", in that the entity in
259 question may not actually have be deleted from the registry, but it no longer
260 matches the criterion which the subscriber defined in the subscription for
261 tracking registry changes.&nbsp; It should be noted that nodes MUST maintain
262 information pertaining to registry changes for both forms of deletion, to be
263 reported with subscription results for applicable subscriptions, although they MAY establish policies on how long such information is retained. Further details on the use of
264 this structure are discussed in the relevant API sections that follow.&nbsp; When
265 the keyBag is used for deleted entities, the deleted element is set to "true,"
266 and all entities listed in such a keyBag are assumed to represent deletions.<br>
267 <br>
268 </p>
269 
270 <p class="MsoBodyText"><span style="font-family:&quot;MS Shell Dlg&quot;;color:black;
271 letter-spacing:0pt">A UDDI node MUST never inform the subscriber of an entity
272 that temporarily matched the subscription criteria but was removed or modified
273 to no longer match the subscription criteria before the subscriber was informed
274 of the match.</span></p>
275 
276 <p class="MsoBodyText">A UDDI node MAY inform a subscriber about the real or
277 virtual deletion of an entity multiple times.</p>
278 
279 <p class="MsoBodyText">The syntax of a keyBag is shown here:</p>
280 
281 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image095.gif" border="0" height="271" width="371"></p>
282 
283 <h3><a name="_Toc85908135"></a><a name="_Toc53709329"></a><a name="_Toc45096414"></a><a name="_Toc45095957"></a><a name="_Toc42047334">5.5.7 Subscription </a>API functions</h3>
284 
285 <p class="MsoBodyText">The APIs in this section describe how to interact with a
286 UDDI node implementation to create and manage requests for the tracking of new
287 and changed registry content.&nbsp; These APIs are synchronous and are exposed via SOAP, although the notifications they may generate are not.&nbsp; </p>
288 
289 <p class="MsoBodyText">The subscription APIs are: </p>
290 
291 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
292 </span></span><b>delete_subscription: </b>&nbsp;Cancels one or more specified
293 subscriptions.</p>
294 
295 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
296 </span></span><b>get_subscriptionResults:</b>&nbsp; Synchronously returns registry
297 data pertaining to a particular subscription within a specified time period.</p>
298 
299 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
300 </span></span><b>get_subscriptions:</b>&nbsp; Returns a list of existing
301 subscriptions previously saved by the subscriber.</p>
302 
303 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
304 </span></span><b>save_subscription:</b>&nbsp; Establishes a new subscription or
305 changes an existing one.&nbsp; Also used to renew existing subscriptions.</p>
306 
307 <p class="MsoBodyText">The OPTIONAL client API is:</p>
308 
309 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
310 </span></span><b>notify_subscriptionListener</b>: A node invoked API which the client implements as a subscription listener service to accept notifications
311 containing the data that changed since notify_subscriptionListener was last
312 invoked for a particular subscription.</p>
313  */
314 @WebService(name = "UDDI_Subscription_PortType", targetNamespace = "urn:uddi-org:api_v3_portType")
315 @XmlSeeAlso({
316     org.uddi.custody_v3.ObjectFactory.class,
317     org.uddi.repl_v3.ObjectFactory.class,
318     org.uddi.subr_v3.ObjectFactory.class,
319     org.uddi.api_v3.ObjectFactory.class,
320     org.uddi.vscache_v3.ObjectFactory.class,
321     org.uddi.vs_v3.ObjectFactory.class,
322     org.uddi.sub_v3.ObjectFactory.class,
323     org.w3._2000._09.xmldsig_.ObjectFactory.class,
324     org.uddi.policy_v3.ObjectFactory.class,
325     org.uddi.policy_v3_instanceparms.ObjectFactory.class
326 })
327 public interface UDDISubscriptionPortType extends Remote {
328 
329     /**
330      *Cancels an existing subscription.
331      *
332      * @param body
333      * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
334 </span></span><b><i>authInfo</i></b>:&nbsp; This optional argument is an element
335 that contains an authentication token.&nbsp; Registries that wish to restrict who
336 can delete a subscription typically require authInfo for this call, though this
337 is a matter of node policy.</p>
338 
339 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
340 </span></span><b><i>subscriptionKey:</i></b>&nbsp; This required argument specifies,
341 using <i>anyURIs,</i> the subscription or subscriptions to be deleted.</p>
342 * <Br><b>If no errors occur then an empty message is returned.</b>
343      * @throws DispositionReportFaultMessage, RemoteException
344      * <p class="MsoBodyText">If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.&nbsp; In addition
345 to the errors common to all APIs, the following error information is relevant
346 here:</p>
347 
348 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
349 </span></span><b>E_userMismatch</b>: signifies that an attempt has been made to
350 use the subscription API to delete a subscription that is controlled by another
351 party.</p>
352 
353 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
354 </span></span><b>E_invalidKeyPassed</b>: signifies that the subscriptionKey is
355 invalid or that the subscription has expired.</p>
356      */
357     @WebMethod(operationName = "delete_subscription", action = "delete_subscription")
358     @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
359     public void deleteSubscription(
360             @WebParam(name = "delete_subscription", targetNamespace = "urn:uddi-org:sub_v3", partName = "body") DeleteSubscription body)
361             throws DispositionReportFaultMessage, RemoteException;
362 
363     /**
364      *This API allows a subscriber to request that the
365 information pertaining to an existing subscription be returned.&nbsp; This is
366 useful, for example, to obtain historical data when a subscription is first set
367 up or when a subscriber misses the notification normally provided by the
368 registry.&nbsp; The results are returned synchronously as the response to this
369 call.&nbsp; The get_subscriptionResults API can also be used as an alternative to
370 notifications for obtaining subscription data. If this is the preference, then
371 the subscriber SHOULD not provide a bindingKey when saving the associated
372 subscription. See Section <a href="#_Ref536850105 ">5.5.8</a> <i>save_subscription</i>.&nbsp;
373 This API is not affected by the value of the notificationInterval in the
374 subscription. 
375      * @param body
376      * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
377 </span></span><b><i>authInfo</i></b>:&nbsp; This optional argument is an element
378 that contains an authentication token.&nbsp; Registries that wish to restrict who
379 can retrieve subscription data typically require authInfo for this call, though
380 this is a matter of node policy.</p>
381 
382 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
383 </span></span><b><i>chunkToken</i></b>:&nbsp; This optional argument is used to
384 retrieve subsequent groups of data when the first call to this API indicates more data is available.&nbsp; This occurs when a chunkToken is returned whose value is
385 not "0" in the subscriptionResultsList structure described in the
386 next section. To retrieve the next chunk of data, the value returned should be
387 used as an argument to the next invocation of this API.</p>
388 
389 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
390 </span></span><b><i>coveragePeriod</i></b>: This structure defines the time
391 period over which the most recent changes in node data are compared with the
392 subscription criteria in order to produce the result set. It provides start and
393 end date/time information according to the format described in Section <a href="#_Ref3402225 ">5.5.4</a> <i>Subscription Coverage Period</i>.&nbsp; The "current"
394 state of registry entries pertaining to the subscription referenced by the
395 subscriptionKey provided are returned if they were last created, changed or
396 deleted during the specified time period.</p>
397 
398 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
399 </span></span><b><i>subscriptionKey:</i></b>&nbsp; This required argument of type
400 anyURI identifies the subscription for which non-recurring synchronous results
401 are being sought.</p>
402 * <img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image101.gif">
403      * @return returns org.uddi.sub_v3.SubscriptionResultsList
404      * <p class="MsoBodyText">A subscriptionResultsList is returned whose content is
405 determined by the coveragePeriod and the criteria in the subscription:</p>
406 
407 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image102.gif" border="0" height="484" width="523"></p>
408 
409 <p class="MsoBodyText"><b>Attributes</b></p>
410 
411 <table class="specTable" style="width:45.68%;margin-left:.5in;border-collapse:collapse;border:none" border="1" cellpadding="0" cellspacing="0" width="45%">
412  <tbody><tr>
413   <td style="width:60.52%;border:solid black 1.0pt;
414   background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="60%">
415   <p class="MsoNormal"><b>Name&nbsp;&nbsp;</b></p>
416   </td>
417   <td style="width:39.48%;border:solid black 1.0pt;
418   border-left:none;background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="39%">
419   <p class="MsoNormal"><b>Use&nbsp;&nbsp;</b></p>
420   </td>
421  </tr>
422  <tr style="height:18.15pt">
423   <td style="width:60.52%;border:solid black 1.0pt;
424   border-top:none;padding:0in 5.4pt 0in 5.4pt;height:18.15pt" valign="top" width="60%">
425   <p class="MsoNormal">someResultsUnavailable&nbsp;&nbsp;</p>
426   </td>
427   <td style="width:39.48%;border-top:none;border-left:
428   none;border-bottom:solid black 1.0pt;border-right:solid black 1.0pt;
429   padding:0in 5.4pt 0in 5.4pt;height:18.15pt" valign="top" width="39%">
430   <p class="MsoNormal">optional&nbsp;&nbsp;</p>
431   </td>
432  </tr>
433 </tbody></table>
434 
435 <p class="MsoBodyText">&nbsp;</p>
436 
437 <p class="MsoBodyText">Subscription results MAY be chunked.&nbsp; See Section <a href="#_Ref4234690 ">5.5.5</a> <i>Chunking of Returned Subscription Data, </i>for
438 more information on chunking of results.&nbsp; If results are chunked, then
439 subsequent "chunks" can be retrieved using the chunkToken returned as
440 an argument in a subsequent invocation of this API.</p>
441 
442 <p class="MsoBodyText">Note that the results returned in the
443 subscriptionResultsList represent a snapshot of the current state of relevant
444 entries in the registry.&nbsp; They are non-transactional in nature and prior states
445 cannot be returned.&nbsp; Deleted entities and virtual deletes of entities, which
446 have been changed in such a way that they no longer match the subscription
447 criterion saved with the subscription, are returned only in the form of a
448 keyBag structure, for which the deleted element is set to "true". A
449 UDDI node MAY inform a subscriber about the real or virtual deletion of an
450 entity multiple times.</p>
451 
452 <p class="MsoBodyText">The someResultsUnavailable attribute is set to "true"
453 whenever the node has found it necessary to flush subscription results
454 information pertaining to entity deletions (either actual or virtual) which
455 pertain to this subscription, which have not yet been reported through prior
456 calls to this API, or through use of the notify_subscriptionListener API described below.&nbsp; The period of time which a node retains information on deletions for a
457 given subscription is a matter of node policy.</p>
458 
459 <p class="MsoBodyText">The API used in the subscription filter determines the
460 sort order for returned entities. By default, they will be sorted according to
461 the behavior specified in the "returns" section of that API.</p>
462      * @throws DispositionReportFaultMessage, RemoteException
463      * <p class="MsoBodyText">If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.&nbsp; In addition
464 to the errors common to all APIs, the following error information is relevant
465 here:</p>
466 
467 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
468 </span></span><b>E_invalidKeyPassed</b>: signifies that the subscriptionKey is
469 invalid or that the subscription has expired.</p>
470 
471 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
472 </span></span><b>E_invalidValue</b>:&nbsp; signifies that the chunkToken value
473 supplied is either invalid or has expired.</p>
474 
475 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
476 </span></span><b>E_unsupported</b>: signifies that one of the argument values
477 was not supported by this implementation. The offending argument is clearly
478 indicated in the error text.</p>
479 
480 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
481 </span></span><b>E_userMismatch</b>: signifies that, in a violation of node
482 policy, an attempt has been made to use the subscription API to change a subscription that is controlled by another party.</p>
483 
484 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
485 </span></span><b>E_invalidTime</b>:&nbsp; signifies that one or both of the values
486 provided in the coveragePeriod range is invalid or does not define a range.&nbsp;
487 The error structure signifies the condition that occurred and the error text
488 clearly calls out the cause of the problem.</p>
489      */
490     @WebMethod(operationName = "get_subscriptionResults", action = "get_subscriptionResults")
491     @WebResult(name = "subscriptionResultsList", targetNamespace = "urn:uddi-org:sub_v3", partName = "body")
492     @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
493     public SubscriptionResultsList getSubscriptionResults(
494             @WebParam(name = "get_subscriptionResults", targetNamespace = "urn:uddi-org:sub_v3", partName = "body") GetSubscriptionResults body)
495             throws DispositionReportFaultMessage, RemoteException;
496 
497     /**
498      * Returns the complete list of existing subscriptions owned by the
499      * subscriber.
500      *
501      * @param authInfo authInfo: This optional argument is an element that
502      * contains an authentication token. Registries that wish to restrict who
503      * can obtain information on subscriptions typically require authInfo for
504      * this call, though this is a matter of node policy.
505      * @return returns java.util.List<org.uddi.sub_v3.Subscription> This API
506      * call returns information on all of the subscriptions owned by the
507      * subscriber, together with the expiration date for each. The subscriptions
508      * structure returned contains zero or more subscription structures, each
509      * pertaining to a subscription. Only subscriptions created by the invoking
510      * subscriber are returned. See Section 5.5.8.1, [save_subscription] Syntax,
511      * for details on these structures.
512      * @throws DispositionReportFaultMessage, RemoteException
513      */
514     @WebMethod(operationName = "get_subscriptions", action = "get_subscriptions")
515     @WebResult(name = "subscription", targetNamespace = "urn:uddi-org:sub_v3")
516     @RequestWrapper(localName = "get_subscriptions", targetNamespace = "urn:uddi-org:sub_v3", className = "org.uddi.sub_v3.GetSubscriptions")
517     @ResponseWrapper(localName = "subscriptions", targetNamespace = "urn:uddi-org:sub_v3", className = "org.uddi.sub_v3.Subscriptions")
518     public List<Subscription> getSubscriptions(
519             @WebParam(name = "authInfo", targetNamespace = "urn:uddi-org:api_v3") String authInfo)
520             throws DispositionReportFaultMessage, RemoteException;
521 
522     /**
523      *
524      * The save_subscription API registers a request to monitor specific registry content and to have the node periodically notify the subscriber when changes are available.  Notifications are not returned synchronously with results for this API.  Only data that matches the requested subscription criteria and which changes after the point in time that the subscription request is accepted is returned to the subscriber via a notification.
525 
526 This API returns a duration for which this particular subscription is valid.  Depending upon the policy of the Node, subscriptions need to be renewed before the expiration date in order to insure that they remain active.  Subscriptions can also be redefined or renewed using this API.  The subscriptionKey pertaining to the subscription to be renewed must be supplied in the save_subscription invocation in order to accomplish this. This allows both renewal and changes to the subscription.  Invoking save_subscription automatically resets the expiration period for the subscription in question to a value based upon the node’s policy. 
527 * 
528 * <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image096.gif" border="0" height="121" width="393"></p>
529 
530 <p class="MsoBodyText">The syntax of the subscription structure is:</p>
531 
532 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image097.gif" border="0" height="236" width="389"></p>
533 
534 <p class="MsoBodyText"><b>Attributes</b></p>
535 
536 <table class="specTable" style="width:33.34%;margin-left:.5in;border-collapse:collapse;border:none" border="1" cellpadding="0" cellspacing="0" width="33%">
537  <tbody><tr>
538   <td style="width:49.98%;border:solid black 1.0pt;
539   background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="49%">
540   <p class="MsoNormal"><b>Name&nbsp;&nbsp;</b></p>
541   </td>
542   <td style="width:50.02%;border:solid black 1.0pt;
543   border-left:none;background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="50%">
544   <p class="MsoNormal"><b>Use&nbsp;&nbsp;</b></p>
545   </td>
546  </tr>
547  <tr>
548   <td style="width:49.98%;border:solid black 1.0pt;
549   border-top:none;padding:0in 5.4pt 0in 5.4pt" valign="top" width="49%">
550   <p class="MsoNormal">brief&nbsp;&nbsp;</p>
551   </td>
552   <td style="width:50.02%;border-top:none;border-left:
553   none;border-bottom:solid black 1.0pt;border-right:solid black 1.0pt;
554   padding:0in 5.4pt 0in 5.4pt" valign="top" width="50%">
555   <p class="MsoNormal">optional&nbsp;&nbsp;</p>
556   </td>
557  </tr>
558 </tbody></table>
559 
560 <p class="MsoBodyText">&nbsp;</p>
561 
562 <span style="font-size:10.0pt;font-family:Arial;letter-spacing:-.25pt"><br style="page-break-before:always" clear="all">
563 </span>
564 
565 <p class="MsoBodyText">&nbsp;</p>
566 
567 <p class="MsoBodyText">The syntax of the subscriptionFilter structure is:</p>
568 
569 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image098.gif" border="0" height="368" width="441"></p>
570      * @param subscription <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
571 </span></span><b><i>bindingKey:</i></b>&nbsp; This optional argument of type anyURI
572 specifies the <i>bindingTemplate</i> which the node is to use to deliver
573 notifications to subscription listeners.&nbsp; It is only required when asynchronous
574 notifications are used.&nbsp; This <i>bindingTemplate</i> MUST define either a Web
575 service that implements notify_subscriptionListener (see below), or an email
576 address to receive the notifications. If a notify_subscriptionListener Web
577 service is identified, the node invokes it to deliver notifications.&nbsp; If an
578 email address is identified, the node delivers notifications via email to the
579 address supplied. When notifications are delivered via email, the body of the
580 email contains the body of the SOAP message, which would have been sent to the
581 notify_subscriptionListener service if that option had been chosen.<span class="MsoCommentReference"><span style="display:none">.</span></span> The
582 publisher making the subscription request MUST own the bindingTemplate.&nbsp; If
583 this argument is not supplied, no notifications are sent, although subscribers
584 may still use the get_subscriptionResults API to obtain subscription results.&nbsp;
585 See Section <a href="#_Ref536844845 ">5.5.11</a> <i>get_subscriptionResults </i>for
586 details.&nbsp; If email delivery to the specified address fails, nodes MAY attempt re-delivery, but are not obligated to do so.&nbsp; Depending upon node policy, excessive
587 delivery failures MAY result in cancellation of the corresponding subscription.</p>
588 
589 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
590 </span></span><b><i>brief</i></b>:&nbsp; This optional argument controls the level
591 of detail returned to a subscription listener.&nbsp; The default is "false"
592 when omitted. When set to "true," it indicates that the subscription
593 results are to be returned to the subscriber in the form of a keyBag, listing
594 all of the entities that matched the subscriptionFilter.&nbsp; Refer to Section <a href="#_Ref3401043 ">5.5.6</a> <i>Use of keyBag in Subscription,</i> for
595 additional information.&nbsp; This option has no effect on the assertionStatusReport
596 structure, which is returned as part of a notification when the
597 subscriptionFilter specifies the get_assertionStatusReport filter criteria.&nbsp;
598 See the explanation of subscriptionFilter below.</p>
599 
600 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
601 </span></span><b><i>expiresAfter</i></b>:&nbsp; This optional argument allows
602 subscribers to specify the period of time for which they would like the
603 subscription to exist.&nbsp; It is of the XML Schema type xsd:dateTime.&nbsp; Specifying
604 a value for this argument is no guarantee that the node will accept it without
605 change.&nbsp; Information on the format of expiresAfter can be found in Section <a href="#_Ref535515666 ">5.5.1.1</a> <i>Specifying Durations</i>.</p>
606 
607 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
608 </span></span><b><i>maxEntities</i></b>:&nbsp; This optional integer specifies the
609 maximum number of entities in a notification returned to a subscription
610 listener. If not specified, the number of entities sent is not limited, unless
611 by node policy.</p>
612 
613 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
614 </span></span><b><i>subscriptionFilter</i></b>:&nbsp; This argument specifies the
615 filtering criteria which limits the scope of a subscription to a subset of
616 registry records. It is required except when renewing an existing subscription.
617 The get_xx and find_xx APIs are all valid choices for use as a
618 subscriptionFilter.&nbsp; Only one of these can be chosen for each subscription.&nbsp;
619 Notifications, based on the subscriptionFilter, are sent to the subscriber if
620 and only if there are changes at the node, which match this criterion during a
621 notification period.&nbsp; A subscriptionFilter MUST contain exactly one of the
622 allowed inquiry elements. The authInfo argument of the specified get_xx or
623 find_xx API call is not required here and is ignored if specified.&nbsp; All of the
624 other arguments supported with each of these inquiry APIs are valid for use
625 here.</p>
626 
627 <p class="MsoBodyText" style="margin-left:1.0in">Specifying find_relatedBusinesses
628 is useful for tracking when reciprocal relationships are formed or dissolved.&nbsp;
629 Specifying get_assertionStatusReport can be used in tracking when reciprocal
630 relationships (which pertain to a business owned by the subscriber) are formed,
631 dissolved, or requested by the owners of some other business.</p>
632 
633 <p class="MsoBodyText" style="margin-left:1.0in">For a get_assertionStatusReport
634 based subscription, there is a specific status value, <b>status:both_incomplete</b>,
635 defined in the XML schema. When appearing in an assertionStatusItem of a
636 subscriptionResultsList, status:both_incomplete indicates that the publisher
637 assertion embedded in the assertionStatusItem has been deleted from both ends. </p>
638 
639 <p class="MsoBodyText" style="margin-left:1.0in">Note that the above handling of
640 deleted publisher assertions is different from the case when a business entity,
641 business service, binding template, or tModel is removed. In the latter case,
642 the key to the entity in question is simply put inside a keyBag. A publisher
643 assertion, on the other hand, has no key and therefore the keyBag idea is not
644 applicable.</p>
645 
646 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
647 </span></span><b><i>subscriptionKey</i></b>:&nbsp; This optional argument of type <i>anyURI</i>
648 identifies the subscription.&nbsp; To renew or change an existing subscription, a
649 valid subscriptionKey MUST be provided. When establishing a new subscription,
650 the subscriptionKey MAY also be either omitted or specified as an empty string in
651 which case the node MUST assign a unique key. If subscriptionKey is specified
652 for a new subscription, the key MUST conform to the registry’s policy on
653 publisher-assigned keys.</p>
654 
655 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
656 </span></span><b><i>notificationInterval</i></b>:&nbsp; This optional argument is
657 only required when asynchronous notifications are used.&nbsp; It is of type
658 xsd:duration and specifies how often change notifications are to be provided to
659 a subscriber.&nbsp; If the notificationInterval specified is not acceptable due to
660 node policy, then the node adjusts the value to match the next longer time
661 period that is supported.&nbsp; The adjusted value is provided with the returns from
662 this API.&nbsp; Also see Section <a href="#_Ref535515666 ">5.5.1.1</a> <i>Specifying
663 Durations</i>.</p>
664      * @param authInfo       authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can save a subscription typically require authInfo for this call, though this is a matter of node policy.
665      * <br><br>
666      * return <p class="MsoBodyText">Upon successful completion this API returns a <i>subscriptions</i>
667 structure.&nbsp; Included in the subscription structure(s) it MUST contain is a <i>subscriptionKey</i>
668 (of type anyURI) that is used by the subscriber to manage the subscription.&nbsp;&nbsp;
669 This key is required in order to delete (unsubscribe), modify or renew the
670 subscription.&nbsp;&nbsp; If a subscriber has multiple subscriptions, the subscriptionKey
671 can be used to distinguish between different subscriptions.&nbsp; The <i>subscriptionKey</i>
672 is also part of the data contained in the notifications returned to subscription
673 listeners.&nbsp; </p>
674 
675 <p class="MsoBodyText">&nbsp;</p>
676 
677 <p class="MsoBodyText">The subscription structure(s) returned from this API, MUST each contain an <i>expiresAfter</i> value, which has been assigned by the node.&nbsp; Nodes
678 SHOULD attempt to honor the value(s) provided with the save_subscription
679 request, but MAY modify them based on node policy.&nbsp;&nbsp;&nbsp; Depending upon the node’s
680 policy, the node MAY delete a subscription after it has expired.</p>
681 
682 <p class="MsoBodyText">The value of the <i>notificationInterval</i> included in
683 the subscription structure(s) returned MAY be adjusted by the node to the value
684 closest to that requested which is supported by its policies. Depending upon
685 the Registry’s workload a node MAY skip a notification cycle.&nbsp; If a cycle is
686 skipped, the next notification sent SHOULD include information based on
687 registry activity, which has occurred since the last notification was issued.</p>
688      * @throws DispositionReportFaultMessage, RemoteException
689      * <p class="MsoBodyText">If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.&nbsp; In addition
690 to the errors common to all APIs, the following error information is relevant
691 here:</p>
692 
693 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
694 </span></span><b>E_invalidKeyPassed</b>: signifies that an entity key value
695 passed did not match with any known key values.&nbsp; The error structure signifies
696 that the condition occurred and the error text clearly calls out the offending
697 key.</p>
698 
699 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
700 </span></span><b>E_unsupported</b>: signifies that one of the argument values
701 was not supported by this implementation. The offending argument is clearly
702 indicated in the error text.</p>
703 
704 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
705 </span></span><b>E_resultSetTooLarge</b>: signifies that the node refuses to
706 accept the subscription because it deems that result sets associated with the
707 subscription are too large.&nbsp; The subscription criteria that triggered this
708 error should be refined and re-issued. </p>
709 
710 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
711 </span></span><b>E_accountLimitExceeded</b>: signifies that the request
712 exceeded the quantity limits for subscription requests, based on node policy.</p>
713 
714 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
715 </span></span><b>E_userMismatch</b>: signifies that an attempt has been made to
716 use the subscription API to change a subscription that is controlled by another
717 party. Or that the bindingTemplate specified does not belong to the publisher.</p>
718 
719 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
720 </span></span><b>E_requestDenied</b>: signifies that the subscription cannot be
721 renewed. The request has been denied due to either node or registry policy.</p>
722      */
723     @WebMethod(operationName = "save_subscription", action = "save_subscription")
724     @RequestWrapper(localName = "save_subscription", targetNamespace = "urn:uddi-org:sub_v3", className = "org.uddi.sub_v3.SaveSubscription")
725     @ResponseWrapper(localName = "subscriptions", targetNamespace = "urn:uddi-org:sub_v3", className = "org.uddi.sub_v3.Subscriptions")
726     public void saveSubscription(
727             @WebParam(name = "authInfo", targetNamespace = "urn:uddi-org:api_v3") String authInfo,
728             @WebParam(name = "subscription", targetNamespace = "urn:uddi-org:sub_v3", mode = WebParam.Mode.INOUT) Holder<List<Subscription>> subscription)
729             throws DispositionReportFaultMessage, RemoteException;
730 }