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  
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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
40  </span></span><b><i>authInfo</i></b>:&nbsp; This optional argument is an element
41  that contains an authentication token.&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
46  </span></span><b><i>bindingKey:</i></b>&nbsp; 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.&nbsp; It is only required when asynchronous
49  notifications are used.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp;
60  See Section <a href="#_Ref536844845 ">5.5.11</a> <i>get_subscriptionResults </i>for
61  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
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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
65  </span></span><b><i>brief</i></b>:&nbsp; This optional argument controls the level
66  of detail returned to a subscription listener.&nbsp; 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.&nbsp; Refer to Section <a href="#_Ref3401043 ">5.5.6</a> <i>Use of keyBag in Subscription,</i> for
70  additional information.&nbsp; 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.&nbsp;
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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
76  </span></span><b><i>expiresAfter</i></b>:&nbsp; This optional argument allows
77  subscribers to specify the period of time for which they would like the
78  subscription to exist.&nbsp; It is of the XML Schema type xsd:dateTime.&nbsp; Specifying
79  a value for this argument is no guarantee that the node will accept it without
80  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>
81  
82  <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;
83  </span></span><b><i>maxEntities</i></b>:&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
89  </span></span><b><i>subscriptionFilter</i></b>:&nbsp; 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.&nbsp; Only one of these can be chosen for each subscription.&nbsp;
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.&nbsp; 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.&nbsp; 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.&nbsp;
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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
122 </span></span><b><i>subscriptionKey</i></b>:&nbsp; This optional argument of type <i>anyURI</i>
123 identifies the subscription.&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
131 </span></span><b><i>notificationInterval</i></b>:&nbsp; This optional argument is
132 only required when asynchronous notifications are used.&nbsp; It is of type
133 xsd:duration and specifies how often change notifications are to be provided to
134 a subscriber.&nbsp; 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.&nbsp; The adjusted value is provided with the returns from
137 this API.&nbsp; 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  * &lt;complexType name="subscription">
145  *   &lt;complexContent>
146  *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
147  *       &lt;sequence>
148  *         &lt;element ref="{urn:uddi-org:sub_v3}subscriptionKey" minOccurs="0"/>
149  *         &lt;element ref="{urn:uddi-org:sub_v3}subscriptionFilter" minOccurs="0"/>
150  *         &lt;element ref="{urn:uddi-org:api_v3}bindingKey" minOccurs="0"/>
151  *         &lt;element ref="{urn:uddi-org:sub_v3}notificationInterval" minOccurs="0"/>
152  *         &lt;element ref="{urn:uddi-org:sub_v3}maxEntities" minOccurs="0"/>
153  *         &lt;element ref="{urn:uddi-org:sub_v3}expiresAfter" minOccurs="0"/>
154  *       &lt;/sequence>
155  *       &lt;attribute name="brief" type="{urn:uddi-org:sub_v3}brief" />
156  *     &lt;/restriction>
157  *   &lt;/complexContent>
158  * &lt;/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 }