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  
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.&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  <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.&nbsp; Registry policy determines which external value sets
75  are supported and how.&nbsp; 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.&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
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.&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
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.&nbsp; 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.&nbsp; See Section <a href="#_Ref9007695 ">9.6.5</a> <i>Value sets</i>
99  for more information<i>.</i>&nbsp; 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.&nbsp; 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.&nbsp; </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.&nbsp; </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.&nbsp; 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.&nbsp; </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.&nbsp; </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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
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.&nbsp; 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 &quot;Times New Roman&quot;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
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 }