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 24 import javax.jws.WebMethod; 25 import javax.jws.WebParam; 26 import javax.jws.WebResult; 27 import javax.jws.WebService; 28 import javax.jws.soap.SOAPBinding; 29 import javax.xml.bind.annotation.XmlSeeAlso; 30 import org.uddi.api_v3.DispositionReport; 31 import org.uddi.vs_v3.ValidateValues; 32 33 34 /** 35 * This portType defines all of the UDDI value set validation 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 <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 70 Value Set Programming Interfaces</a></h3> 71 72 <p class="MsoBodyText">The Application Programming Interfaces in this section 73 represent capabilities that a UDDI registry MAY use to enable validation of 74 references to value sets. Registry policy determines which external value sets 75 are supported and how. See Section <a href="#_Ref9007633 ">9.4.19</a> <i>Value 76 Set Policies </i>and Section <a href="#_Ref9007695 ">9.6.5</a><i>Value Sets </i>for 77 more information on registry support of external value sets. These SOAP messages all behave synchronously.</p> 78 79 <p class="MsoBodyText">The publicly accessible APIs that are used to support 80 external value set validation are:</p> 81 82 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 83 </span></span><a href="#_validate_values"><b><span style="color:windowtext; 84 text-decoration:none">validate_values</span></b></a>: Used by nodes to allow 85 external providers of value set validation Web services to assess whether 86 keyedReferences or keyedReferenceGroups are valid. Returns a dispositionReport 87 structure.</p> 88 89 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 90 </span></span><a href="#_get_allValidValues"><b><span style="color:windowtext; 91 text-decoration:none">get_allValidValues</span></b></a>: Used by nodes that 92 support caching of valid values from cacheable checked value sets to obtain the 93 set of valid values. Returns an empty message or a dispositionReport structure.</p> 94 95 <p class="MsoBodyText">Registry policy may require value set providers that offer 96 one of these Web services to publish the bindingTemplate for the service and 97 the tModel for the value set in a particular way so that the proper Web service 98 can be discovered. See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value sets</i> 99 for more information<i>.</i> When a value set provider offers one of these Web 100 services, a tModel for the checked value set SHOULD be published in any 101 registry the provider wishes to offer it, and a bindingTemplate SHOULD be 102 published for the Web service(s) the value set provider offers for the checked 103 value set. The tModel SHOULD have categorizations from the uddi-org:types 104 category system to indicate the type of value set (<i>categorization</i>, <i>identifier</i>, 105 <i>relationship</i>, <i>categorizationGroup</i>), that it is checked (<i>checked</i>), 106 and, if the value set provider allows validation to occur against node caches 107 of valid values, the <i>cacheable</i> categorization should also be provided. </p> 108 109 <p class="MsoBodyText">In order for a value set to be considered checked, the 110 tModel MUST first be categorized with the checked value from the uddi-org:types 111 category system. The decision to check such value sets is a registry and node 112 policy decision. </p> 113 114 <p class="MsoBodyText">If a value set tModel is categorized as checked, then in 115 response to attempts to publish a keyedReference which uses the checked tModel, 116 nodes MUST either perform the required validation, or return E_unsupported.</p> 117 118 <p class="MsoBodyText">The tModel should also have a categorization reference to 119 the bindingTemplate of the get_allValidValues or validate_values Web service 120 that the value set provider designates, using the uddi-org:validatedBy category 121 system. See Section <a href="#_Ref8977125 ">11.1.1</a> <i>UDDI Types Category 122 System </i>and Section <a href="# ">11.1.7</a> <i>Validated By Category System</i> 123 for more information.</p> 124 125 <p class="MsoBodyText">The bindingTemplate for the get_allValidValues or the 126 validate_values Web service SHOULD reference in its tModelInstanceDetails the 127 appropriate value set API tModel (Section <a href="#_Ref8979902 ">11.2.7</a> <i>Value 128 Set Caching API tModel </i>or Section <a href="#_Ref8979938 ">11.2.8</a> <i>Value 129 Set Validation API tModel</i>) as well tModels for all of the value sets the 130 service applies to. </p> 131 * 132 */ 133 @WebService(name = "UDDI_ValueSetValidation_PortType", targetNamespace = "urn:uddi-org:api_v3_portType") 134 @XmlSeeAlso({ 135 org.uddi.custody_v3.ObjectFactory.class, 136 org.uddi.repl_v3.ObjectFactory.class, 137 org.uddi.subr_v3.ObjectFactory.class, 138 org.uddi.api_v3.ObjectFactory.class, 139 org.uddi.vscache_v3.ObjectFactory.class, 140 org.uddi.vs_v3.ObjectFactory.class, 141 org.uddi.sub_v3.ObjectFactory.class, 142 org.w3._2000._09.xmldsig_.ObjectFactory.class, 143 org.uddi.policy_v3.ObjectFactory.class, 144 org.uddi.policy_v3_instanceparms.ObjectFactory.class 145 }) 146 public interface UDDIValueSetValidationPortType extends Remote{ 147 148 149 /** 150 * 151 * <p class="MsoBodyText">A UDDI node that supports external validation sends the 152 validate_values API to the appropriate external Web service, of which there is 153 exactly one, whenever a publisher saves data that uses a keyedReference or 154 keyedReferenceGroup whose use is regulated by the external party who controls 155 that Web service. For purposes of discussion, the identifier, category, and 156 relationship type systems that the keyedReference elements refer to are called 157 checked value sets. The category group systems that the keyedReferenceGroup 158 elements refer to are similarly called checked category group systems. </p> 159 160 <p class="MsoBodyText">The normal use for checked value sets is to verify that 161 specific values (checking the keyValue attribute of values supplied) exist 162 within the value set. For certain value sets the value set provider may 163 further restrict the use of a value based on a contextual evaluation of the 164 passed data. The provider may do enable this contextual checking by offering a 165 validation Web service.</p> 166 167 <p class="MsoBodyText">Validation algorithms for checked category group systems 168 similarly verify that the contents of the keyedReferenceGroup elements form a 169 valid set according to the validation algorithm for the checked category group 170 system. Frequently such validation ensures that the value sets identified in 171 contained keyedReferences are allowed to participate in the category group 172 system.</p> 173 * 174 * @param body 175 * 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. 176 177 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. 178 * 179 * <p class="MsoBodyText">The called Web service for a checked value set performs 180 validation on all of the keyedReferences or keyedReferenceGroups that are 181 associated with the value sets the Web service is authorized to check. This 182 can involve merely checking that the <i>keyValue</i> values supplied are good for 183 the given value set (as signified by the embedded keyedReference tModelKey 184 values). Other types of validation as desired may be performed, including 185 context sensitive checks that utilize the information passed in the entity 186 being saved.</p> 187 188 <p class="MsoBodyText">The entity being saved may contain multiple references to 189 values from the value set(s) that the validation Web service is authorized to 190 validate. When the entity being saved is a businessEntity, contained 191 businessService and bindingTemplate entities may themselves reference values 192 from the authorized value sets as well. All references to values that are 193 associated with the value set(s) that the validation Web service is authorized 194 to check MUST be validated without regard to their placement in the entity 195 being saved.</p> 196 197 <p class="MsoBodyText">If the external value set and the node both support 198 caching of valid values, the node may not invoke validate_values if it already 199 knows that the referenced values are valid, through checking its cache.</p> 200 201 <p class="MsoBodyText">A checked category group system is treated in the same manner 202 as a checked value set. The tModelKey associated with the keyedReferenceGroup 203 identifies the checked category group system. A node may be able to validate a 204 reference to a cacheable checked category group system without calling 205 validate_values if it can determine using its cache that the tModelKey 206 attributes from the keyedReference elements contained in the 207 keyedReferenceGroup are allowed for the category group system.</p> 208 * @return 209 * returns org.uddi.api_v3.DispositionReport 210 * 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. 211 * @throws DispositionReportFaultMessage, RemoteException 212 * <p class="MsoBodyText">If any error is found, or the called Web service needs to 213 signal that the information being saved is not valid based on the validation 214 algorithm chosen by the external Web service provider, then the Web service 215 MUST raise a SOAP Fault as specified in Section <a href="#_Ref8979985 ">4.8</a> 216 <i>Success and Error Reporting.</i></p> 217 218 <p class="MsoBodyText">When an error is signaled in this fashion, the UDDI node MUST 219 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 220 following reasons, and the error text clearly indicates the keyedReference or 221 keyedReferenceGroup data that is being rejected and the reason it is being 222 rejected.</p> 223 224 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 225 </span></span><b>E_invalidValue</b>: One or more of the keyValues in the 226 keyedReference or keyedReferences in the keyedReferenceGroup supplied failed 227 validation. Only the first error encountered need be reported.</p> 228 229 <p class="MsoBodyText" style="margin-left:1.0in;text-indent:-.25in"><span style="font-family:Symbol">·<span style="font:7.0pt "Times New Roman""> 230 </span></span><b>E_valueNotAllowed</b>: The values may be valid, but are not 231 allowed contextually.</p> 232 */ 233 @WebMethod(operationName = "validate_values", action = "validate_values") 234 @WebResult(name = "dispositionReport", targetNamespace = "urn:uddi-org:api_v3", partName = "body") 235 @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) 236 public DispositionReport validateValues( 237 @WebParam(name = "validate_values", targetNamespace = "urn:uddi-org:vs_v3", partName = "body") 238 ValidateValues body) 239 throws DispositionReportFaultMessage, RemoteException 240 ; 241 242 }