[jboss-svn-commits] JBL Code SVN: r12209 - labs/jbossesb/trunk/product/core/listeners/src/org/jboss/soa/esb/actions/soap.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue May 29 07:01:23 EDT 2007
Author: tfennelly
Date: 2007-05-29 07:01:23 -0400 (Tue, 29 May 2007)
New Revision: 12209
Modified:
labs/jbossesb/trunk/product/core/listeners/src/org/jboss/soa/esb/actions/soap/SOAPClient.java
Log:
Added Javadoc.
Modified: labs/jbossesb/trunk/product/core/listeners/src/org/jboss/soa/esb/actions/soap/SOAPClient.java
===================================================================
--- labs/jbossesb/trunk/product/core/listeners/src/org/jboss/soa/esb/actions/soap/SOAPClient.java 2007-05-29 09:26:49 UTC (rev 12208)
+++ labs/jbossesb/trunk/product/core/listeners/src/org/jboss/soa/esb/actions/soap/SOAPClient.java 2007-05-29 11:01:23 UTC (rev 12209)
@@ -37,11 +37,20 @@
/**
* SOAP Client action processor.
* <p/>
- * Uses the SOAPUI Client Service to construct an populate a message
- * for the target service. This action then routes that message to the service.
+ * Uses the soapUI Client Service to construct and populate a message
+ * for the target service. This action then routes that message to that service.
*
- * <h2>SOAP Request Message Construction</h2>
- * The message parameters are supplied in one of 2 ways:
+ * <h2>Endpoint Operation Specification</h2>
+ * Specifying the endpoint operation is a straightforward task. Simply specify the "wsdl" and
+ * "operation" properties on the SOAPClient action as follows:
+ * <pre>
+ * <action name="soapui-client-action" class="org.jboss.soa.esb.actions.soap.SOAPClient">
+ * <property name="wsdl" value="http://localhost:18080/acme/services/RetailerCallback?wsdl"/>
+ * <property name="operation" value="SendSalesOrderNotification"/>
+ * </action></pre>
+ *
+ * <h2 id="request-construction">SOAP Request Message Construction</h2>
+ * The SOAP operation parameters are supplied in one of 2 ways:
* <ol>
* <li>As a {@link Map} instance set on the <i>default body location</i> (Message.getBody().add(Map))</li>
* <li>As a {@link Map} instance set on in a <i>named body location</i> (Message.getBody().add(String, Map)),
@@ -50,16 +59,144 @@
* </ol>
* The parameter {@link Map} itself can also be populated in one of 2 ways:
* <ol>
- * <li>With a set of Objects that are accessed (for SOAP message parameters) using the
+ * <li><b>Option 1</b>: With a set of Objects that are accessed (for SOAP message parameters) using the
* <a href="http://www.ognl.org/">OGNL</a></li> framework. More on the use of OGNL below.
- * <li>With a set of String based key-value pairs(<String, String>), where the
+ * <li><b>Option 2</b>: With a set of String based key-value pairs(<String, Object>), where the
* key is an OGNL expression identifying the SOAP parameter to be populated with
* the key's value. More on the use of OGNL below.
* </li>
* </ol>
- *
+ * As stated above, <a href="http://www.ognl.org/">OGNL</a> is the mechanism we use for selecting
+ * the SOAP parameter values to be injected into the SOAP message from the supplied parameter
+ * {@link Map}. The OGNL expression for a specific parameter within the SOAP message depends on that
+ * the position of that parameter within the SOAP body. In the following message:
+ * <pre>
+ * <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ * xmlns:cus="http://schemas.acme.com">
+ * <soapenv:Header/>
+ * <soapenv:Body>
+ * <cus:<b color="red">customerOrder</b>>
+ * <cus:<b color="red">header</b>>
+ * <cus:<b color="red">customerNumber</b>>123456</cus:customerNumber>
+ * </cus:header>
+ * </cus:customerOrder>
+ * </soapenv:Body>
+ * </soapenv:Envelope>
+ * </pre>
*
+ * The OGNL expression representing the customerNumber parameter is "<b color="red">customerOrder.header.customerNumber</b>".
+ * <p/>
+ * Once the OGNL expression has been calculated for a parameter, this class will check the supplied parameter
+ * map for an Object keyed off the full OGNL expression (Option 1 above). If no such parameter Object is present on the map,
+ * this class will then attempt to load the parameter by supplying the map and OGNL expression instances to the
+ * OGNL toolkit (Option 2 above). If this doesn't yield a value, this parameter location within the SOAP message will
+ * remain blank.
+ * <p/>
+ * Taking the sample message above and using the "Option 1" approach to populating the "customerNumber" requires an
+ * object instance (e.g. an "Order" object instance) to be set on the parameters map under the key "customerOrder". The "customerOrder"
+ * object instance needs to contain a "header" property (e.g. a "Header" object instance). The object instance
+ * behind the "header" property (e.g. a "Header" object instance) should have a "customerNumber" property.
+ * <p/>
+ * OGNL expressions associated with Collections are constructed in a slightly different way. This is easiest explained
+ * through an example:
+ * <pre>
+ * <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ * xmlns:cus="http://schemas.active-endpoints.com/sample/customerorder/2006/04/CustomerOrder.xsd"
+ * xmlns:stan="http://schemas.active-endpoints.com/sample/standardtypes/2006/04/StandardTypes.xsd">
+ * <soapenv:Header/>
+ * <soapenv:Body>
+ * <cus:<b color="red">customerOrder</b>>
+ * <cus:<b color="red">items</b>>
+ * <cus:item>
+ * <cus:<b color="red">partNumber</b>>FLT16100</cus:partNumber>
+ * <cus:description>Flat 16 feet 100 count</cus:description>
+ * <cus:quantity>50</cus:quantity>
+ * <cus:price>490.00</cus:price>
+ * <cus:extensionAmount>24500.00</cus:extensionAmount>
+ * </cus:item>
+ * <cus:item>
+ * <cus:<b color="red">partNumber</b>>RND08065</cus:partNumber>
+ * <cus:description>Round 8 feet 65 count</cus:description>
+ * <cus:quantity>9</cus:quantity>
+ * <cus:price>178.00</cus:price>
+ * <cus:extensionAmount>7852.00</cus:extensionAmount>
+ * </cus:item>
+ * </cus:items>
+ * </cus:customerOrder>
+ * </soapenv:Body>
+ * </soapenv:Envelope>
+ * </pre>
+ * The above order message contains a collection of order "items". Each entry in the collection is represented
+ * by an "item" element. The OGNL expressions for the order item "partNumber" is constructed as
+ * "<b color="red">customerOrder.items[0].partnumber</b>" and "<b color="red">customerOrder.items[1].partnumber</b>".
+ * As you can see from this, the collection entry element (the "item" element) makes no explicit appearance in the OGNL
+ * expression. It is represented implicitly by the indexing notation. In terms of an Object Graph (Option 1 above),
+ * this could be represented by an Order object instance (keyed on the map as "customerOrder") containing an "items"
+ * list ({@link java.util.List} or array), with the list entries being "OrderItem" instances, which in turn contains
+ * "partNumber" etc properties.
+ * <p/>
+ * Option 2 (above) provides a quick-and-dirty way to populate a SOAP message without having to create an Object
+ * model ala Option 1. The OGNL expressions that correspond with the SOAP operation parameters are exactly the same
+ * as for Option 1, except that there's not Object Graph Navigation involved. The OGNL expression is simply used as
+ * the key into the {@link Map}, with the corresponding key-value being the parameter.
*
+ * <h2>SOAP Response Message Consumption</h2>
+ * The SOAP response object instance can be is attached to the ESB {@link Message} instance in one of the
+ * following ways:
+ * <ol>
+ * <li>On the <i>default body location</i> (Message.getBody().add(Map))</li>
+ * <li>On in a <i>named body location</i> (Message.getBody().add(String, Map)),
+ * where the name of that body location is specified as the value of the "responseLocation" action property.
+ * </li>
+ * </ol>
+ * The response object instance can also be populated (from the SOAP response) in one of 3 ways:
+ * <ol>
+ * <li><b>Option 1</b>: As an Object Graph created and populated by the
+ * <a href="http://xstream.codehaus.org">XStream</a> toolkit.
+ * <li><b>Option 2</b>: As a set of String based key-value pairs(<String, String>), where the
+ * key is an OGNL expression identifying the SOAP response element and the value is a String
+ * representing the value from the SOAP message.
+ * </li>
+ * <li><b>Option 3</b>: If Options 1 or 2 are not specified in the action configuration, the raw SOAP
+ * response message (String) is attached to the message.
+ * </li>
+ * </ol>
+ * Using <a href="http://xstream.codehaus.org">XStream</a> as a mechanism for populating an Object Graph
+ * (Option 1 above) is straightforward and works well, as long as the XML and Java object models are in line with
+ * each other.
+ * <p/>
+ * The XStream approach (Option 1) is configured on the action as follows:
+ * <pre>
+ * <action name="soapui-client-action" class="org.jboss.soa.esb.actions.soap.SOAPClient">
+ * <property name="wsdl" value="http://localhost:18080/acme/services/RetailerService?wsdl"/>
+ * <property name="operation" value="GetOrder"/>
+ * <property name="paramsLocation" value="get-order-params" />
+ * <property name="responseLocation" value="get-order-response" />
+ * <property name="responseXStreamConfig">
+ * <alias name="customerOrder" class="com.acme.order.Order" namespace="http://schemas.acme.com/services/CustomerOrder.xsd" />
+ * <alias name="orderheader" class="com.acme.order.Header" namespace="http://schemas.acme.com/services/CustomerOrder.xsd" />
+ * <alias name="item" class="com.acme.order.OrderItem" namespace="http://schemas.acme.com/services/CustomerOrder.xsd" />
+ * </property>
+ * </action>
+ * </pre>
+ * In the above example, we also include an example of how to specify non-default named locations for the request
+ * parameters {@link Map} and response object instance.
+ * <p/>
+ * To have the SOAP reponse data extracted into an OGNL keyed map (Option 2 above) and attached to the ESB
+ * {@link Message}, simply replace the "responseXStreamConfig" property with the "responseAsOgnlMap" property
+ * having a value of "true" as follows:
+ * <pre>
+ * <action name="soapui-client-action" class="org.jboss.soa.esb.actions.soap.SOAPClient">
+ * <property name="wsdl" value="http://localhost:18080/acme/services/RetailerService?wsdl"/>
+ * <property name="operation" value="GetOrder"/>
+ * <property name="paramsLocation" value="get-order-params" />
+ * <property name="responseLocation" value="get-order-response" />
+ * <property name="responseAsOgnlMap" value="true" />
+ * </action>
+ * </pre>
+ * To return the raw SOAP message as a String (Option 3), simply omit both the "responseXStreamConfig"
+ * and "responseAsOgnlMap" properties.
+ *
* @author <a href="mailto:tom.fennelly at jboss.com">tom.fennelly at jboss.com</a>
*/
public class SOAPClient extends AbstractActionPipelineProcessor {
More information about the jboss-svn-commits
mailing list