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 18 19 package org.uddi.sub_v3; 20 21 import java.io.Serializable; 22 23 import javax.xml.bind.annotation.XmlAccessType; 24 import javax.xml.bind.annotation.XmlAccessorType; 25 import javax.xml.bind.annotation.XmlAttribute; 26 import javax.xml.bind.annotation.XmlElement; 27 import javax.xml.bind.annotation.XmlRootElement; 28 import javax.xml.bind.annotation.XmlTransient; 29 import javax.xml.bind.annotation.XmlType; 30 import javax.xml.datatype.Duration; 31 import javax.xml.datatype.XMLGregorianCalendar; 32 33 34 /** 35 * <h1>UDDI Subscription</h1> 36 * 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. 37 38 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. 39 * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 40 </span></span><b><i>authInfo</i></b>: This optional argument is an element 41 that contains an authentication token. Registries that wish to restrict who 42 can save a subscription typically require authInfo for this call, though this 43 is a matter of node policy.</p> 44 45 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 46 </span></span><b><i>bindingKey:</i></b> This optional argument of type anyURI 47 specifies the <i>bindingTemplate</i> which the node is to use to deliver 48 notifications to subscription listeners. It is only required when asynchronous 49 notifications are used. This <i>bindingTemplate</i> MUST define either a Web 50 service that implements notify_subscriptionListener (see below), or an email 51 address to receive the notifications. If a notify_subscriptionListener Web 52 service is identified, the node invokes it to deliver notifications. If an 53 email address is identified, the node delivers notifications via email to the 54 address supplied. When notifications are delivered via email, the body of the 55 email contains the body of the SOAP message, which would have been sent to the 56 notify_subscriptionListener service if that option had been chosen.<span class="MsoCommentReference"><span style="display:none">.</span></span> The 57 publisher making the subscription request MUST own the bindingTemplate. If 58 this argument is not supplied, no notifications are sent, although subscribers 59 may still use the get_subscriptionResults API to obtain subscription results. 60 See Section <a href="#_Ref536844845 ">5.5.11</a> <i>get_subscriptionResults </i>for 61 details. If email delivery to the specified address fails, nodes MAY attempt re-delivery, but are not obligated to do so. Depending upon node policy, excessive 62 delivery failures MAY result in cancellation of the corresponding subscription.</p> 63 64 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 65 </span></span><b><i>brief</i></b>: This optional argument controls the level 66 of detail returned to a subscription listener. The default is "false" 67 when omitted. When set to "true," it indicates that the subscription 68 results are to be returned to the subscriber in the form of a keyBag, listing 69 all of the entities that matched the subscriptionFilter. Refer to Section <a href="#_Ref3401043 ">5.5.6</a> <i>Use of keyBag in Subscription,</i> for 70 additional information. This option has no effect on the assertionStatusReport 71 structure, which is returned as part of a notification when the 72 subscriptionFilter specifies the get_assertionStatusReport filter criteria. 73 See the explanation of subscriptionFilter below.</p> 74 75 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 76 </span></span><b><i>expiresAfter</i></b>: This optional argument allows 77 subscribers to specify the period of time for which they would like the 78 subscription to exist. It is of the XML Schema type xsd:dateTime. Specifying 79 a value for this argument is no guarantee that the node will accept it without 80 change. Information on the format of expiresAfter can be found in Section <a href="#_Ref535515666 ">5.5.1.1</a> <i>Specifying Durations</i>.</p> 81 82 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 83 </span></span><b><i>maxEntities</i></b>: This optional integer specifies the 84 maximum number of entities in a notification returned to a subscription 85 listener. If not specified, the number of entities sent is not limited, unless 86 by node policy.</p> 87 88 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 89 </span></span><b><i>subscriptionFilter</i></b>: This argument specifies the 90 filtering criteria which limits the scope of a subscription to a subset of 91 registry records. It is required except when renewing an existing subscription. 92 The get_xx and find_xx APIs are all valid choices for use as a 93 subscriptionFilter. Only one of these can be chosen for each subscription. 94 Notifications, based on the subscriptionFilter, are sent to the subscriber if 95 and only if there are changes at the node, which match this criterion during a 96 notification period. A subscriptionFilter MUST contain exactly one of the 97 allowed inquiry elements. The authInfo argument of the specified get_xx or 98 find_xx API call is not required here and is ignored if specified. All of the 99 other arguments supported with each of these inquiry APIs are valid for use 100 here.</p> 101 102 <p class="MsoBodyText" style="margin-left:1.0in">Specifying find_relatedBusinesses 103 is useful for tracking when reciprocal relationships are formed or dissolved. 104 Specifying get_assertionStatusReport can be used in tracking when reciprocal 105 relationships (which pertain to a business owned by the subscriber) are formed, 106 dissolved, or requested by the owners of some other business.</p> 107 108 <p class="MsoBodyText" style="margin-left:1.0in">For a get_assertionStatusReport 109 based subscription, there is a specific status value, <b>status:both_incomplete</b>, 110 defined in the XML schema. When appearing in an assertionStatusItem of a 111 subscriptionResultsList, status:both_incomplete indicates that the publisher 112 assertion embedded in the assertionStatusItem has been deleted from both ends. </p> 113 114 <p class="MsoBodyText" style="margin-left:1.0in">Note that the above handling of 115 deleted publisher assertions is different from the case when a business entity, 116 business service, binding template, or tModel is removed. In the latter case, 117 the key to the entity in question is simply put inside a keyBag. A publisher 118 assertion, on the other hand, has no key and therefore the keyBag idea is not 119 applicable.</p> 120 121 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 122 </span></span><b><i>subscriptionKey</i></b>: This optional argument of type <i>anyURI</i> 123 identifies the subscription. To renew or change an existing subscription, a 124 valid subscriptionKey MUST be provided. When establishing a new subscription, 125 the subscriptionKey MAY also be either omitted or specified as an empty string in 126 which case the node MUST assign a unique key. If subscriptionKey is specified 127 for a new subscription, the key MUST conform to the registry’s policy on 128 publisher-assigned keys.</p> 129 130 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 131 </span></span><b><i>notificationInterval</i></b>: This optional argument is 132 only required when asynchronous notifications are used. It is of type 133 xsd:duration and specifies how often change notifications are to be provided to 134 a subscriber. If the notificationInterval specified is not acceptable due to 135 node policy, then the node adjusts the value to match the next longer time 136 period that is supported. The adjusted value is provided with the returns from 137 this API. Also see Section <a href="#_Ref535515666 ">5.5.1.1</a> <i>Specifying 138 Durations</i>.</p> 139 * <p>Java class for subscription complex type. 140 * 141 * <p>The following schema fragment specifies the expected content contained within this class. 142 * 143 * <pre> 144 * <complexType name="subscription"> 145 * <complexContent> 146 * <restriction base="{http://www.w3.org/2001/XMLSchema}anyType"> 147 * <sequence> 148 * <element ref="{urn:uddi-org:sub_v3}subscriptionKey" minOccurs="0"/> 149 * <element ref="{urn:uddi-org:sub_v3}subscriptionFilter" minOccurs="0"/> 150 * <element ref="{urn:uddi-org:api_v3}bindingKey" minOccurs="0"/> 151 * <element ref="{urn:uddi-org:sub_v3}notificationInterval" minOccurs="0"/> 152 * <element ref="{urn:uddi-org:sub_v3}maxEntities" minOccurs="0"/> 153 * <element ref="{urn:uddi-org:sub_v3}expiresAfter" minOccurs="0"/> 154 * </sequence> 155 * <attribute name="brief" type="{urn:uddi-org:sub_v3}brief" /> 156 * </restriction> 157 * </complexContent> 158 * </complexType> 159 * </pre> 160 * 161 * 162 * 163 */ 164 @XmlAccessorType(XmlAccessType.FIELD) 165 @XmlType(name = "subscription", propOrder = { 166 "subscriptionKey", 167 "subscriptionFilter", 168 "bindingKey", 169 "notificationInterval", 170 "maxEntities", 171 "expiresAfter" 172 }) 173 @XmlRootElement 174 public class Subscription implements Serializable{ 175 @XmlTransient 176 private static final long serialVersionUID = -1016771256986173140L; 177 protected String subscriptionKey; 178 protected SubscriptionFilter subscriptionFilter; 179 @XmlElement(namespace = "urn:uddi-org:api_v3") 180 protected String bindingKey; 181 protected Duration notificationInterval; 182 protected Integer maxEntities; 183 protected XMLGregorianCalendar expiresAfter; 184 @XmlAttribute 185 protected Boolean brief; 186 187 /** 188 * Gets the value of the subscriptionKey property. 189 * 190 * @return 191 * possible object is 192 * {@link String } 193 * 194 */ 195 public String getSubscriptionKey() { 196 return subscriptionKey; 197 } 198 199 /** 200 * Sets the value of the subscriptionKey property. 201 * 202 * @param value 203 * allowed object is 204 * {@link String } 205 * 206 */ 207 public void setSubscriptionKey(String value) { 208 this.subscriptionKey = value; 209 } 210 211 /** 212 * Gets the value of the subscriptionFilter property. 213 * 214 * @return 215 * possible object is 216 * {@link SubscriptionFilter } 217 * 218 */ 219 public SubscriptionFilter getSubscriptionFilter() { 220 return subscriptionFilter; 221 } 222 223 /** 224 * Sets the value of the subscriptionFilter property. 225 * 226 * @param value 227 * allowed object is 228 * {@link SubscriptionFilter } 229 * 230 */ 231 public void setSubscriptionFilter(SubscriptionFilter value) { 232 this.subscriptionFilter = value; 233 } 234 235 /** 236 * Gets the value of the bindingKey property. 237 * 238 * @return 239 * possible object is 240 * {@link String } 241 * 242 */ 243 public String getBindingKey() { 244 return bindingKey; 245 } 246 247 /** 248 * Sets the value of the bindingKey property. 249 * 250 * @param value 251 * allowed object is 252 * {@link String } 253 * 254 */ 255 public void setBindingKey(String value) { 256 this.bindingKey = value; 257 } 258 259 /** 260 * Gets the value of the notificationInterval property. 261 * 262 * @return 263 * possible object is 264 * {@link Duration } 265 * 266 */ 267 public Duration getNotificationInterval() { 268 return notificationInterval; 269 } 270 271 /** 272 * Sets the value of the notificationInterval property. 273 * 274 * @param value 275 * allowed object is 276 * {@link Duration } 277 * 278 */ 279 public void setNotificationInterval(Duration value) { 280 this.notificationInterval = value; 281 } 282 283 /** 284 * Gets the value of the maxEntities property. 285 * 286 * @return 287 * possible object is 288 * {@link Integer } 289 * 290 */ 291 public Integer getMaxEntities() { 292 return maxEntities; 293 } 294 295 /** 296 * Sets the value of the maxEntities property. 297 * 298 * @param value 299 * allowed object is 300 * {@link Integer } 301 * 302 */ 303 public void setMaxEntities(Integer value) { 304 this.maxEntities = value; 305 } 306 307 /** 308 * Gets the value of the expiresAfter property. 309 * 310 * @return 311 * possible object is 312 * {@link XMLGregorianCalendar } 313 * 314 */ 315 public XMLGregorianCalendar getExpiresAfter() { 316 return expiresAfter; 317 } 318 319 /** 320 * Sets the value of the expiresAfter property. 321 * 322 * @param value 323 * allowed object is 324 * {@link XMLGregorianCalendar } 325 * 326 */ 327 public void setExpiresAfter(XMLGregorianCalendar value) { 328 this.expiresAfter = value; 329 } 330 331 /** 332 * Gets the value of the brief property. 333 * 334 * @return 335 * possible object is 336 * {@link Boolean } 337 * 338 */ 339 public Boolean isBrief() { 340 return brief; 341 } 342 343 /** 344 * Sets the value of the brief property. 345 * 346 * @param value 347 * allowed object is 348 * {@link Boolean } 349 * 350 */ 351 public void setBrief(Boolean value) { 352 this.brief = value; 353 } 354 355 }