org.jboss.soa.esb.actions.soap.proxy
Class SOAPProxy

java.lang.Object
  org.jboss.soa.esb.actions.AbstractActionLifecycle
      org.jboss.soa.esb.actions.AbstractActionPipelineProcessor
          org.jboss.soa.esb.actions.soap.proxy.SOAPProxy

All Implemented Interfaces:

ActionLifecycle, ActionPipelineProcessor

@Publish(value=SOAPProxyWsdlContractPublisher.class)
public class SOAPProxy
extends AbstractActionPipelineProcessor

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 solves the following problems:

• Provides for more loose coupling between the client & service; 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 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.
• 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)
• 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.
• Complex context-based routing via ContentBasedRouter.

Other mechanisms of doing this are inappropriate or inadequate:

• SOAPClient is used to invoke external web services, not mirror them.
• SOAPProducer only executes internally-deployed JBoss WS services.
• HttpRouter requires too much by-hand configuration for easy WS proxying.
• EBWS strips out the SOAP Envelope and only passes along the body.

With a SOAPProxy action:

• It is both a producer and consumer of web services.
• All that is required is a property pointing to the external wsdl.
• The wsdl can be automatically transformed via the optional wsdlTransform property.
• 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.
• If using http, any of the HttpRouter properties can also optionally be applied to as overrides.

Configuration Properties

• wsdl (required): The original wsdl url whose WS endpoint will get re-written and exposed as new wsdl from the ESB. Depending upon the <definitions><service><port><soap:address location attribute's protocol (for example "http"), a protocol-specific 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:
  
  • http://localhost:8080/Quickstart_webservice_proxy_basic_ws/HelloWorldWS?wsdl
  • https://localhost:8443/webservice_proxy_security/HelloWorldWS?wsdl
  • file:///tmp/HelloWorldWS.wsdl
  • classpath://META-INF/HelloWorldWS.wsdl
  • internal://jboss.ws:context=Quickstart_webservice_proxy_basic_ws,endpoint=HelloWorldWS
• wsdlTransform (optional): A <smooks-resource-list> xml config file allowing for flexible wsdl transformation.
• * (optional): Any of the HttpRouter properties can be applied, if the wsdl specifies an http transport.
• endpointUrl (optional): Example of an HttpRouter property, but useful when domain name matching is important for SSL certs.
• file (optional): Apache Commons HTTPClient properties file, useful when proxying to a web service via SSL
• clientCredentialsRequired (optional; default is "true"): Whether the Basic Auth credentials are required to come from the end client, or if the credentials specified inside file can be used instead.

* For other possible configuration properties, see the specific SOAPProxyTransport implementations themselves.

Example of a straightforward scenario:

 <action name="proxy" class="org.jboss.soa.esb.actions.soap.proxy.SOAPProxy">
     <property name="wsdl" value="http://localhost:8080/Quickstart_webservice_proxy_basic_ws/HelloWorldWS?wsdl"/>
 </action>
 

Example of a basic auth + ssl scenario:

 <action name="proxy" class="org.jboss.soa.esb.actions.soap.proxy.SOAPProxy">
     <property name="wsdl" value="https://localhost:8443/webservice_proxy_security/HelloWorldWS?wsdl"/>
     <property name="endpointUrl" value="https://localhost:8443/webservice_proxy_security/HelloWorldWS"/>
     <property name="file" value="/META-INF/httpclient-8443.properties"/>
     <property name="clientCredentialsRequired" value="true"/>
 </action>
 

Author:

dward at jboss.org

Field Summary

Fields inherited from interface org.jboss.soa.esb.actions.ActionPipelineProcessor

PROCESS_EXCEPTION_METHOD, PROCESS_METHOD, PROCESS_SUCCESS_METHOD

Constructor Summary

SOAPProxy(ConfigTree config)

Method Summary

void	destroy() Destroy the action instance.
void	initialise() Initialise the action instance.
Message	process(Message message) Perform the action processing on the specified message.

Methods inherited from class org.jboss.soa.esb.actions.AbstractActionPipelineProcessor

processException, processSuccess

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SOAPProxy

public SOAPProxy(ConfigTree config)
          throws ConfigurationException

Throws:

ConfigurationException

Method Detail

initialise

public void initialise()
                throws ActionLifecycleException

Description copied from class: AbstractActionLifecycle

Initialise the action instance.

This method is called after the action instance has been instantiated so that configuration options can be validated.

Specified by:

initialise in interface ActionLifecycle

Overrides:

initialise in class AbstractActionLifecycle

Throws:

ActionLifecycleException - for errors during initialisation.

process

public Message process(Message message)
                throws ActionProcessingException

Description copied from interface: ActionPipelineProcessor

Perform the action processing on the specified message. This method is invoked for each message passing throught the pipeline.

Parameters:

message - The current message being processed.

Returns:

The message to be passed to the next stage of the pipeline.

Throws:

ActionProcessingException - for errors during processing.

destroy

public void destroy()
             throws ActionLifecycleException

Description copied from class: AbstractActionLifecycle

Destroy the action instance.

This method is called prior to the release of the action instance. All resources associated with this action instance should be released as the instance will no longer be used.

Specified by:

destroy in interface ActionLifecycle

Overrides:

destroy in class AbstractActionLifecycle

Throws:

ActionLifecycleException