Author: alexoree
Date: Wed May 15 22:55:08 2013
New Revision: 1483119
URL: http://svn.apache.org/r1483119
Log:
Adding some additional javadoc to the AccessPoint
Modified:
juddi/trunk/uddi-ws/src/main/java/org/uddi/api_v3/AccessPoint.java
Modified: juddi/trunk/uddi-ws/src/main/java/org/uddi/api_v3/AccessPoint.java
URL:
http://svn.apache.org/viewvc/juddi/trunk/uddi-ws/src/main/java/org/uddi/api_v3/AccessPoint.java?rev=1483119&r1=1483118&r2=1483119&view=diff
==============================================================================
--- juddi/trunk/uddi-ws/src/main/java/org/uddi/api_v3/AccessPoint.java
(original)
+++ juddi/trunk/uddi-ws/src/main/java/org/uddi/api_v3/AccessPoint.java Wed May
15 22:55:08 2013
@@ -29,9 +29,285 @@ import javax.xml.bind.annotation.XmlValu
/**
- * <p>Java class for accessPoint complex type.
+ * <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"">
+</span>Appendix B: Using and Extending the useType Attribute</a></p>
+
+</div>
+
+<p class="MsoBodyText">UDDI provides type information through the useType
+attribute on the following UDDI elements: accessPoint, overviewURL,
+discoveryURL, contact, address, email and phone. The useType attribute is
+intended to provide information on how to use or invoke the resource contained
+within the element. This Appendix establishes and explains common values
and
+conventions for the useType attribute in the context of certain elements, as
+well as a model for establishing new common values and conventions.</p>
+
+<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"">
+</span>accessPoint</a></p>
+
+<p class="MsoBodyText">Four common values for providing type information about
+the accessPoint are: "endPoint", "wsdlDeployment", "bindingTemplate",
+and "hostingRedirector.</p>
+
+<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"">
+</span>Using the "endPoint" value</a></p>
+
+<p class="MsoBodyText">Typically, the network address of a Web service
described
+by a bindingTemplate is found in the accessPoint element. This common
behavior
+is denoted by using the string "endpoint" as the value of the
+accessPoint. Decorating an accessPoint with a useType="endPoint"
+signifies that a user or application can invoke a Web service at that
address.
+A sample of such behavior is as follows:</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:example.org:catalog"><br>
+ <description xml:lang="en"><br>
+ Browse catalog Web service<br>
+ </description><br>
+ <accessPoint useType="endPoint"><br>
+
http://www.example.org/CatalogWebService<br>
+ </accessPoint><br>
+ <tModelInstanceDetails><br>
+ <tModelInstanceInfo
+tModelKey="uddi:example.org:catalog_interface"/><br>
+ <tModelInstanceInfo
+tModelKey="uddi:uddi.org:transport:http"/><br>
+ </tModelInstanceDetails><br>
+</bindingTemplate></p>
+
+<p class="codeSample"> </p>
+
+<p class="MsoBodyText">In the example above, a client would be able to parse
the
+bindingTemplate and discover the end point of the Web service itself.
However,
+the information about how to invoke that Web service would be modeled using
+tModels. All interface information about that service would be
represented by
+the tModelInstanceInfo structures contained as children of the
bindingTemplate.</p>
+
+<p class="MsoBodyText">The client knows the transport of the accessPoint either
+by checking to see if a protocol tModel has been associated with the
+bindingTemplate or inspecting the URI prefix. In the example above, the
http
+transport was used, denoted by the tModelInstanceInfo.</p>
+
+<span style="font-size:10.0pt;font-family:Arial;letter-spacing:-.25pt"><br
style="page-break-before:always" clear="all">
+</span>
+
+<p class="MsoBodyText"> </p>
+
+<p class="MsoBodyText">UDDI RECOMMENDS that endpoints for phone, fax and modem
+communication follow the guidelines outlined in RFC 2806 <i>URLs for Telephone
+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>.
+Following such a convention for a phone number accessPoint would result in the
+following bindingTemplate sample:</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:example.org:catalog"><br>
+ <description xml:lang="en"><br>
+ Browse catalog Web service<br>
+ </description><br>
+ <accessPoint useType="endPoint"><br>
+ tel:+1-512-555-1212<br>
+ </accessPoint><br>
+ <tModelInstanceDetails><br>
+ <tModelInstanceInfo
+tModelKey="uddi:uddi.org:transport:telephone"/><br>
+ </tModelInstanceDetails><br>
+</bindingTemplate></p>
+
+<p class="MsoBodyText"> </p>
+
+<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"">
+</span>Using the "wsdlDeployment" value</a></p>
+
+<p class="MsoBodyText">Instead of directly providing the network address in
the accessPoint,
+it is occasionally useful or necessary to provide this information through
+indirect means. One common scenario for such a behavior is when the
+accessPoint is embedded within a WSDL file. In such a scenario, the UDDI
+accessPoint contains the address of the WSDL file, and the client then must
+retrieve the WSDL file and extract the end point address from the WSDL file
+itself.</p>
+
+<p class="MsoBodyText">In this case, decorating the UDDI accessPoint with a
+useType="wsdlDeployment" is appropriate. A sample of such behavior is
+as follows:</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:example.org:catalog"><br>
+ <description xml:lang="en"><br>
+ Browse catalog Web service<br>
+ </description><br>
+ <accessPoint useType="wsdlDeployment"><br>
+
http://www.example.org/CatalogWebService/catalog.wsdl<br>
+ </accessPoint></p>
+
+<p class="codeSample"> <categoryBag><br>
+ <keyedReference
keyName="uddi-org:types:wsdl"<br>
+ keyValue="wsdlDeployment" <br>
+
+tModelKey="uddi:uddi.org:categorization:types"/> <br>
+ </categoryBag><br>
+</bindingTemplate></p>
+
+<p class="codeSample"> </p>
+
+<p class="MsoBodyText">In the example above, a client would be able to parse
the
+result of the bindingTemplate and determine the end point of the Web service
+within the WSDL file discovered in the accessPoint element. Note that the
+bindingTemplate has also been categorized with the "wsdlDeployment"
+value from the uddi.org:categorization:types scheme so that it can be
+discovered through a find_binding API call.</p>
+
+<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"">
+</span>Using the "bindingTemplate" value</a></p>
+
+<p class="MsoBodyText">Another form of indirection uses UDDI itself to discover
+the location of the final end point. Categorizing a bindingTemplate with
+either "bindingTemplate" or "hostingRedirector" specifies
+that the accessPoint contains a bindingKey intended to be used in a
+get_bindingDetail API call to a UDDI registry Inquiry API Set. How the
+resultant bindingTemplate is interpreted depends on which one of the two
+methods described below is used. In the case of "bindingTemplate", a
+bindingKey refers to another binding within the same UDDI registry.</p>
+
+<p class="MsoBodyText">For example, suppose tempuri.com, the well known but
+fictitious maker of crispy batter coating for fried foods, contracts with the
+equally fictitious Web service hosting company ws-o-rama.com to host
tempuriâs
+Web service that exposes its product catalog. Tempuri.com wishes to publish a
+bindingTemplate for this service in the UDDI Business Registry, but wishes to
+leave the details of the technical implementation and its description up to
+ws-o-rama.com who may wish to change them over time. To do this, tempuri.com
+and ws-o-rama.com use bindingTemplate indirection. In the UDDI Business
+Registry the bindingTemplate in tempuriâs businessEntity that describes this
+service appears as follows:</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:tempuri.com:catalog"><br>
+ <description xml:lang="en"><br>
+ Browse catalog Web service<br>
+ </description><br>
+ <accessPoint useType="bindingTemplate"><br>
+ uddi:ws-o-rama.com:tempuri:bt1<br>
+ </accessPoint><br>
+</bindingTemplate></p>
+
+<p class="codeSample"> </p>
+
+<p class="MsoBodyText">Here, the bindingTemplate describing tempuriâs catalog
+browsing Web service uses an accessPoint to refer to the bindingTemplate (also
+in the UDDI Business Registry) whose bindingKey is
uddi:ws-o-rama.com:tempura:bt1.
+When a client does a get_bindingDetail asking for the bindingTemplate with that
+key, the following bindingTemplate is returned:</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:ws-o-rama.com:tempuri:bt1"><br>
+ <description xml:lang="en"><br>
+ Tempuri.comâs catalog browsing service
hosted by ws-o-rama<br>
+ </description><br>
+ <accessPoint useType="endPoint"><br>
+
http://sf1.ws-o-rama.com/tempuri/catalog/<br>
+ </accessPoint><br>
+ <tModelInstanceDetails><br>
+ <tModelInstanceInfo
tModelKey="uddi:..."/><br>
+ </tModelInstanceDetails><br>
+</bindingTemplate></p>
+
+<p class="MsoBodyText"> </p>
+
+<p class="MsoBodyText">This bindingTemplate describes the actual Web service
that
+is to be used.</p>
+
+<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"">
+</span>Using the "hostingRedirector" value</a></p>
+
+<p class="MsoBodyText">It may be necessary to "hide" the network
+address of a Web service from unauthorized access. In this case, a
useType="hostingRedirector"
+can be used to indicate that the client must follow a longer path of
+indirection to retrieve the accessPoint. In the bindingTemplate, the
client
+will discover a bindingKey, which will lead to a bindingTemplate that contains
+the end point for a Web service which supports the UDDI get_bindingDetail Web
+Service. The client will then be able to re-issue the get_bindingDetail
+message with the original key, presumably with authentication, to this other
+Web service. Such an indirection mechanism allows a Web service to be
+discoverable but not accessible from a given node. </p>
+
+<p class="MsoBodyText">For example, tempuri.com uses ws-o-rama.com to host more
+than just its publicly visible catalog browsing service. In particular it has a
+number of services it does not wish to expose fully in the UDDI Business
+Registry. Instead, it wishes to keep their full definition in its private UDDI
+registry, which ws-o-rama.com also happens to host, and supply the end points
+to these Web services only to authorized inquirers. </p>
+
+<p class="MsoBodyText">In particular, tempuri has a Web service that its
+suppliers use to bill it for goods they deliver. In the UDDI Business Registry,
+tempuri publishes the following bindingTemplate, which contains a
bindingKey.</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:tempuri.com:billing"><br>
+ <description xml:lang="en"><br>
+ Tempuri supplier billing Web service<br>
+ </description><br>
+ <accessPoint useType="hostingRedirector"><br>
+ uddi:ws-o-rama.com:tempuri:bt47<br>
+ </accessPoint><br>
+</bindingTemplate></p>
+
+<p class="MsoBodyText"> </p>
+
+<p class="MsoBodyText">Here, the bindingTemplate describing tempuriâs
supplier
+billing Web service uses an accessPoint to refer to the bindingTemplate (also
+in the UDDI Business Registry) whose bindingKey is uddi:ws-o-rama.com:
tempuri:bt47.
+Note that the useType equals "hostingRedirector" which indicates that
+the bindingKey refers to a hostingRedirector service. When a client does a
+get_bindingDetail (on the UDDI Business Registry) asking for the
+bindingTemplate with that key, the following indirect bindingTemplate is
+returned: </p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:ws-o-rama.com:tempura:bt47"><br>
+ <description xml:lang="en"><br>
+ Hosting Redirector Service for
Tempuri.com<br>
+ hosted by ws-o-rama.com<br>
+ </description><br>
+ <accessPoint useType="endPoint"><br>
+
http://sf1.ws-o-rama.com/tempuri/uddi/inquiry<br>
+ </accessPoint><br>
+ <tModelInstanceDetails><br>
+ <tModelInstanceInfo <br>
+
tModelKey="uddi:uddi.org:specification:hostingredirector"/><br>
+ </tModelInstanceDetails><br>
+</bindingTemplate></p>
+
+<p class="codeSample"> </p>
+
+<p class="MsoBodyText">This bindingTemplate describes the hosting redirector
Web
+service hosted for tempuri.com by ws-o-rama.com. By definition, it responds to
+the get_bindingDetail API call using SOAP over HTTP. The description in the
+bindingTemplate says it responds only to authorized requests. For authorized
+clients, invoking get_bindingDetail, passing the key of the original
+bindingTemplate (uddi:tempuri.com:billing) retrieves the following
+bindingTemplate:</p>
+
+<p class="codeSample"><bindingTemplate
+bindingKey="uddi:tempuri.com:billing"><br>
+ <description xml:lang="en"><br>
+ Tempuri.comâs supplier billing browsing
service<br>
+ hosted by ws-o-rama.com<br>
+ </description><br>
+ <accessPoint useType="endPoint"><br>
+
http:sf1.ws-o-rama.com/tempuri/billing/<br>
+ </accessPoint><br>
+ <tModelInstanceDetails><br>
+ <tModelInstanceInfo
tModelKey="uddi:..."/><br>
+ </tModelInstanceDetails><br>
+</bindingTemplate></p>
+
+<p class="MsoBodyText"> </p>
+
+<p class="MsoBodyText">This bindingTemplate describes the actual Web service
that
+is to be used.</p>
+ * <p>Java class for accessPoint complex type.</p>
+ *
*
- * <p>The following schema fragment specifies the expected content contained
within this class.
+ * <p>The following schema fragment specifies the expected content contained
within this class.</p>
*
* <pre>
* <complexType name="accessPoint">
@@ -58,7 +334,19 @@ public class AccessPoint implements Seri
protected String value;
@XmlAttribute
protected String useType;
-
+ public AccessPoint()
+ {}
+ /**
+ * A convenience constructor<br>
+ *@see org.apache.juddi.api_v3.AccessPointType for help on useType
+ * @param value
+ * @param useType
+ */
+ public AccessPoint(String value, String useType)
+ {
+ this.value = value;
+ this.useType = useType;
+ }
/**
* Gets the value of the value property.
*
@@ -111,5 +399,4 @@ public class AccessPoint implements Seri
this.useType = value;
}
-}
-
\ No newline at end of file
+}
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
