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.v3_service;
20  
21  import java.rmi.Remote;
22  import java.rmi.RemoteException;
23  import java.util.List;
24  import javax.jws.WebMethod;
25  import javax.jws.WebParam;
26  import javax.jws.WebService;
27  import javax.xml.bind.annotation.XmlSeeAlso;
28  import javax.xml.ws.Holder;
29  import javax.xml.ws.RequestWrapper;
30  import javax.xml.ws.ResponseWrapper;
31  import org.uddi.vscache_v3.ValidValue;
32  
33  
34  /**
35   * This portType defines all of the UDDI value set caching operations.
36   * 
37   * This class was generated by the JAX-WS RI.
38   * JAX-WS RI 2.1.5-b03-
39   * Generated source version: 2.1
40   * 
41   * <p class="MsoBodyText">Whenever a keyedReference is involved in a save operation
42  it may be checked to see that it is valid.&nbsp; Similarly, a keyedReferenceGroup
43  element that is involved in a save operation may also be checked to ensure that
44  it is valid.&nbsp; Checking is performed for tModels that are deemed to be
45  "checked", as determined by the policy of the UDDI registry.</p>
46  
47  <p class="MsoBodyText">UDDI provides the ability for third parties to register
48  value sets, and then control the validation process used by UDDI to perform
49  such checks. UDDI registries MAY support caching of these external value sets.&nbsp;
50  UDDI registries MAY also support external validation.&nbsp; Node and registry
51  policies determine the manner in which validation of references to external
52  value sets is performed.&nbsp; The APIs in this section can be used by UDDI
53  registries and nodes in their validation policies.</p>
54  
55  <p class="MsoBodyText">Third parties that want to provide an external checking
56  capability may be required by the UDDI registry to implement a Web service in
57  the same manner that UDDI does (e.g. using SOAP for message passing using
58  literal encoding) that exposes a single method named validate_values.&nbsp; The
59  interface for validate_values is described here.</p>
60  
61  <p class="MsoBodyText">In some cases a node may desire to eliminate or minimize
62  the number of calls to external validation Web services.&nbsp; It can do so by
63  caching valid values for those external value sets that allow caching of their
64  values.&nbsp; A node has two normative options for obtaining the set of valid
65  values.&nbsp; One is to periodically obtain the set of valid values from those value
66  set providers that implement a Web service that handles the get_allValidValues API.&nbsp; This API is described below.&nbsp; The other method of obtaining a cache of valid values is to
67  accumulate the valid values from successful calls to validate_values.</p>
68  * 
69  * <p class="MsoBodyText">The Application Programming Interfaces in this section
70  represent capabilities that a UDDI registry MAY use to enable validation of
71  references to value sets.&nbsp; Registry policy determines which external value sets
72  are supported and how.&nbsp; See Section <a href="#_Ref9007633 ">9.4.19</a> <i>Value
73  Set Policies </i>and Section <a href="#_Ref9007695 ">9.6.5</a><i>Value Sets </i>for
74  more information on registry support of external value sets.&nbsp; These SOAP messages all behave synchronously.</p>
75  
76  <p class="MsoBodyText">The publicly accessible APIs that are used to support
77  external value set validation are:</p>
78  
79  <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;
80  </span></span><a href="#_validate_values"><b><span style="color:windowtext;
81  text-decoration:none">validate_values</span></b></a>: Used by nodes to allow
82  external providers of value set validation Web services to assess whether
83  keyedReferences or keyedReferenceGroups are valid.&nbsp; Returns a dispositionReport
84  structure.</p>
85  
86  <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;
87  </span></span><a href="#_get_allValidValues"><b><span style="color:windowtext;
88  text-decoration:none">get_allValidValues</span></b></a>: Used by nodes that
89  support caching of valid values from cacheable checked value sets to obtain the
90  set of valid values.&nbsp; Returns an empty message or a dispositionReport structure.</p>
91  
92  <p class="MsoBodyText">Registry policy may require value set providers that offer
93  one of these Web services to publish the bindingTemplate for the service and
94  the tModel for the value set in a particular way so that the proper Web service
95  can be discovered.&nbsp; See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value sets</i>
96  for more information<i>.</i>&nbsp; When a value set provider offers one of these Web
97  services, a tModel for the checked value set SHOULD be published in any
98  registry the provider wishes to offer it, and a bindingTemplate SHOULD be
99  published for the Web service(s) the value set provider offers for the checked
100 value set.&nbsp; The tModel SHOULD have categorizations from the uddi-org:types
101 category system to indicate the type of value set (<i>categorization</i>, <i>identifier</i>,
102 <i>relationship</i>, <i>categorizationGroup</i>), that it is checked (<i>checked</i>),
103 and, if the value set provider allows validation to occur against node caches
104 of valid values, the <i>cacheable</i> categorization should also be provided.&nbsp; </p>
105 
106 <p class="MsoBodyText">In order for a value set to be considered checked, the
107 tModel MUST first be categorized with the checked value from the uddi-org:types
108 category system. The decision to check such value sets is a registry and node
109 policy decision.&nbsp; </p>
110 
111 <p class="MsoBodyText">If a value set tModel is categorized as checked, then in
112 response to attempts to publish a keyedReference which uses the checked tModel,
113 nodes MUST either perform the required validation, or return E_unsupported.</p>
114 
115 <p class="MsoBodyText">The tModel should also have a categorization reference to
116 the bindingTemplate of the get_allValidValues or validate_values Web service
117 that the value set provider designates, using the uddi-org:validatedBy category
118 system.&nbsp; See Section <a href="#_Ref8977125 ">11.1.1</a> <i>UDDI Types Category
119 System </i>and Section <a href="# ">11.1.7</a> <i>Validated By Category System</i>
120 for more information.</p>
121 
122 <p class="MsoBodyText">The bindingTemplate for the get_allValidValues or the
123 validate_values Web service SHOULD reference in its tModelInstanceDetails the
124 appropriate value set API tModel (Section <a href="#_Ref8979902 ">11.2.7</a> <i>Value
125 Set Caching API tModel </i>or Section <a href="#_Ref8979938 ">11.2.8</a> <i>Value
126 Set Validation API tModel</i>) as well tModels for all of the value sets the
127 service applies to.&nbsp; </p>
128  */
129 @WebService(name = "UDDI_ValueSetCaching_PortType", targetNamespace = "urn:uddi-org:api_v3_portType")
130 @XmlSeeAlso({
131     org.uddi.custody_v3.ObjectFactory.class,
132     org.uddi.repl_v3.ObjectFactory.class,
133     org.uddi.subr_v3.ObjectFactory.class,
134     org.uddi.api_v3.ObjectFactory.class,
135     org.uddi.vscache_v3.ObjectFactory.class,
136     org.uddi.vs_v3.ObjectFactory.class,
137     org.uddi.sub_v3.ObjectFactory.class,
138     org.w3._2000._09.xmldsig_.ObjectFactory.class,
139     org.uddi.policy_v3.ObjectFactory.class,
140     org.uddi.policy_v3_instanceparms.ObjectFactory.class
141 })
142 public interface UDDIValueSetCachingPortType extends Remote {
143 
144 
145     /**
146      * <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
147 permission to that registry to cache the valid values for that value set.&nbsp; The
148 external value set provider MAY offer the get_allValidValues Web service and
149 the UDDI node MAY use it.&nbsp; The normal use is to return a full set of valid
150 values for the identified value set.&nbsp; If the value set provider determines
151 there are too many values to return in one chunk, the set of valid values may
152 be returned in chunks.</p>
153 
154 <p class="MsoBodyText">Registry policy may require the value set provider that
155 offers a get_allValidValues Web service to republish its value set tModel when
156 the cache should be re-acquired by participating nodes.&nbsp; See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value Sets</i> for more information.</p>
157 
158 <p class="MsoBodyText">get_allValidValues can similarly be used to obtain the set
159 of tModelKeys for value sets that can participate in a cached category group
160 system.</p>
161 * 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.
162 * 
163 * <h5 style="margin-left:0in;text-indent:0in">Chunking of valid values</h5>
164 
165 <p class="MsoBodyText">If the value set provider determines that there are too
166 many values to be returned in a single group, then the provider SHOULD provide
167 a chunkToken with the results.&nbsp; The chunkToken is a string based token which is
168 used by the value set provider to maintain the state of the set of values for a
169 particular caller, when these results are chunked across multiple responses.&nbsp;
170 Providers should establish their own policies for determining the content and
171 format of the chunkToken. The chunkToken returned with a particular value set
172 result set SHOULD be used to retrieve subsequent results.&nbsp; If no more results
173 are pending, the value of the chunkToken will be "0" or the
174 chunkToken will be absent.&nbsp; </p>
175 
176 <p class="MsoBodyText">A chunkToken is intended as a short-term aid in obtaining
177 contiguous results across multiple API calls and is therefore likely to remain
178 valid for only a short time.&nbsp; Value set providers may establish policies on how
179 long a chunkToken remains valid.</p>
180      * @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.
181      * @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. 
182      * @param validValue RETURN TYPE <p class="MsoBodyText">A validValuesList structure is returned containing the set
183 of valid values for the external category or identifier system.&nbsp; The list MUST
184 contain a chunkToken if the Web service provider wishes to provide the data in
185 packets.&nbsp; The validValuesList has the form: </p>
186 
187 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image106.gif" border="0" height="121" width="393"></p>
188 
189 <p class="MsoBodyText">And its contained validValue element has the form:</p>
190 
191 <p class="MsoBodyText"><img src="http://uddi.org/pubs/uddi-v3.0.2-20041019_files/image107.gif" border="0" height="71" width="347"></p>
192      * @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.
193      * @throws DispositionReportFaultMessage
194      * <p class="MsoBodyText">If any error occurs in processing this API, a dispositionReport structure MUST be returned to the caller in a SOAP Fault.&nbsp; See Section <a href="#_Ref8980008 ">4.8</a> <i>Success and Error Reporting.&nbsp; </i>The following
195 error information is relevant: </p>
196 
197 <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;
198 </span></span><b>E_invalidKeyPassed</b>: Signifies that the tModelKey passed
199 did not match with the uddiKey of any known tModels.&nbsp; The details on the
200 invalid key SHOULD be included in the dispositionReport element.</p>
201 
202 <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;
203 </span></span><b>E_noValuesAvailable</b>: Signifies that no values could be
204 returned. </p>
205 
206 <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;
207 </span></span><b>E_unsupported</b>: Signifies that the Web service does not
208 support this API.</p>
209 
210 <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;
211 </span></span><b>E_invalidValue</b>: Signifies that the chunkToken value
212 supplied is either invalid or has expired.</p>
213      */
214     @WebMethod(operationName = "get_allValidValues", action = "get_allValidValues")
215     @RequestWrapper(localName = "get_allValidValues", targetNamespace = "urn:uddi-org:vscache_v3", className = "org.uddi.vscache_v3.GetAllValidValues")
216     @ResponseWrapper(localName = "validValuesList", targetNamespace = "urn:uddi-org:vscache_v3", className = "org.uddi.vscache_v3.ValidValuesList")
217     public void getAllValidValues(
218         @WebParam(name = "authInfo", targetNamespace = "urn:uddi-org:api_v3")
219         String authInfo,
220         @WebParam(name = "tModelKey", targetNamespace = "urn:uddi-org:api_v3")
221         String tModelKey,
222         @WebParam(name = "chunkToken", targetNamespace = "urn:uddi-org:vscache_v3", mode = WebParam.Mode.INOUT)
223         Holder<String> chunkToken,
224         @WebParam(name = "validValue", targetNamespace = "urn:uddi-org:vscache_v3", mode = WebParam.Mode.OUT)
225         Holder<List<ValidValue>> validValue)
226         throws DispositionReportFaultMessage, RemoteException
227     ;
228 
229 }