[jboss-svn-commits] JBL Code SVN: r30078 - labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/proxy.

Mon Nov 9 13:58:06 EST 2009

Author: dward
Date: 2009-11-09 13:58:06 -0500 (Mon, 09 Nov 2009)
New Revision: 30078

Modified:
   labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/proxy/SOAPProxy.java
Log:
javadoc tweak


Modified: labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/proxy/SOAPProxy.java
===================================================================

--- labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/proxy/SOAPProxy.java	2009-11-09 18:56:52 UTC (rev 30077)
+++ labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/proxy/SOAPProxy.java	2009-11-09 18:58:06 UTC (rev 30078)
@@ -57,18 +57,41 @@
  * A SOAPProxy focuses on the consumption of an external WS endpoint (e.g. hosted on .NET, another external Java-based AS, LAMP)
  * and re-publication of a WS endpoint via the ESB.  The ESB sits between the ultimate consumer/client (e.g. .NET WinForm
  * application) and the ultimate producer (e.g. RoR-hosted WS).  The purpose of this intermediary is to provide an abstraction
- * layer that provides for more loose coupling between the client and service, as they are both completely unaware of each other
- * (the client no longer has a direct connection to the remote service's hostname/IP address).  The client will see modified WSDL
- * so that the client is pointed to the ESB's exposed endpoint instead of the original, now proxied endpoint.<p/>
+ * layer that solves the following problems:
+ * <ul>
+ * <li>Provides for more loose coupling between the client &amp; service; they are both completely unaware of each other.</li>
+ * <li>The client no longer has a direct connection to the remote service's hostname/IP address.</li>
+ * <li>The client will see modified WSDL that changes the inbound/outbound parameters. At a minimum, the WSDL must be tweaked so that the client is pointed to the ESB's exposed endpoint instead of the original, now proxied endpoint.</li>
+ * <li>A transformation of the SOAP envelope/body can be introduced via the ESB action chain both for the inbound request and outbound response.  (see XsltAction or SmooksAction)</li>
+ * <li>Service versioning is possible since clients can connect to 2 or more proxy endpoints on the ESB, each with its own WSDL and/or transformations and routing requirements, and the ESB will send the appropriate message to the appropriate endpoint and provide an ultimate response.</li>
+ * <li>Complex context-based routing via ContentBasedRouter.</li>
+ * </ul>
  * 
- * <i>Configuration</i><br/>
- * <ol>
+ * Other mechanisms of doing this are inappropriate or inadequate:
+ * <ul>
+ * <li>SOAPClient is used to invoke external web services, not mirror them.</li>
+ * <li>SOAPProducer only executes internally-deployed JBoss WS services.</li>
+ * <li>HttpRouter requires too much by-hand configuration for easy WS proxying.</li>
+ * <li>EBWS strips out the SOAP Envelope and only passes along the body.</li>
+ * </ul>
+ * 
+ * With a SOAPProxy action:
+ * <ul>
+ * <li>It is both a producer and consumer of web services.</li>
+ * <li>All that is required is a property pointing to the external wsdl.</li>
+ * <li>The wsdl can be automatically transformed via the optional wsdlTransform property.</li>
+ * <li>It is understood that SOAP is not tied to http.  The wsdl is read, and if an http transport is defined, that will be used.  Other transports (jms) will need future consideration.</li>
+ * <li>If using http, any of the HttpRouter properties can also optionally be applied to as overrides.</li>
+ * </ul>
+ * 
+ * <i>Configuration Properties</i><br/>
+ * <ul>
  * <li><b>wsdl</b> (required): The original wsdl {@link URL url} whose WS endpoint will get re-written and exposed as new wsdl from
  * the ESB.  Depending upon the &lt;definitions&gt;&lt;service&gt;&lt;port&gt;&lt;soap:address location attribute's protocol (for
  * example "http"), a protocol-specific {@link SOAPProxyTransport} implementation is used.  The value can reference a location based on
  * five different schemes: http, https, file, classpath or internal (JBossWS).  Here are some examples:<br/>
  * <ul>
- * <li>http://localhost:8080/Quickstart_webservice_proxy_basic/HelloWorldWS?wsdl</li>
+ * <li>http://localhost:8080/Quickstart_webservice_proxy_basic_ws/HelloWorldWS?wsdl</li>
  * <li>https://localhost:8443/webservice_proxy_security/HelloWorldWS?wsdl</li>
  * <li>file:///tmp/HelloWorldWS.wsdl</li>
  * <li>classpath://META-INF/HelloWorldWS.wsdl</li>
@@ -80,13 +103,13 @@
  * <li><b>file</b> (optional): Apache Commons HTTPClient properties file, useful when proxying to a web service via SSL</li>
  * <li><b>clientCredentialsRequired</b> (optional; default is "true"): Whether the Basic Auth credentials are required to come from the end
  * client, or if the credentials specified inside <b>file</b> can be used instead.</li>
- * </ol>
- * * For other possible configuration properties, see the specific {@link SOAPProxyTransport} implementations themselves.<p/>
+ * </ul>
+ * <b>*</b> For other possible configuration properties, see the specific {@link SOAPProxyTransport} implementations themselves.<p/>
  * 
  * <i>Example of a straightforward scenario:</i><br/>
  * <pre>
  * &lt;action name="proxy" class="org.jboss.soa.esb.actions.soap.proxy.SOAPProxy"&gt;
- * &nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="wsdl" value="http://localhost:8080/Quickstart_webservice_proxy_basic/HelloWorldWS?wsdl"/&gt;
+ * &nbsp;&nbsp;&nbsp;&nbsp;&lt;property name="wsdl" value="http://localhost:8080/Quickstart_webservice_proxy_basic_ws/HelloWorldWS?wsdl"/&gt;
  * &lt;/action&gt;
  * </pre>
  * <i>Example of a basic auth + ssl scenario:</i><br/>

