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. Similarly, a keyedReferenceGroup 43 element that is involved in a save operation may also be checked to ensure that 44 it is valid. 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. 50 UDDI registries MAY also support external validation. Node and registry 51 policies determine the manner in which validation of references to external 52 value sets is performed. 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. 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. It can do so by 63 caching valid values for those external value sets that allow caching of their 64 values. A node has two normative options for obtaining the set of valid 65 values. 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. This API is described below. 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. Registry policy determines which external value sets 72 are supported and how. 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. 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 "Times New Roman""> 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. 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 "Times New Roman""> 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. 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. See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value sets</i> 96 for more information<i>.</i> 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. 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. </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. </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. 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. </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. The 148 external value set provider MAY offer the get_allValidValues Web service and 149 the UDDI node MAY use it. The normal use is to return a full set of valid 150 values for the identified value set. 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. 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. 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. 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. If no more results 173 are pending, the value of the chunkToken will be "0" or the 174 chunkToken will be absent. </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. 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. The list MUST 184 contain a chunkToken if the Web service provider wishes to provide the data in 185 packets. 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. See Section <a href="#_Ref8980008 ">4.8</a> <i>Success and Error Reporting. </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 "Times New Roman""> 198 </span></span><b>E_invalidKeyPassed</b>: Signifies that the tModelKey passed 199 did not match with the uddiKey of any known tModels. 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 "Times New Roman""> 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 "Times New Roman""> 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 "Times New Roman""> 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 }