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.api_v3; 20 21 import java.io.Serializable; 22 23 import javax.xml.bind.annotation.XmlAccessType; 24 import javax.xml.bind.annotation.XmlAccessorType; 25 import javax.xml.bind.annotation.XmlAttribute; 26 import javax.xml.bind.annotation.XmlTransient; 27 import javax.xml.bind.annotation.XmlType; 28 import javax.xml.bind.annotation.XmlValue; 29 import org.apache.juddi.api_v3.AccessPointType; 30 31 32 /** 33 * <div style="border:none;border-top:solid #333399 1.0pt;padding:1.0pt 0in 0in 0in"><p class="AppH1" style="margin-left:0in;text-indent:0in"><a name="_Toc8974358">B<span style="font:7.0pt "Times New Roman""> 34 </span>Appendix B: Using and Extending the useType Attribute</a></p> 35 36 </div> 37 38 <p class="MsoBodyText">UDDI provides type information through the useType 39 attribute on the following UDDI elements: accessPoint, overviewURL, 40 discoveryURL, contact, address, email and phone. The useType attribute is 41 intended to provide information on how to use or invoke the resource contained 42 within the element. This Appendix establishes and explains common values and 43 conventions for the useType attribute in the context of certain elements, as 44 well as a model for establishing new common values and conventions.</p> 45 46 <p class="AppH2" style="margin-left:0in;text-indent:0in"><a name="_Toc85908385"></a><a name="_Toc53709543"></a><a name="_Toc45096631"></a><a name="_Toc45096173"></a><a name="_Toc42047544"></a><a name="_Toc8974359">B.1<span style="font:7.0pt "Times New Roman""> 47 </span>accessPoint</a></p> 48 49 <p class="MsoBodyText">Four common values for providing type information about 50 the accessPoint are: "endPoint", "wsdlDeployment", "bindingTemplate", 51 and "hostingRedirector.</p> 52 53 <p class="AppH3" style="margin-left:0in;text-indent:0in"><a name="_Toc85908386"></a><a name="_Toc53709544"></a><a name="_Toc45096632"></a><a name="_Toc45096174"></a><a name="_Toc42047545">B.1.1<span style="font:7.0pt "Times New Roman""> 54 </span>Using the "endPoint" value</a></p> 55 56 <p class="MsoBodyText">Typically, the network address of a Web service described 57 by a bindingTemplate is found in the accessPoint element. This common behavior 58 is denoted by using the string "endpoint" as the value of the 59 accessPoint. Decorating an accessPoint with a useType="endPoint" 60 signifies that a user or application can invoke a Web service at that address. 61 A sample of such behavior is as follows:</p> 62 63 <p class="codeSample"><bindingTemplate 64 bindingKey="uddi:example.org:catalog"><br> 65 <description xml:lang="en"><br> 66 Browse catalog Web service<br> 67 </description><br> 68 <accessPoint useType="endPoint"><br> 69 http://www.example.org/CatalogWebService<br>; 70 </accessPoint><br> 71 <tModelInstanceDetails><br> 72 <tModelInstanceInfo 73 tModelKey="uddi:example.org:catalog_interface"/><br> 74 <tModelInstanceInfo 75 tModelKey="uddi:uddi.org:transport:http"/><br> 76 </tModelInstanceDetails><br> 77 </bindingTemplate></p> 78 79 <p class="codeSample"> </p> 80 81 <p class="MsoBodyText">In the example above, a client would be able to parse the 82 bindingTemplate and discover the end point of the Web service itself. However, 83 the information about how to invoke that Web service would be modeled using 84 tModels. All interface information about that service would be represented by 85 the tModelInstanceInfo structures contained as children of the bindingTemplate.</p> 86 87 <p class="MsoBodyText">The client knows the transport of the accessPoint either 88 by checking to see if a protocol tModel has been associated with the 89 bindingTemplate or inspecting the URI prefix. In the example above, the http 90 transport was used, denoted by the tModelInstanceInfo.</p> 91 92 <span style="font-size:10.0pt;font-family:Arial;letter-spacing:-.25pt"><br style="page-break-before:always" clear="all"> 93 </span> 94 95 <p class="MsoBodyText"> </p> 96 97 <p class="MsoBodyText">UDDI RECOMMENDS that endpoints for phone, fax and modem 98 communication follow the guidelines outlined in RFC 2806 <i>URLs for Telephone 99 Calls</i><a href="#_ftn51" name="_ftnref51" title=""><span class="MsoFootnoteReference"><span class="MsoFootnoteReference"><span style="font-size:10.0pt;letter-spacing:-.25pt">[51]</span></span></span></a>. 100 Following such a convention for a phone number accessPoint would result in the 101 following bindingTemplate sample:</p> 102 103 <p class="codeSample"><bindingTemplate 104 bindingKey="uddi:example.org:catalog"><br> 105 <description xml:lang="en"><br> 106 Browse catalog Web service<br> 107 </description><br> 108 <accessPoint useType="endPoint"><br> 109 tel:+1-512-555-1212<br> 110 </accessPoint><br> 111 <tModelInstanceDetails><br> 112 <tModelInstanceInfo 113 tModelKey="uddi:uddi.org:transport:telephone"/><br> 114 </tModelInstanceDetails><br> 115 </bindingTemplate></p> 116 117 <p class="MsoBodyText"> </p> 118 119 <p class="AppH3" style="margin-left:0in;text-indent:0in"><a name="_Toc85908387"></a><a name="_Toc53709545"></a><a name="_Toc45096633"></a><a name="_Toc45096175"></a><a name="_Toc42047546">B.1.2<span style="font:7.0pt "Times New Roman""> 120 </span>Using the "wsdlDeployment" value</a></p> 121 122 <p class="MsoBodyText">Instead of directly providing the network address in the accessPoint, 123 it is occasionally useful or necessary to provide this information through 124 indirect means. One common scenario for such a behavior is when the 125 accessPoint is embedded within a WSDL file. In such a scenario, the UDDI 126 accessPoint contains the address of the WSDL file, and the client then must 127 retrieve the WSDL file and extract the end point address from the WSDL file 128 itself.</p> 129 130 <p class="MsoBodyText">In this case, decorating the UDDI accessPoint with a 131 useType="wsdlDeployment" is appropriate. A sample of such behavior is 132 as follows:</p> 133 134 <p class="codeSample"><bindingTemplate 135 bindingKey="uddi:example.org:catalog"><br> 136 <description xml:lang="en"><br> 137 Browse catalog Web service<br> 138 </description><br> 139 <accessPoint useType="wsdlDeployment"><br> 140 http://www.example.org/CatalogWebService/catalog.wsdl<br>; 141 </accessPoint></p> 142 143 <p class="codeSample"> <categoryBag><br> 144 <keyedReference keyName="uddi-org:types:wsdl"<br> 145 keyValue="wsdlDeployment" <br> 146 147 tModelKey="uddi:uddi.org:categorization:types"/> <br> 148 </categoryBag><br> 149 </bindingTemplate></p> 150 151 <p class="codeSample"> </p> 152 153 <p class="MsoBodyText">In the example above, a client would be able to parse the 154 result of the bindingTemplate and determine the end point of the Web service 155 within the WSDL file discovered in the accessPoint element. Note that the 156 bindingTemplate has also been categorized with the "wsdlDeployment" 157 value from the uddi.org:categorization:types scheme so that it can be 158 discovered through a find_binding API call.</p> 159 160 <p class="AppH3" style="margin-left:0in;text-indent:0in"><a name="_Toc85908388"></a><a name="_Toc53709546"></a><a name="_Toc45096634"></a><a name="_Toc45096176"></a><a name="_Toc42047547">B.1.3<span style="font:7.0pt "Times New Roman""> 161 </span>Using the "bindingTemplate" value</a></p> 162 163 <p class="MsoBodyText">Another form of indirection uses UDDI itself to discover 164 the location of the final end point. Categorizing a bindingTemplate with 165 either "bindingTemplate" or "hostingRedirector" specifies 166 that the accessPoint contains a bindingKey intended to be used in a 167 get_bindingDetail API call to a UDDI registry Inquiry API Set. How the 168 resultant bindingTemplate is interpreted depends on which one of the two 169 methods described below is used. In the case of "bindingTemplate", a 170 bindingKey refers to another binding within the same UDDI registry.</p> 171 172 <p class="MsoBodyText">For example, suppose tempuri.com, the well known but 173 fictitious maker of crispy batter coating for fried foods, contracts with the 174 equally fictitious Web service hosting company ws-o-rama.com to host tempuri’s 175 Web service that exposes its product catalog. Tempuri.com wishes to publish a 176 bindingTemplate for this service in the UDDI Business Registry, but wishes to 177 leave the details of the technical implementation and its description up to 178 ws-o-rama.com who may wish to change them over time. To do this, tempuri.com 179 and ws-o-rama.com use bindingTemplate indirection. In the UDDI Business 180 Registry the bindingTemplate in tempuri’s businessEntity that describes this 181 service appears as follows:</p> 182 183 <p class="codeSample"><bindingTemplate 184 bindingKey="uddi:tempuri.com:catalog"><br> 185 <description xml:lang="en"><br> 186 Browse catalog Web service<br> 187 </description><br> 188 <accessPoint useType="bindingTemplate"><br> 189 uddi:ws-o-rama.com:tempuri:bt1<br> 190 </accessPoint><br> 191 </bindingTemplate></p> 192 193 <p class="codeSample"> </p> 194 195 <p class="MsoBodyText">Here, the bindingTemplate describing tempuri’s catalog 196 browsing Web service uses an accessPoint to refer to the bindingTemplate (also 197 in the UDDI Business Registry) whose bindingKey is uddi:ws-o-rama.com:tempura:bt1. 198 When a client does a get_bindingDetail asking for the bindingTemplate with that 199 key, the following bindingTemplate is returned:</p> 200 201 <p class="codeSample"><bindingTemplate 202 bindingKey="uddi:ws-o-rama.com:tempuri:bt1"><br> 203 <description xml:lang="en"><br> 204 Tempuri.com’s catalog browsing service hosted by ws-o-rama<br> 205 </description><br> 206 <accessPoint useType="endPoint"><br> 207 http://sf1.ws-o-rama.com/tempuri/catalog/<br>; 208 </accessPoint><br> 209 <tModelInstanceDetails><br> 210 <tModelInstanceInfo tModelKey="uddi:..."/><br> 211 </tModelInstanceDetails><br> 212 </bindingTemplate></p> 213 214 <p class="MsoBodyText"> </p> 215 216 <p class="MsoBodyText">This bindingTemplate describes the actual Web service that 217 is to be used.</p> 218 219 <p class="AppH3" style="margin-left:0in;text-indent:0in"><a name="_Toc85908389"></a><a name="_Toc53709547"></a><a name="_Toc45096635"></a><a name="_Toc45096177"></a><a name="_Toc42047548">B.1.4<span style="font:7.0pt "Times New Roman""> 220 </span>Using the "hostingRedirector" value</a></p> 221 222 <p class="MsoBodyText">It may be necessary to "hide" the network 223 address of a Web service from unauthorized access. In this case, a useType="hostingRedirector" 224 can be used to indicate that the client must follow a longer path of 225 indirection to retrieve the accessPoint. In the bindingTemplate, the client 226 will discover a bindingKey, which will lead to a bindingTemplate that contains 227 the end point for a Web service which supports the UDDI get_bindingDetail Web 228 Service. The client will then be able to re-issue the get_bindingDetail 229 message with the original key, presumably with authentication, to this other 230 Web service. Such an indirection mechanism allows a Web service to be 231 discoverable but not accessible from a given node. </p> 232 233 <p class="MsoBodyText">For example, tempuri.com uses ws-o-rama.com to host more 234 than just its publicly visible catalog browsing service. In particular it has a 235 number of services it does not wish to expose fully in the UDDI Business 236 Registry. Instead, it wishes to keep their full definition in its private UDDI 237 registry, which ws-o-rama.com also happens to host, and supply the end points 238 to these Web services only to authorized inquirers. </p> 239 240 <p class="MsoBodyText">In particular, tempuri has a Web service that its 241 suppliers use to bill it for goods they deliver. In the UDDI Business Registry, 242 tempuri publishes the following bindingTemplate, which contains a bindingKey.</p> 243 244 <p class="codeSample"><bindingTemplate 245 bindingKey="uddi:tempuri.com:billing"><br> 246 <description xml:lang="en"><br> 247 Tempuri supplier billing Web service<br> 248 </description><br> 249 <accessPoint useType="hostingRedirector"><br> 250 uddi:ws-o-rama.com:tempuri:bt47<br> 251 </accessPoint><br> 252 </bindingTemplate></p> 253 254 <p class="MsoBodyText"> </p> 255 256 <p class="MsoBodyText">Here, the bindingTemplate describing tempuri’s supplier 257 billing Web service uses an accessPoint to refer to the bindingTemplate (also 258 in the UDDI Business Registry) whose bindingKey is uddi:ws-o-rama.com: tempuri:bt47. 259 Note that the useType equals "hostingRedirector" which indicates that 260 the bindingKey refers to a hostingRedirector service. When a client does a 261 get_bindingDetail (on the UDDI Business Registry) asking for the 262 bindingTemplate with that key, the following indirect bindingTemplate is 263 returned: </p> 264 265 <p class="codeSample"><bindingTemplate 266 bindingKey="uddi:ws-o-rama.com:tempura:bt47"><br> 267 <description xml:lang="en"><br> 268 Hosting Redirector Service for Tempuri.com<br> 269 hosted by ws-o-rama.com<br> 270 </description><br> 271 <accessPoint useType="endPoint"><br> 272 http://sf1.ws-o-rama.com/tempuri/uddi/inquiry<br>; 273 </accessPoint><br> 274 <tModelInstanceDetails><br> 275 <tModelInstanceInfo <br> 276 tModelKey="uddi:uddi.org:specification:hostingredirector"/><br> 277 </tModelInstanceDetails><br> 278 </bindingTemplate></p> 279 280 <p class="codeSample"> </p> 281 282 <p class="MsoBodyText">This bindingTemplate describes the hosting redirector Web 283 service hosted for tempuri.com by ws-o-rama.com. By definition, it responds to 284 the get_bindingDetail API call using SOAP over HTTP. The description in the 285 bindingTemplate says it responds only to authorized requests. For authorized 286 clients, invoking get_bindingDetail, passing the key of the original 287 bindingTemplate (uddi:tempuri.com:billing) retrieves the following 288 bindingTemplate:</p> 289 290 <p class="codeSample"><bindingTemplate 291 bindingKey="uddi:tempuri.com:billing"><br> 292 <description xml:lang="en"><br> 293 Tempuri.com’s supplier billing browsing service<br> 294 hosted by ws-o-rama.com<br> 295 </description><br> 296 <accessPoint useType="endPoint"><br> 297 http:sf1.ws-o-rama.com/tempuri/billing/<br> 298 </accessPoint><br> 299 <tModelInstanceDetails><br> 300 <tModelInstanceInfo tModelKey="uddi:..."/><br> 301 </tModelInstanceDetails><br> 302 </bindingTemplate></p> 303 304 <p class="MsoBodyText"> </p> 305 306 <p class="MsoBodyText">This bindingTemplate describes the actual Web service that 307 is to be used.</p> 308 * <p>Java class for accessPoint complex type.</p> 309 * 310 * 311 * <p>The following schema fragment specifies the expected content contained within this class.</p> 312 * 313 * <pre> 314 * <complexType name="accessPoint"> 315 * <simpleContent> 316 * <extension base="<urn:uddi-org:api_v3>validationTypeString4096"> 317 * <attribute name="useType" type="{urn:uddi-org:api_v3}useType" default="" /> 318 * </extension> 319 * </simpleContent> 320 * </complexType> 321 * </pre> 322 * 323 * 324 */ 325 @XmlAccessorType(XmlAccessType.FIELD) 326 @XmlType(name = "accessPoint", propOrder = { 327 "value" 328 }) 329 public class AccessPoint implements Serializable { 330 331 @XmlTransient 332 private static final long serialVersionUID = -6377843530866292358L; 333 334 @XmlValue 335 protected String value; 336 @XmlAttribute 337 protected String useType; 338 public AccessPoint() 339 {} 340 /** 341 * A convenience constructor<br> 342 *@see org.apache.juddi.api_v3.AccessPointType for help on useType 343 * @param value 344 * @param useType 345 */ 346 public AccessPoint(String value, String useType) 347 { 348 this.value = value; 349 this.useType = useType; 350 } 351 /** 352 * Gets the value of the value property. 353 * 354 * @return 355 * possible object is 356 * {@link String } 357 * 358 */ 359 public String getValue() { 360 return value; 361 } 362 363 /** 364 * Sets the value of the value property. 365 * 366 * @param value 367 * allowed object is 368 * {@link String } 369 * @see AccessPointType for spec defined values 370 */ 371 public void setValue(String value) { 372 this.value = value; 373 } 374 375 /** 376 * Gets the value of the useType property. 377 * 378 * @return 379 * possible object is 380 * {@link String } 381 * 382 * @see AccessPointType for spec defined values 383 */ 384 public String getUseType() { 385 if (useType == null) { 386 return ""; 387 } else { 388 return useType; 389 } 390 } 391 392 /** 393 * Sets the value of the useType property. 394 * 395 * @param value 396 * allowed object is 397 * {@link String } 398 * 399 */ 400 public void setUseType(String value) { 401 this.useType = value; 402 } 403 404 }