You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juddi.apache.org by al...@apache.org on 2013/05/04 01:23:28 UTC
svn commit: r1479003 [5/5] - in /juddi/branches/juddi-3.2.x:
juddi-client/src/main/java/org/apache/juddi/v3/client/
uddi-ws/src/main/java/org/uddi/v3_service/
Modified: juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDISubscriptionPortType.java
URL: http://svn.apache.org/viewvc/juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDISubscriptionPortType.java?rev=1479003&r1=1479002&r2=1479003&view=diff
==============================================================================
--- juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDISubscriptionPortType.java (original)
+++ juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDISubscriptionPortType.java Fri May 3 23:23:27 2013
@@ -39,29 +39,277 @@ import org.uddi.sub_v3.SubscriptionResul
* This class was generated by the JAX-WS RI. JAX-WS RI 2.1.5-b03- Generated
* source version: 2.1
*
- * The APIs in this section describe how to interact with a UDDI node
- * implementation to create and manage requests for the tracking of new and
- * changed registry content. These APIs are synchronous and are exposed via
- * SOAP, although the notifications they may generate are not. * The
- * subscription APIs are:
- *
- * · delete_subscription: Cancels one or more specified subscriptions.
- *
- * · get_subscriptionResults: Synchronously returns registry data pertaining to
- * a particular subscription within a specified time period.
- *
- * · get_subscriptions: Returns a list of existing subscriptions previously
- * saved by the subscriber.
- *
- * · save_subscription: Establishes a new subscription or changes an existing
- * one. Also used to renew existing subscriptions.
- *
- * The OPTIONAL client API is:
- *
- * · notify_subscriptionListener: A node invoked API which the client implements
- * as a subscription listener service to accept notifications containing the
- * data that changed since notify_subscriptionListener was last invoked for a
- * particular subscription.
+ * 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>
+ *
+ * <p class="MsoBodyText">The subscription API set satisfies a variety of
+requirements. The flexibility of the subscription API allows monitoring of activity
+in a registry by registering to track new, changed and deleted entries for each
+of these entities:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>businessEntity</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>businessService</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>bindingTemplate</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>tModel</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>related businessEntity</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>publisherAssertion (limited to those publisherAssertions for
+which the subscriber owns at least one of the businesses referenced)</p>
+
+<p class="MsoBodyText">With the exception of single publisher registries
+subscription typically is limited to authorized clients as a matter of node
+policy. Therefore, subscribers MUST typically authenticate with the node
+before saving subscription requests. Individual nodes, including those in the
+UDDI Business Registry, MAY establish policies concerning the use of the
+subscription APIs they choose to offer. Such policies might include restricting
+the use of subscription, defining which APIs are supported, establishing
+whether subscriptions require authentication, defining special rules affecting
+different classes of subscriptions, or even imposing fees for the use of these
+services. The use of the authInfo argument is OPTIONAL throughout the
+subscription APIs, although registries which support multiple users or which
+require authentication for publishing operations typically require it. </p>
+
+<p class="MsoBodyText">Subscription allows subscribers to "monitor" a
+particular subset of data within a registry. Two patterns are defined. Nodes MAY support either or both:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>Asynchronous notification â subscribers choose to be
+asynchronously notified by the node when registry data of interest changes via
+calls to the notify_subscriptionListener API, which they implement as a "subscription
+listener" service.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>Synchronous change tracking â subscribers issue a synchronous
+request using the get_subscriptionResults API to obtain information on activity
+in the registry which matches their subscription preferences.</p>
+
+<p class="MsoBodyText">A subscription request establishes criteria for the
+subscription and specifies how and if the subscriber is to be notified of
+changes matching the specified criteria. Any of the existing standard inquiry
+APIs (find_xx and get_xx) may be used within a subscription request to define
+the criteria, although nodes are free to restrict which inquiry APIs are
+supported in subscription as a matter of policy. The duration, or life of a
+subscription is also a matter of node policy, but subscribers can renew existing
+subscriptions periodically instead of having to create new ones. Subscribers
+may also create multiple subscriptions. Each subscription request is treated
+independently. The level of detail provided for the data returned is
+controlled by the subscription request.</p>
+
+<p class="MsoBodyText">When asynchronous notifications are requested,
+subscriptions provide information on new, changed or deleted entities within a
+registry that occur <i>after</i> the point in time that the subscription is
+registered. A node notifies subscribers based upon its identification of data
+matching the requested subscription criteria. Subscribers can choose to have
+these notifications provided via email or an HTTP/SOAP-based Web service, which
+the subscriber MAY implement. Such services are called "subscription
+listeners." Notifications are made periodically rather than in response
+to the continuous stream of changes that normally occur within the registry.
+This means that subscription results provided via notifications pertain only to
+the <i>current</i> state of the entities at the time they are reported â
+intermediate state changes are not provided. While subscribers can specify a
+frequency for these notifications, nodes MAY choose to restrict this as a
+matter of policy.</p>
+
+<p class="MsoBodyText">When synchronous requests are made for subscription
+results, the <i>current</i> state of the registry data, which matches the
+subscription criteria, is returned for entries that were last created, changed
+or deleted within a specified date range. Prior states of the registry data
+are not available and are not returned.</p>
+
+<p class="MsoBodyText">Subscriptions are owned by the subscriber who creates
+them. A subscriptionKey, which distinguishes each individual subscription, is
+not visible to anyone except the subscriber. While node policy MAY permit others besides the subscriptionâs owner to receive or retrieve subscription results,
+such interested parties require knowledge of the relevant subscriptionKey from
+the subscription owner in order to do so.</p>
+
+<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>
+
+<p class="MsoBodyText">As stated above, the subscription API allows monitoring of
+new, changed and deleted entities. This section provides the definition of
+changed entities. The following are the criteria for considering an entity to
+have been "changed":</p>
+
+<p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
+margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>For businessEntity, businessService, bindingTemplate, and tModel:
+<br>
+The entity is considered to be changed if the modifiedIncludingChildren element
+of the operationalInfo element of the entity has been changed.</p>
+
+<p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
+margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>For publisherAssertion:<br>
+A publisherAssertion is considered to be changed if the publisher has updated
+the publisherAssertion via the set_publisherAssertions, or
+add_publisherAssertions APIs.</p>
+
+<p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
+margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>For related businessEntity: <br>
+A related businessEntity (related to the business specified in the businessKey
+argument of find_relatedBusinesses API) is considered to be changed if either:</p>
+
+<p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
+margin-left:1.5in;text-indent:-.25in">1.<span style="font:7.0pt "Times New Roman"">
+</span>the related businessEntity is changed, or</p>
+
+<p class="MsoNormal" style="margin-top:4.0pt;margin-right:0in;margin-bottom:4.0pt;
+margin-left:1.5in;text-indent:-.25in">2.<span style="font:7.0pt "Times New Roman"">
+</span>at least one of the two reciprocal publisherAssertions that represents
+the relationship is changed.</p>
+
+<h3><a name="_Toc85908130"></a><a name="_Toc53709324"></a><a name="_Toc45096409"></a><a name="_Toc45095952">5.5.2 Specifying Durations</a></h3>
+
+<p class="MsoBodyText">Time durations used in the subscription APIs are of type
+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>. Any form
+supported by this data type is permitted. For example, the lexical
+representation extended format can be used, which is of the form PnYnMnDTnHnMnS,
+where nY represents the number of years, nM the number of months, nD the number
+of days, 'T' is the date/time separator, nH the number of hours, nM the number
+of minutes and nS the number of seconds. The "P" identifies the field
+as duration. The number of seconds can include decimal digits to arbitrary
+precision.</p>
+
+<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>
+
+<p class="MsoBodyText">Points in time used in the subscription APIs are all of
+the XML Schema type, xsd:dateTime. Two points in time are used to specify a
+period of time.</p>
+
+<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
+Coverage Period</a></h3>
+
+<p class="MsoBodyText">The APIs, which support each of the patterns previously
+described for obtaining subscription results, accept a coveragePeriod argument,
+which is composed of two points in time. Each of these corresponds to the last
+point in time which any given entity in the registry was modified (i.e.,
+created, deleted or changed). The syntax of this element is:</p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image094.gif" border="0" height="104" width="357"></p>
+
+<p class="MsoBodyText">Where<b><i>:</i></b></p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>startPoint</b>: Signifies the point in time after which
+subscription results are to be collected and/or returned. The startPoint is
+optional. If it is not specified, this indicates that all available results are
+to be returned from the beginning of the registry.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>endPoint</b>: Signifies the point in time corresponding to
+the last activity date for entities matching subscription results. No activity
+among matching entities, which occurred after this point in time, is returned.
+The endPoint is optional. If not provided, it signifies that the latest changes
+available, which match the subscription criterions that are to be returned. </p>
+
+<p class="MsoBodyText">With respect to notifications, the startPoint of a given
+notification SHOULD align with the endPoint of the previous notification. If
+this is not the case, the subscriber SHOULD assume a notification was missed,
+or lost. The subscriber can then take corrective action by using the
+get_subscriptionResults API. Note that it is permissible for nodes to send the
+same data more than once, depending on overlaps in these times.</p>
+
+<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
+of Returned Subscription Data</a><a name="_Ref535517771"></a></h3>
+
+<p class="MsoBodyText">If a subscriber specifies a maximum number of entries to
+be returned with a subscription and the amount of data to be returned exceeds
+this limit, or if the node determines based on its policy that there are too
+many entries to be returned in a single group, then the node SHOULD provide a
+chunkToken with results. The chunkToken is a string based token which is used
+by the node to maintain the state of the subscription results for a particular
+caller, when these results are chunked across multiple responses. The format
+and content of the chunkToken is a matter of implementation choice by
+individual nodes. The chunkToken returned with a particular subscription result
+set SHOULD be used to retrieve subsequent results when subscription results are
+requested in a synchronous manor. If no more results are pending, the value of
+the chunkToken MUST be "0".</p>
+
+<p class="MsoBodyText">A chunkToken is intended as a short-term aid in obtaining
+contiguous results across multiple API calls and is therefore likely to remain
+valid for only a short time. Nodes MAY establish policies on how long a
+chunkToken remains valid.</p>
+
+<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
+of keyBag in Subscription</a></h3>
+
+<p class="MsoBodyText">The subscription results returned by the subscription APIs
+allow for the use of a structure called a keyBag. A keyBag contains a list of
+entity keys, which correspond to any of the core data structures
+(businessEntity, businessService, bindingTemplate or tModel). The keyBag has
+two uses. </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>Returning results when a "brief" format is selected,
+which minimizes returned information. </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span>Indicating entities which have been deleted, or which no longer
+match the subscription criteria provided with the subscription. This later
+situation is referred to as a "virtual delete", in that the entity in
+question may not actually have be deleted from the registry, but it no longer
+matches the criterion which the subscriber defined in the subscription for
+tracking registry changes. It should be noted that nodes MUST maintain
+information pertaining to registry changes for both forms of deletion, to be
+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
+this structure are discussed in the relevant API sections that follow. When
+the keyBag is used for deleted entities, the deleted element is set to "true,"
+and all entities listed in such a keyBag are assumed to represent deletions.<br>
+<br>
+</p>
+
+<p class="MsoBodyText"><span style="font-family:"MS Shell Dlg";color:black;
+letter-spacing:0pt">A UDDI node MUST never inform the subscriber of an entity
+that temporarily matched the subscription criteria but was removed or modified
+to no longer match the subscription criteria before the subscriber was informed
+of the match.</span></p>
+
+<p class="MsoBodyText">A UDDI node MAY inform a subscriber about the real or
+virtual deletion of an entity multiple times.</p>
+
+<p class="MsoBodyText">The syntax of a keyBag is shown here:</p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image095.gif" border="0" height="271" width="371"></p>
+
+<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>
+
+<p class="MsoBodyText">The APIs in this section describe how to interact with a
+UDDI node implementation to create and manage requests for the tracking of new
+and changed registry content. These APIs are synchronous and are exposed via SOAP, although the notifications they may generate are not. </p>
+
+<p class="MsoBodyText">The subscription APIs are: </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>delete_subscription: </b> Cancels one or more specified
+subscriptions.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>get_subscriptionResults:</b> Synchronously returns registry
+data pertaining to a particular subscription within a specified time period.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>get_subscriptions:</b> Returns a list of existing
+subscriptions previously saved by the subscriber.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>save_subscription:</b> Establishes a new subscription or
+changes an existing one. Also used to renew existing subscriptions.</p>
+
+<p class="MsoBodyText">The OPTIONAL client API is:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>notify_subscriptionListener</b>: A node invoked API which the client implements as a subscription listener service to accept notifications
+containing the data that changed since notify_subscriptionListener was last
+invoked for a particular subscription.</p>
*/
@WebService(name = "UDDI_Subscription_PortType", targetNamespace = "urn:uddi-org:v3_service")
@XmlSeeAlso({
@@ -79,17 +327,32 @@ import org.uddi.sub_v3.SubscriptionResul
public interface UDDISubscriptionPortType extends Remote {
/**
- *
- * Cancels an existing subscription. authInfo: This optional argument is an
- * element that contains an authentication token. Registries that wish to
- * restrict who can delete a subscription typically require authInfo for
- * this call, though this is a matter of node policy.
- *
- * · subscriptionKey: This required argument specifies, using anyURIs, the
- * subscription or subscriptions to be deleted.
+ *Cancels an existing subscription.
*
* @param body
+ * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>authInfo</i></b>: This optional argument is an element
+that contains an authentication token. Registries that wish to restrict who
+can delete a subscription typically require authInfo for this call, though this
+is a matter of node policy.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>subscriptionKey:</i></b> This required argument specifies,
+using <i>anyURIs,</i> the subscription or subscriptions to be deleted.</p>
+* @return If no errors occur then an empty message is returned.
* @throws DispositionReportFaultMessage, RemoteException
+ * <p class="MsoBodyText">If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault. In addition
+to the errors common to all APIs, the following error information is relevant
+here:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_userMismatch</b>: signifies that an attempt has been made to
+use the subscription API to delete a subscription that is controlled by another
+party.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidKeyPassed</b>: signifies that the subscriptionKey is
+invalid or that the subscription has expired.</p>
*/
@WebMethod(operationName = "delete_subscription", action = "delete_subscription")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@@ -98,10 +361,131 @@ public interface UDDISubscriptionPortTyp
throws DispositionReportFaultMessage, RemoteException;
/**
- *
+ *This API allows a subscriber to request that the
+information pertaining to an existing subscription be returned. This is
+useful, for example, to obtain historical data when a subscription is first set
+up or when a subscriber misses the notification normally provided by the
+registry. The results are returned synchronously as the response to this
+call. The get_subscriptionResults API can also be used as an alternative to
+notifications for obtaining subscription data. If this is the preference, then
+the subscriber SHOULD not provide a bindingKey when saving the associated
+subscription. See Section <a href="#_Ref536850105 ">5.5.8</a> <i>save_subscription</i>.
+This API is not affected by the value of the notificationInterval in the
+subscription.
* @param body
+ * <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>authInfo</i></b>: This optional argument is an element
+that contains an authentication token. Registries that wish to restrict who
+can retrieve subscription data typically require authInfo for this call, though
+this is a matter of node policy.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>chunkToken</i></b>: This optional argument is used to
+retrieve subsequent groups of data when the first call to this API indicates more data is available. This occurs when a chunkToken is returned whose value is
+not "0" in the subscriptionResultsList structure described in the
+next section. To retrieve the next chunk of data, the value returned should be
+used as an argument to the next invocation of this API.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>coveragePeriod</i></b>: This structure defines the time
+period over which the most recent changes in node data are compared with the
+subscription criteria in order to produce the result set. It provides start and
+end date/time information according to the format described in Section <a href="#_Ref3402225 ">5.5.4</a> <i>Subscription Coverage Period</i>. The "current"
+state of registry entries pertaining to the subscription referenced by the
+subscriptionKey provided are returned if they were last created, changed or
+deleted during the specified time period.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>subscriptionKey:</i></b> This required argument of type
+anyURI identifies the subscription for which non-recurring synchronous results
+are being sought.</p>
+* <img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image101.gif">
* @return returns org.uddi.sub_v3.SubscriptionResultsList
+ * <p class="MsoBodyText">A subscriptionResultsList is returned whose content is
+determined by the coveragePeriod and the criteria in the subscription:</p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image102.gif" border="0" height="484" width="523"></p>
+
+<p class="MsoBodyText"><b>Attributes</b></p>
+
+<table class="specTable" style="width:45.68%;margin-left:.5in;border-collapse:collapse;border:none" border="1" cellpadding="0" cellspacing="0" width="45%">
+ <tbody><tr>
+ <td style="width:60.52%;border:solid black 1.0pt;
+ background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="60%">
+ <p class="MsoNormal"><b>Name </b></p>
+ </td>
+ <td style="width:39.48%;border:solid black 1.0pt;
+ border-left:none;background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="39%">
+ <p class="MsoNormal"><b>Use </b></p>
+ </td>
+ </tr>
+ <tr style="height:18.15pt">
+ <td style="width:60.52%;border:solid black 1.0pt;
+ border-top:none;padding:0in 5.4pt 0in 5.4pt;height:18.15pt" valign="top" width="60%">
+ <p class="MsoNormal">someResultsUnavailable </p>
+ </td>
+ <td style="width:39.48%;border-top:none;border-left:
+ none;border-bottom:solid black 1.0pt;border-right:solid black 1.0pt;
+ padding:0in 5.4pt 0in 5.4pt;height:18.15pt" valign="top" width="39%">
+ <p class="MsoNormal">optional </p>
+ </td>
+ </tr>
+</tbody></table>
+
+<p class="MsoBodyText"> </p>
+
+<p class="MsoBodyText">Subscription results MAY be chunked. See Section <a href="#_Ref4234690 ">5.5.5</a> <i>Chunking of Returned Subscription Data, </i>for
+more information on chunking of results. If results are chunked, then
+subsequent "chunks" can be retrieved using the chunkToken returned as
+an argument in a subsequent invocation of this API.</p>
+
+<p class="MsoBodyText">Note that the results returned in the
+subscriptionResultsList represent a snapshot of the current state of relevant
+entries in the registry. They are non-transactional in nature and prior states
+cannot be returned. Deleted entities and virtual deletes of entities, which
+have been changed in such a way that they no longer match the subscription
+criterion saved with the subscription, are returned only in the form of a
+keyBag structure, for which the deleted element is set to "true". A
+UDDI node MAY inform a subscriber about the real or virtual deletion of an
+entity multiple times.</p>
+
+<p class="MsoBodyText">The someResultsUnavailable attribute is set to "true"
+whenever the node has found it necessary to flush subscription results
+information pertaining to entity deletions (either actual or virtual) which
+pertain to this subscription, which have not yet been reported through prior
+calls to this API, or through use of the notify_subscriptionListener API described below. The period of time which a node retains information on deletions for a
+given subscription is a matter of node policy.</p>
+
+<p class="MsoBodyText">The API used in the subscription filter determines the
+sort order for returned entities. By default, they will be sorted according to
+the behavior specified in the "returns" section of that API.</p>
* @throws DispositionReportFaultMessage, RemoteException
+ * <p class="MsoBodyText">If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault. In addition
+to the errors common to all APIs, the following error information is relevant
+here:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidKeyPassed</b>: signifies that the subscriptionKey is
+invalid or that the subscription has expired.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidValue</b>: signifies that the chunkToken value
+supplied is either invalid or has expired.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_unsupported</b>: signifies that one of the argument values
+was not supported by this implementation. The offending argument is clearly
+indicated in the error text.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_userMismatch</b>: signifies that, in a violation of node
+policy, an attempt has been made to use the subscription API to change a subscription that is controlled by another party.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidTime</b>: signifies that one or both of the values
+provided in the coveragePeriod range is invalid or does not define a range.
+The error structure signifies the condition that occurred and the error text
+clearly calls out the cause of the problem.</p>
*/
@WebMethod(operationName = "get_subscriptionResults", action = "get_subscriptionResults")
@WebResult(name = "subscriptionResultsList", targetNamespace = "urn:uddi-org:sub_v3", partName = "body")
@@ -136,123 +520,204 @@ public interface UDDISubscriptionPortTyp
throws DispositionReportFaultMessage, RemoteException;
/**
- * 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.
- *
- * 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.
- *
-* 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.
- *
- * · bindingKey: This optional argument of type anyURI specifies the
- * bindingTemplate which the node is to use to deliver notifications to
- * subscription listeners. It is only required when asynchronous
- * notifications are used. This bindingTemplate MUST define either a Web
- * service that implements notify_subscriptionListener (see below), or an
- * email address to receive the notifications. If a
- * notify_subscriptionListener Web service is identified, the node invokes
- * it to deliver notifications. If an email address is identified, the node
- * delivers notifications via email to the address supplied. When
- * notifications are delivered via email, the body of the email contains the
- * body of the SOAP message, which would have been sent to the
- * notify_subscriptionListener service if that option had been chosen. The
- * publisher making the subscription request MUST own the bindingTemplate.
- * If this argument is not supplied, no notifications are sent, although
- * subscribers may still use the get_subscriptionResults API to obtain
- * subscription results. See Section 5.5.11 get_subscriptionResults for
- * 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 delivery failures MAY result in cancellation of the
- * corresponding subscription.
- *
- * · brief: This optional argument controls the level of detail returned to
- * a subscription listener. The default is "false" when omitted. When set to
- * "true," it indicates that the subscription results are to be returned to
- * the subscriber in the form of a keyBag, listing all of the entities that
- * matched the subscriptionFilter. Refer to Section 5.5.6 Use of keyBag in
- * Subscription, for additional information. This option has no effect on
- * the assertionStatusReport structure, which is returned as part of a
- * notification when the subscriptionFilter specifies the
- * get_assertionStatusReport filter criteria. See the explanation of
- * subscriptionFilter below.
- *
- * · expiresAfter: This optional argument allows subscribers to specify the
- * period of time for which they would like the subscription to exist. It is
- * of the XML Schema type xsd:dateTime. Specifying a value for this argument
- * is no guarantee that the node will accept it without change. Information
- * on the format of expiresAfter can be found in Section 5.5.1.1 Specifying
- * Durations.
- *
- * · maxEntities: This optional integer specifies the maximum number of
- * entities in a notification returned to a subscription listener. If not
- * specified, the number of entities sent is not limited, unless by node
- * policy.
- *
- * · subscriptionFilter: This argument specifies the filtering criteria
- * which limits the scope of a subscription to a subset of registry records.
- * It is required except when renewing an existing subscription. The get_xx
- * and find_xx APIs are all valid choices for use as a subscriptionFilter.
- * Only one of these can be chosen for each subscription. Notifications,
- * based on the subscriptionFilter, are sent to the subscriber if and only
- * if there are changes at the node, which match this criterion during a
- * notification period. A subscriptionFilter MUST contain exactly one of the
- * allowed inquiry elements. The authInfo argument of the specified get_xx
- * or find_xx API call is not required here and is ignored if specified. All
- * of the other arguments supported with each of these inquiry APIs are
- * valid for use here.
- *
- * Specifying find_relatedBusinesses is useful for tracking when reciprocal
- * relationships are formed or dissolved. Specifying
- * get_assertionStatusReport can be used in tracking when reciprocal
- * relationships (which pertain to a business owned by the subscriber) are
- * formed, dissolved, or requested by the owners of some other business.
- *
- * For a get_assertionStatusReport based subscription, there is a specific
- * status value, status:both_incomplete, defined in the XML schema. When
- * appearing in an assertionStatusItem of a subscriptionResultsList,
- * status:both_incomplete indicates that the publisher assertion embedded in
- * the assertionStatusItem has been deleted from both ends.
- *
- * Note that the above handling of deleted publisher assertions is different
- * from the case when a business entity, business service, binding template,
- * or tModel is removed. In the latter case, the key to the entity in
- * question is simply put inside a keyBag. A publisher assertion, on the
- * other hand, has no key and therefore the keyBag idea is not applicable.
*
- * · subscriptionKey: This optional argument of type anyURI identifies the
- * subscription. To renew or change an existing subscription, a valid
- * subscriptionKey MUST be provided. When establishing a new subscription,
- * the subscriptionKey MAY also be either omitted or specified as an empty
- * string in which case the node MUST assign a unique key. If
- * subscriptionKey is specified for a new subscription, the key MUST conform
- * to the registryâs policy on publisher-assigned keys.
- *
- * · notificationInterval: This optional argument is only required when
- * asynchronous notifications are used. It is of type xsd:duration and
- * specifies how often change notifications are to be provided to a
- * subscriber. If the notificationInterval specified is not acceptable due
- * to node policy, then the node adjusts the value to match the next longer
- * time period that is supported. The adjusted value is provided with the
- * returns from this API. Also see Section 5.5.1.1 Specifying Durations.
- *
- * @param subscription
- * @param authInfo
+ * 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.
+
+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.
+*
+* <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image096.gif" border="0" height="121" width="393"></p>
+
+<p class="MsoBodyText">The syntax of the subscription structure is:</p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image097.gif" border="0" height="236" width="389"></p>
+
+<p class="MsoBodyText"><b>Attributes</b></p>
+
+<table class="specTable" style="width:33.34%;margin-left:.5in;border-collapse:collapse;border:none" border="1" cellpadding="0" cellspacing="0" width="33%">
+ <tbody><tr>
+ <td style="width:49.98%;border:solid black 1.0pt;
+ background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="49%">
+ <p class="MsoNormal"><b>Name </b></p>
+ </td>
+ <td style="width:50.02%;border:solid black 1.0pt;
+ border-left:none;background:#FFFFCA;padding:0in 5.4pt 0in 5.4pt" valign="top" width="50%">
+ <p class="MsoNormal"><b>Use </b></p>
+ </td>
+ </tr>
+ <tr>
+ <td style="width:49.98%;border:solid black 1.0pt;
+ border-top:none;padding:0in 5.4pt 0in 5.4pt" valign="top" width="49%">
+ <p class="MsoNormal">brief </p>
+ </td>
+ <td style="width:50.02%;border-top:none;border-left:
+ none;border-bottom:solid black 1.0pt;border-right:solid black 1.0pt;
+ padding:0in 5.4pt 0in 5.4pt" valign="top" width="50%">
+ <p class="MsoNormal">optional </p>
+ </td>
+ </tr>
+</tbody></table>
+
+<p class="MsoBodyText"> </p>
+
+<span style="font-size:10.0pt;font-family:Arial;letter-spacing:-.25pt"><br style="page-break-before:always" clear="all">
+</span>
+
+<p class="MsoBodyText"> </p>
+
+<p class="MsoBodyText">The syntax of the subscriptionFilter structure is:</p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image098.gif" border="0" height="368" width="441"></p>
+ * @param subscription<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>bindingKey:</i></b> This optional argument of type anyURI
+specifies the <i>bindingTemplate</i> which the node is to use to deliver
+notifications to subscription listeners. It is only required when asynchronous
+notifications are used. This <i>bindingTemplate</i> MUST define either a Web
+service that implements notify_subscriptionListener (see below), or an email
+address to receive the notifications. If a notify_subscriptionListener Web
+service is identified, the node invokes it to deliver notifications. If an
+email address is identified, the node delivers notifications via email to the
+address supplied. When notifications are delivered via email, the body of the
+email contains the body of the SOAP message, which would have been sent to the
+notify_subscriptionListener service if that option had been chosen.<span class="MsoCommentReference"><span style="display:none">.</span></span> The
+publisher making the subscription request MUST own the bindingTemplate. If
+this argument is not supplied, no notifications are sent, although subscribers
+may still use the get_subscriptionResults API to obtain subscription results.
+See Section <a href="#_Ref536844845 ">5.5.11</a> <i>get_subscriptionResults </i>for
+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
+delivery failures MAY result in cancellation of the corresponding subscription.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>brief</i></b>: This optional argument controls the level
+of detail returned to a subscription listener. The default is "false"
+when omitted. When set to "true," it indicates that the subscription
+results are to be returned to the subscriber in the form of a keyBag, listing
+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
+additional information. This option has no effect on the assertionStatusReport
+structure, which is returned as part of a notification when the
+subscriptionFilter specifies the get_assertionStatusReport filter criteria.
+See the explanation of subscriptionFilter below.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>expiresAfter</i></b>: This optional argument allows
+subscribers to specify the period of time for which they would like the
+subscription to exist. It is of the XML Schema type xsd:dateTime. Specifying
+a value for this argument is no guarantee that the node will accept it without
+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>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>maxEntities</i></b>: This optional integer specifies the
+maximum number of entities in a notification returned to a subscription
+listener. If not specified, the number of entities sent is not limited, unless
+by node policy.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>subscriptionFilter</i></b>: This argument specifies the
+filtering criteria which limits the scope of a subscription to a subset of
+registry records. It is required except when renewing an existing subscription.
+The get_xx and find_xx APIs are all valid choices for use as a
+subscriptionFilter. Only one of these can be chosen for each subscription.
+Notifications, based on the subscriptionFilter, are sent to the subscriber if
+and only if there are changes at the node, which match this criterion during a
+notification period. A subscriptionFilter MUST contain exactly one of the
+allowed inquiry elements. The authInfo argument of the specified get_xx or
+find_xx API call is not required here and is ignored if specified. All of the
+other arguments supported with each of these inquiry APIs are valid for use
+here.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in">Specifying find_relatedBusinesses
+is useful for tracking when reciprocal relationships are formed or dissolved.
+Specifying get_assertionStatusReport can be used in tracking when reciprocal
+relationships (which pertain to a business owned by the subscriber) are formed,
+dissolved, or requested by the owners of some other business.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in">For a get_assertionStatusReport
+based subscription, there is a specific status value, <b>status:both_incomplete</b>,
+defined in the XML schema. When appearing in an assertionStatusItem of a
+subscriptionResultsList, status:both_incomplete indicates that the publisher
+assertion embedded in the assertionStatusItem has been deleted from both ends. </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in">Note that the above handling of
+deleted publisher assertions is different from the case when a business entity,
+business service, binding template, or tModel is removed. In the latter case,
+the key to the entity in question is simply put inside a keyBag. A publisher
+assertion, on the other hand, has no key and therefore the keyBag idea is not
+applicable.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>subscriptionKey</i></b>: This optional argument of type <i>anyURI</i>
+identifies the subscription. To renew or change an existing subscription, a
+valid subscriptionKey MUST be provided. When establishing a new subscription,
+the subscriptionKey MAY also be either omitted or specified as an empty string in
+which case the node MUST assign a unique key. If subscriptionKey is specified
+for a new subscription, the key MUST conform to the registryâs policy on
+publisher-assigned keys.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b><i>notificationInterval</i></b>: This optional argument is
+only required when asynchronous notifications are used. It is of type
+xsd:duration and specifies how often change notifications are to be provided to
+a subscriber. If the notificationInterval specified is not acceptable due to
+node policy, then the node adjusts the value to match the next longer time
+period that is supported. The adjusted value is provided with the returns from
+this API. Also see Section <a href="#_Ref535515666 ">5.5.1.1</a> <i>Specifying
+Durations</i>.</p>
+ * @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.
+ * @return <p class="MsoBodyText">Upon successful completion this API returns a <i>subscriptions</i>
+structure. Included in the subscription structure(s) it MUST contain is a <i>subscriptionKey</i>
+(of type anyURI) that is used by the subscriber to manage the subscription.
+This key is required in order to delete (unsubscribe), modify or renew the
+subscription. If a subscriber has multiple subscriptions, the subscriptionKey
+can be used to distinguish between different subscriptions. The <i>subscriptionKey</i>
+is also part of the data contained in the notifications returned to subscription
+listeners. </p>
+
+<p class="MsoBodyText"> </p>
+
+<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. Nodes
+SHOULD attempt to honor the value(s) provided with the save_subscription
+request, but MAY modify them based on node policy. Depending upon the nodeâs
+policy, the node MAY delete a subscription after it has expired.</p>
+
+<p class="MsoBodyText">The value of the <i>notificationInterval</i> included in
+the subscription structure(s) returned MAY be adjusted by the node to the value
+closest to that requested which is supported by its policies. Depending upon
+the Registryâs workload a node MAY skip a notification cycle. If a cycle is
+skipped, the next notification sent SHOULD include information based on
+registry activity, which has occurred since the last notification was issued.</p>
* @throws DispositionReportFaultMessage, RemoteException
+ * <p class="MsoBodyText">If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault. In addition
+to the errors common to all APIs, the following error information is relevant
+here:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidKeyPassed</b>: signifies that an entity key value
+passed did not match with any known key values. The error structure signifies
+that the condition occurred and the error text clearly calls out the offending
+key.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_unsupported</b>: signifies that one of the argument values
+was not supported by this implementation. The offending argument is clearly
+indicated in the error text.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_resultSetTooLarge</b>: signifies that the node refuses to
+accept the subscription because it deems that result sets associated with the
+subscription are too large. The subscription criteria that triggered this
+error should be refined and re-issued. </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_accountLimitExceeded</b>: signifies that the request
+exceeded the quantity limits for subscription requests, based on node policy.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_userMismatch</b>: signifies that an attempt has been made to
+use the subscription API to change a subscription that is controlled by another
+party. Or that the bindingTemplate specified does not belong to the publisher.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_requestDenied</b>: signifies that the subscription cannot be
+renewed. The request has been denied due to either node or registry policy.</p>
*/
@WebMethod(operationName = "save_subscription", action = "save_subscription")
@RequestWrapper(localName = "save_subscription", targetNamespace = "urn:uddi-org:sub_v3", className = "org.uddi.sub_v3.SaveSubscription")
Modified: juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetCachingPortType.java
URL: http://svn.apache.org/viewvc/juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetCachingPortType.java?rev=1479003&r1=1479002&r2=1479003&view=diff
==============================================================================
--- juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetCachingPortType.java (original)
+++ juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetCachingPortType.java Fri May 3 23:23:27 2013
@@ -38,6 +38,93 @@ import org.uddi.vscache_v3.ValidValue;
* JAX-WS RI 2.1.5-b03-
* Generated source version: 2.1
*
+ * <p class="MsoBodyText">Whenever a keyedReference is involved in a save operation
+it may be checked to see that it is valid. Similarly, a keyedReferenceGroup
+element that is involved in a save operation may also be checked to ensure that
+it is valid. Checking is performed for tModels that are deemed to be
+"checked", as determined by the policy of the UDDI registry.</p>
+
+<p class="MsoBodyText">UDDI provides the ability for third parties to register
+value sets, and then control the validation process used by UDDI to perform
+such checks. UDDI registries MAY support caching of these external value sets.
+UDDI registries MAY also support external validation. Node and registry
+policies determine the manner in which validation of references to external
+value sets is performed. The APIs in this section can be used by UDDI
+registries and nodes in their validation policies.</p>
+
+<p class="MsoBodyText">Third parties that want to provide an external checking
+capability may be required by the UDDI registry to implement a Web service in
+the same manner that UDDI does (e.g. using SOAP for message passing using
+literal encoding) that exposes a single method named validate_values. The
+interface for validate_values is described here.</p>
+
+<p class="MsoBodyText">In some cases a node may desire to eliminate or minimize
+the number of calls to external validation Web services. It can do so by
+caching valid values for those external value sets that allow caching of their
+values. A node has two normative options for obtaining the set of valid
+values. One is to periodically obtain the set of valid values from those value
+set providers that implement a Web service that handles the get_allValidValues API. This API is described below. The other method of obtaining a cache of valid values is to
+accumulate the valid values from successful calls to validate_values.</p>
+*
+* <p class="MsoBodyText">The Application Programming Interfaces in this section
+represent capabilities that a UDDI registry MAY use to enable validation of
+references to value sets. Registry policy determines which external value sets
+are supported and how. See Section <a href="#_Ref9007633 ">9.4.19</a> <i>Value
+Set Policies </i>and Section <a href="#_Ref9007695 ">9.6.5</a><i>Value Sets </i>for
+more information on registry support of external value sets. These SOAP messages all behave synchronously.</p>
+
+<p class="MsoBodyText">The publicly accessible APIs that are used to support
+external value set validation are:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><a href="#_validate_values"><b><span style="color:windowtext;
+text-decoration:none">validate_values</span></b></a>: Used by nodes to allow
+external providers of value set validation Web services to assess whether
+keyedReferences or keyedReferenceGroups are valid. Returns a dispositionReport
+structure.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><a href="#_get_allValidValues"><b><span style="color:windowtext;
+text-decoration:none">get_allValidValues</span></b></a>: Used by nodes that
+support caching of valid values from cacheable checked value sets to obtain the
+set of valid values. Returns an empty message or a dispositionReport structure.</p>
+
+<p class="MsoBodyText">Registry policy may require value set providers that offer
+one of these Web services to publish the bindingTemplate for the service and
+the tModel for the value set in a particular way so that the proper Web service
+can be discovered. See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value sets</i>
+for more information<i>.</i> When a value set provider offers one of these Web
+services, a tModel for the checked value set SHOULD be published in any
+registry the provider wishes to offer it, and a bindingTemplate SHOULD be
+published for the Web service(s) the value set provider offers for the checked
+value set. The tModel SHOULD have categorizations from the uddi-org:types
+category system to indicate the type of value set (<i>categorization</i>, <i>identifier</i>,
+<i>relationship</i>, <i>categorizationGroup</i>), that it is checked (<i>checked</i>),
+and, if the value set provider allows validation to occur against node caches
+of valid values, the <i>cacheable</i> categorization should also be provided. </p>
+
+<p class="MsoBodyText">In order for a value set to be considered checked, the
+tModel MUST first be categorized with the checked value from the uddi-org:types
+category system. The decision to check such value sets is a registry and node
+policy decision. </p>
+
+<p class="MsoBodyText">If a value set tModel is categorized as checked, then in
+response to attempts to publish a keyedReference which uses the checked tModel,
+nodes MUST either perform the required validation, or return E_unsupported.</p>
+
+<p class="MsoBodyText">The tModel should also have a categorization reference to
+the bindingTemplate of the get_allValidValues or validate_values Web service
+that the value set provider designates, using the uddi-org:validatedBy category
+system. See Section <a href="#_Ref8977125 ">11.1.1</a> <i>UDDI Types Category
+System </i>and Section <a href="# ">11.1.7</a> <i>Validated By Category System</i>
+for more information.</p>
+
+<p class="MsoBodyText">The bindingTemplate for the get_allValidValues or the
+validate_values Web service SHOULD reference in its tModelInstanceDetails the
+appropriate value set API tModel (Section <a href="#_Ref8979902 ">11.2.7</a> <i>Value
+Set Caching API tModel </i>or Section <a href="#_Ref8979938 ">11.2.8</a> <i>Value
+Set Validation API tModel</i>) as well tModels for all of the value sets the
+service applies to. </p>
*/
@WebService(name = "UDDI_ValueSetCaching_PortType", targetNamespace = "urn:uddi-org:v3_service")
@XmlSeeAlso({
@@ -56,12 +143,73 @@ public interface UDDIValueSetCachingPort
/**
- *
- * @param tModelKey
- * @param authInfo
- * @param validValue
- * @param chunkToken
+ * <p class="MsoBodyText">A UDDI node that supports external value sets MAY invoke a get_allValidValues Web service offered by a value set provider that has granted
+permission to that registry to cache the valid values for that value set. The
+external value set provider MAY offer the get_allValidValues Web service and
+the UDDI node MAY use it. The normal use is to return a full set of valid
+values for the identified value set. If the value set provider determines
+there are too many values to return in one chunk, the set of valid values may
+be returned in chunks.</p>
+
+<p class="MsoBodyText">Registry policy may require the value set provider that
+offers a get_allValidValues Web service to republish its value set tModel when
+the cache should be re-acquired by participating nodes. See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value Sets</i> for more information.</p>
+
+<p class="MsoBodyText">get_allValidValues can similarly be used to obtain the set
+of tModelKeys for value sets that can participate in a cached category group
+system.</p>
+* The called Web service returns the set of valid values in a validValuesList on success. This structure lists every valid value associated with the value set or category group system that is described by the tModelKey provided. In the event too many values exist to be returned in a single response (i.e., the message size exceeds the maximum number of bytes allowed by the UDDI registry), or the value set provider wants to supply the values in multiple packets, then the validValueList includes the chunkToken element and the API can be re-issued to get the remaining valid values.
+*
+* <h5 style="margin-left:0in;text-indent:0in">Chunking of valid values</h5>
+
+<p class="MsoBodyText">If the value set provider determines that there are too
+many values to be returned in a single group, then the provider SHOULD provide
+a chunkToken with the results. The chunkToken is a string based token which is
+used by the value set provider to maintain the state of the set of values for a
+particular caller, when these results are chunked across multiple responses.
+Providers should establish their own policies for determining the content and
+format of the chunkToken. The chunkToken returned with a particular value set
+result set SHOULD be used to retrieve subsequent results. If no more results
+are pending, the value of the chunkToken will be "0" or the
+chunkToken will be absent. </p>
+
+<p class="MsoBodyText">A chunkToken is intended as a short-term aid in obtaining
+contiguous results across multiple API calls and is therefore likely to remain
+valid for only a short time. Value set providers may establish policies on how
+long a chunkToken remains valid.</p>
+ * @param tModelKey tModelKey: A required uddiKey value that identifies the specific instance of the tModel which describes the value set or category group system for which a Web service to get all valid values has been provided. It uniquely identifies the category, identifier, or category group system for which valid values are being requested.
+ * @param authInfo · authInfo: An optional element that contains an authentication token. Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Providers of get_allValidValues Web services that serve multiple registries and providers that restrict who can use their service may require authInfo for this API.
+ * @param validValue RETURN TYPE <p class="MsoBodyText">A validValuesList structure is returned containing the set
+of valid values for the external category or identifier system. The list MUST
+contain a chunkToken if the Web service provider wishes to provide the data in
+packets. The validValuesList has the form: </p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image106.gif" border="0" height="121" width="393"></p>
+
+<p class="MsoBodyText">And its contained validValue element has the form:</p>
+
+<p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image107.gif" border="0" height="71" width="347"></p>
+ * @param chunkToken · chunkToken: Optional element used to retrieve subsequent groups of data when the first invocation of this API indicates more data is available. This occurs when a chunkToken is returned whose value is not "0" in the validValuesList structure described in the next section. To retrieve the next chunk of data, the chunkToken returned should be used as an argument to the next invocation of this API.
* @throws DispositionReportFaultMessage
+ * <p class="MsoBodyText">If any error occurs in processing this API, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section <a href="#_Ref8980008 ">4.8</a> <i>Success and Error Reporting. </i>The following
+error information is relevant: </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidKeyPassed</b>: Signifies that the tModelKey passed
+did not match with the uddiKey of any known tModels. The details on the
+invalid key SHOULD be included in the dispositionReport element.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_noValuesAvailable</b>: Signifies that no values could be
+returned. </p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_unsupported</b>: Signifies that the Web service does not
+support this API.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidValue</b>: Signifies that the chunkToken value
+supplied is either invalid or has expired.</p>
*/
@WebMethod(operationName = "get_allValidValues", action = "get_allValidValues")
@RequestWrapper(localName = "get_allValidValues", targetNamespace = "urn:uddi-org:vscache_v3", className = "org.uddi.vscache_v3.GetAllValidValues")
Modified: juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetValidationPortType.java
URL: http://svn.apache.org/viewvc/juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetValidationPortType.java?rev=1479003&r1=1479002&r2=1479003&view=diff
==============================================================================
--- juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetValidationPortType.java (original)
+++ juddi/branches/juddi-3.2.x/uddi-ws/src/main/java/org/uddi/v3_service/UDDIValueSetValidationPortType.java Fri May 3 23:23:27 2013
@@ -38,6 +38,97 @@ import org.uddi.vs_v3.ValidateValues;
* JAX-WS RI 2.1.5-b03-
* Generated source version: 2.1
*
+ * <p class="MsoBodyText">Whenever a keyedReference is involved in a save operation
+it may be checked to see that it is valid. Similarly, a keyedReferenceGroup
+element that is involved in a save operation may also be checked to ensure that
+it is valid. Checking is performed for tModels that are deemed to be
+"checked", as determined by the policy of the UDDI registry.</p>
+
+<p class="MsoBodyText">UDDI provides the ability for third parties to register
+value sets, and then control the validation process used by UDDI to perform
+such checks. UDDI registries MAY support caching of these external value sets.
+UDDI registries MAY also support external validation. Node and registry
+policies determine the manner in which validation of references to external
+value sets is performed. The APIs in this section can be used by UDDI
+registries and nodes in their validation policies.</p>
+
+<p class="MsoBodyText">Third parties that want to provide an external checking
+capability may be required by the UDDI registry to implement a Web service in
+the same manner that UDDI does (e.g. using SOAP for message passing using
+literal encoding) that exposes a single method named validate_values. The
+interface for validate_values is described here.</p>
+
+<p class="MsoBodyText">In some cases a node may desire to eliminate or minimize
+the number of calls to external validation Web services. It can do so by
+caching valid values for those external value sets that allow caching of their
+values. A node has two normative options for obtaining the set of valid
+values. One is to periodically obtain the set of valid values from those value
+set providers that implement a Web service that handles the get_allValidValues API. This API is described below. The other method of obtaining a cache of valid values is to
+accumulate the valid values from successful calls to validate_values.</p>
+
+<h3><a name="_Toc85908142"></a><a name="_Toc53709336"></a><a name="_Toc45096421"></a><a name="_Toc45095964"></a><a name="_Toc42047341"></a><a name="_Toc535332281">5.6.1
+Value Set Programming Interfaces</a></h3>
+
+<p class="MsoBodyText">The Application Programming Interfaces in this section
+represent capabilities that a UDDI registry MAY use to enable validation of
+references to value sets. Registry policy determines which external value sets
+are supported and how. See Section <a href="#_Ref9007633 ">9.4.19</a> <i>Value
+Set Policies </i>and Section <a href="#_Ref9007695 ">9.6.5</a><i>Value Sets </i>for
+more information on registry support of external value sets. These SOAP messages all behave synchronously.</p>
+
+<p class="MsoBodyText">The publicly accessible APIs that are used to support
+external value set validation are:</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><a href="#_validate_values"><b><span style="color:windowtext;
+text-decoration:none">validate_values</span></b></a>: Used by nodes to allow
+external providers of value set validation Web services to assess whether
+keyedReferences or keyedReferenceGroups are valid. Returns a dispositionReport
+structure.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><a href="#_get_allValidValues"><b><span style="color:windowtext;
+text-decoration:none">get_allValidValues</span></b></a>: Used by nodes that
+support caching of valid values from cacheable checked value sets to obtain the
+set of valid values. Returns an empty message or a dispositionReport structure.</p>
+
+<p class="MsoBodyText">Registry policy may require value set providers that offer
+one of these Web services to publish the bindingTemplate for the service and
+the tModel for the value set in a particular way so that the proper Web service
+can be discovered. See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value sets</i>
+for more information<i>.</i> When a value set provider offers one of these Web
+services, a tModel for the checked value set SHOULD be published in any
+registry the provider wishes to offer it, and a bindingTemplate SHOULD be
+published for the Web service(s) the value set provider offers for the checked
+value set. The tModel SHOULD have categorizations from the uddi-org:types
+category system to indicate the type of value set (<i>categorization</i>, <i>identifier</i>,
+<i>relationship</i>, <i>categorizationGroup</i>), that it is checked (<i>checked</i>),
+and, if the value set provider allows validation to occur against node caches
+of valid values, the <i>cacheable</i> categorization should also be provided. </p>
+
+<p class="MsoBodyText">In order for a value set to be considered checked, the
+tModel MUST first be categorized with the checked value from the uddi-org:types
+category system. The decision to check such value sets is a registry and node
+policy decision. </p>
+
+<p class="MsoBodyText">If a value set tModel is categorized as checked, then in
+response to attempts to publish a keyedReference which uses the checked tModel,
+nodes MUST either perform the required validation, or return E_unsupported.</p>
+
+<p class="MsoBodyText">The tModel should also have a categorization reference to
+the bindingTemplate of the get_allValidValues or validate_values Web service
+that the value set provider designates, using the uddi-org:validatedBy category
+system. See Section <a href="#_Ref8977125 ">11.1.1</a> <i>UDDI Types Category
+System </i>and Section <a href="# ">11.1.7</a> <i>Validated By Category System</i>
+for more information.</p>
+
+<p class="MsoBodyText">The bindingTemplate for the get_allValidValues or the
+validate_values Web service SHOULD reference in its tModelInstanceDetails the
+appropriate value set API tModel (Section <a href="#_Ref8979902 ">11.2.7</a> <i>Value
+Set Caching API tModel </i>or Section <a href="#_Ref8979938 ">11.2.8</a> <i>Value
+Set Validation API tModel</i>) as well tModels for all of the value sets the
+service applies to. </p>
+ *
*/
@WebService(name = "UDDI_ValueSetValidation_PortType", targetNamespace = "urn:uddi-org:v3_service")
@XmlSeeAlso({
@@ -57,10 +148,87 @@ public interface UDDIValueSetValidationP
/**
*
+ * <p class="MsoBodyText">A UDDI node that supports external validation sends the
+validate_values API to the appropriate external Web service, of which there is
+exactly one, whenever a publisher saves data that uses a keyedReference or
+keyedReferenceGroup whose use is regulated by the external party who controls
+that Web service. For purposes of discussion, the identifier, category, and
+relationship type systems that the keyedReference elements refer to are called
+checked value sets. The category group systems that the keyedReferenceGroup
+elements refer to are similarly called checked category group systems. </p>
+
+<p class="MsoBodyText">The normal use for checked value sets is to verify that
+specific values (checking the keyValue attribute of values supplied) exist
+within the value set. For certain value sets the value set provider may
+further restrict the use of a value based on a contextual evaluation of the
+passed data. The provider may do enable this contextual checking by offering a
+validation Web service.</p>
+
+<p class="MsoBodyText">Validation algorithms for checked category group systems
+similarly verify that the contents of the keyedReferenceGroup elements form a
+valid set according to the validation algorithm for the checked category group
+system. Frequently such validation ensures that the value sets identified in
+contained keyedReferences are allowed to participate in the category group
+system.</p>
+*
* @param body
+ * The UDDI node that is calling validate_values MUST pass one or more businessEntity elements, one or more businessService elements, one or more bindingTemplate elements, one or more tModel elements, or one or more publisherAssertion elements as the sole argument to this Web service. The one or more elements passed represents the outermost UDDI data structure(s) being passed within a save_business, save_service, save_binding, save_tModel, add_publisherAssertion, or set_publisherAssertions API call. Multiple elements of the same type may be passed together if multiples are included in the same save invocation.
+
+The optional authInfo argument is an element that contains an authentication token. An authentication token is obtained using the get_authToken API call or through some other means external to this specification. Providers of validate_values Web services that serve multiple registries and providers that restrict who can use their service may require authInfo for this API.
+*
+* <p class="MsoBodyText">The called Web service for a checked value set performs
+validation on all of the keyedReferences or keyedReferenceGroups that are
+associated with the value sets the Web service is authorized to check. This
+can involve merely checking that the <i>keyValue</i> values supplied are good for
+the given value set (as signified by the embedded keyedReference tModelKey
+values). Other types of validation as desired may be performed, including
+context sensitive checks that utilize the information passed in the entity
+being saved.</p>
+
+<p class="MsoBodyText">The entity being saved may contain multiple references to
+values from the value set(s) that the validation Web service is authorized to
+validate. When the entity being saved is a businessEntity, contained
+businessService and bindingTemplate entities may themselves reference values
+from the authorized value sets as well. All references to values that are
+associated with the value set(s) that the validation Web service is authorized
+to check MUST be validated without regard to their placement in the entity
+being saved.</p>
+
+<p class="MsoBodyText">If the external value set and the node both support
+caching of valid values, the node may not invoke validate_values if it already
+knows that the referenced values are valid, through checking its cache.</p>
+
+<p class="MsoBodyText">A checked category group system is treated in the same manner
+as a checked value set. The tModelKey associated with the keyedReferenceGroup
+identifies the checked category group system. A node may be able to validate a
+reference to a cacheable checked category group system without calling
+validate_values if it can determine using its cache that the tModelKey
+attributes from the keyedReference elements contained in the
+keyedReferenceGroup are allowed for the category group system.</p>
* @return
* returns org.uddi.api_v3.DispositionReport
+ * If all values referenced in the entity being saved are valid from the value set(s) or category group system(s) that the validation Web service is authorized to validate, the proper response is an empty message.
* @throws DispositionReportFaultMessage, RemoteException
+ * <p class="MsoBodyText">If any error is found, or the called Web service needs to
+signal that the information being saved is not valid based on the validation
+algorithm chosen by the external Web service provider, then the Web service
+MUST raise a SOAP Fault as specified in Section <a href="#_Ref8979985 ">4.8</a>
+<i>Success and Error Reporting.</i></p>
+
+<p class="MsoBodyText">When an error is signaled in this fashion, the UDDI node MUST
+reject the pending change and return to the original caller the same SOAP fault data returned by the validation Web service. The error codes indicate one of the
+following reasons, and the error text clearly indicates the keyedReference or
+keyedReferenceGroup data that is being rejected and the reason it is being
+rejected.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_invalidValue</b>: One or more of the keyValues in the
+keyedReference or keyedReferences in the keyedReferenceGroup supplied failed
+validation. Only the first error encountered need be reported.</p>
+
+<p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman"">
+</span></span><b>E_valueNotAllowed</b>: The values may be valid, but are not
+allowed contextually.</p>
*/
@WebMethod(operationName = "validate_values", action = "validate_values")
@WebResult(name = "dispositionReport", targetNamespace = "urn:uddi-org:api_v3", partName = "body")
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@juddi.apache.org
For additional commands, e-mail: commits-help@juddi.apache.org