{section}
{column}

h1. What is the BC-SOAP ?

This binding component allows to interact with external Web Services and to expose JBI services as Web Services.

A JBI MessageExchange sent to a ServiceEndpoint (mapped to a Web Service) is transformed into a SOAP message and sent to the linked external web service. A SOAP message received on an exposed web service is transformed into a JBI MessageExchange and sent to the corresponding JBI ServiceEndpoint.

This component is based on the Petals CDK.

_If you want more details about SOAP, you can consult this W3C specification : [http://www.w3.org/TR/soap/|http://www.w3.org/TR/soap/]._

h1. Features

The petals-bc-soap is based on the petals-cdk v4.x, Apache Axis2 v1.4.1 ([http://ws.apache.org/axis2/|http://ws.apache.org/axis2/]) and Mortbay Jetty v6.1.4 ([http://jetty.codehaus.org/jetty/|http://jetty.codehaus.org/jetty/]). It provides the following features :
* Expose JBI Services as Web Services
* Expose JBI Services as REST Services
* Expose Web Services as JBI Services
* Expose REST Services as JBI Services
* Handle SOAP attachments. The attachments of the incoming SOAP message are placed into the JBI message as attachments; the JBI attachments are placed in the outgoing SOAP message as attachments.
* WS-notification. The component can send/receive web service notifications to/from external subscribers/producers.
* WS-Security, WS-SecureConversation and WS-Policy via the addition of the Rampart's Axis2 module.

h1. Component Configuration

The component can be configured through its JBI descriptor file like this :

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:soap="http://petals.ow2.org/components/soap/version-3.2">
<jbi:component type="binding-component"
bootstrap-class-loader-delegation="parent-first">
<jbi:identification>
<jbi:name>petals-bc-soap</jbi:name>
<jbi:description> The SOAP Binding Component (based on Axis2 + Jetty)</jbi:description>
</jbi:identification>

<jbi:component-class-name>org.ow2.petals.binding.soap.SoapComponent</jbi:component-class-name>
<jbi:component-class-path>...</jbi:component-class-path>
<jbi:bootstrap-class-name>org.ow2.petals.binding.soap.SoapBootstrap</jbi:bootstrap-class-name>
<jbi:bootstrap-class-path>...</jbi:bootstrap-class-path>

<!-- Component Development Kit Parameters -->
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:properties-file />
<petalsCDK:performance-notifications>false</petalsCDK:performance-notifications>
<petalsCDK:jbi-listener-class-name>
org.ow2.petals.binding.soap.listener.outgoing.JBIListener
</petalsCDK:jbi-listener-class-name>
<petalsCDK:external-listener-classname>
org.ow2.petals.binding.soap.listener.incoming.SoapExternalListener
</petalsCDK:externallistener-class-name>

<!-- SOAP Component Parameters -->
<soap:http-port>8084</soap:http-port>
<soap:http-host>148.39.34.45</soap:http-host>
<soap:http-services-list>true</soap:http-services-list>
<soap:http-services-context>petals</soap:http-services-context>
<soap:http-services-mapping>services</soap:http-services-mapping>
<soap:http-thread-pool-size-min>2</soap:http-thread-pool-size-min>
<soap:http-thread-pool-size-max>50</soap:http-thread-pool-size-max>
<soap:http-acceptors>4</soap:http-acceptors>
</jbi:component>
</jbi:jbi>
{code}

{warning:title=Warning}
Only the last part of this file can be modified.
{warning}

\\
{include:0 CDK Component Configuration Table}

\\
{include:0 CDK Parameter scope}

\\
*Configuration of the component (SOAP)*
|| Parameter || Description || Default || Required ||
| http-port | The port used by the Jetty HTTP server to handle incoming http requests | 8084 | No |
| http-host | Define the network interface on which the web servser must listen. If this parameter is not set, all interfaces are listen. | localhost | No |
| http-services-list | Display the list of exposed services on http://<HOST>:<PORT>/
<CONTEXT>/<MAPPING>/listServices | true | No |
| http-threadpool-size-min | Minimun size of the Jetty HTTP server thread pool | 2 | No |
| http-threadpool-size-max | Maximun size of the Jetty HTTP server thread pool | 50 | No |
| http-acceptors | Number of Jetty HTTP acceptors | 4 | No |
| http-services-context | Context of the exposed services | petals | No |
| http-services-mapping | Mapping of the exposed services | services | No |

The SOAP component specific parameters can be also set through JMX during its installation phase.
_More information about Jetty tunning can be found on the Jetty documentation._

h1. Service Configuration

h2. Send a JBI message to an external Web Service

todo

h3. Service Unit descriptor

todo

h2. Send a JBI message from an incoming SOAP message

todo

h3. Service Unit descriptor

todo

h1. REST Services

h2. Introduction

The SOAP binding component provides REST (REpresentational State Transfer ([http://en.wikipedia.org/wiki/Representational_State_Transfer|http://en.wikipedia.org/wiki/Representational_State_Transfer])) services features since release 3.1. The REST feature is provided by Axis2 in the component.

h2. Configuration

The component can be configured to :
* Provide access to an external REST Service. This service will be available as JBI service inside the JBI environment. Each JBI message received on the JBI endpoint will be used to invoke the external REST Service. This mode is configured with a Service Unit in "provider mode".
* Expose a JBI Service as REST Service. The JBI Service can be accessed from outside of the JBI environment like other standard REST Services. This mode is configured with a Service Unit in "consumer mode".

h3. Provide mode : Provide access to external REST Service

In order to activate REST mode, the Service Unit (in provide mode) must be configured like this :

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:soap="http://petals.ow2.org/components/soap/version-3.1"
xmlns:sample="http://petals.ow2.org/soap/sample">

<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Import a Service into PEtALS => provides a Service. -->
<jbi:provides
interface-name="sample:SoapInterface"
service-name="sample:SoapInterface"
endpoint-name="SoapInterfaceEndpoint">

<!-- CDK specific fields -->
<petalsCDK:mep xsi:nil="true"/>

<!-- WSDL file -->
<petalsCDK:wsdl>
http://example.org/service/SampleWebService?wsdl
</petalsCDK:wsdl>

<!-- SOAP specific fields -->
<soap:address>
http://example.org/param1={xpathexpression1}&amp;param2={xpathexpression1}
</soap:address>
<soap:mode>REST</soap:mode>
<soap:rest-http-method>GET</soap:rest-http-method>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

* The address parameter can be configured with placeholders. In the previous code snippet, the placeholder is the bracket {}. The placeholder will be replaced by the result of the XPath expression defined inside of the placeholder. The XPath expression is performed on the content of the incoming JBI message. The placeholders will be replaced in the adress parameter to build the final URI according to the result of the XPath expression.

* The mode parameter must be set to REST to enable REST feature in component.

* Possible rest-http-method parameter values are GET, POST, PUT, DELETE (default is GET). It will be used in provider mode by Axis2 as HTTP method invokation.
** GET : The JBI message is only used to create the URI of the REST service to be invoked with the placeholders mechanism.
** POST : The JBI message is sent to the REST service.
** PUT : The JBI message is sent to the REST service.

h3. Consume mode : Expose JBI Service as as REST Service

{code:lang=xml}
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:soap="http://petals.ow2.org/components/soap/version-3.1">
<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Import a Service into PEtALS => provides a Service. -->
<jbi:consumes interface-name="helloworld:Helloworld" service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">

<!-- CDK specific fields -->
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation>getXXX</petalsCDK:operation>

<!-- SOAP specific fields -->
<soap:address>RESTServiceName</soap:address>
<soap:mode>REST</soap:mode>
<soap:rest-add-namespace-uri>http://petals.ow2.org/soapbc</soap:rest-add-namespace-uri>
<soap:rest-add-namespace-prefix>ns1</soap:rest-add-namespace-prefix>
<soap:rest-remove-prefix-on-response>*</soap:rest-remove-prefix-on-response>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

* The {{address}} parameter is used to create the Axis2 WebService that will be accessible from outside of the JBI environment. This is the same mechanism as for the standard WebService created without REST mode.

* The {{mode}} parameter value set to REST enable REST feature on the newly created WebService. Without this parameter, the REST mode is unactive.

* The {{rest-add-namespace-uri}} parameter is used to add a namespace to the generated JBI message.

* The {{rest-add-namespace-prefix}} parameter is used to specify the prefix to be used for the namespace specified by the rest.add-namespace-uri parameter. Default value is petalsbcsoaprest.

* The {{rest-remove-prefix-on-response}} is used to specify the prefix namespaces to be removed on message response. The values have to be specified in Coma Separated Value format like 'ns1,ns2'. The special value '*' is used to remove all the namespaces.

The component will create a JBI message depending on the http-method used in the incoming request :
* GET : A JBI message is created from the URL parameters
* POST/PUT/DELETE : The incoming XML message is used to create the JBI message.

In all the cases the namespaces are added to the JBI message if they are specified in the Service Unit configuration.

The JBI operation is created from the incoming REST query. The operation is extracted from the URL. A URL like {{http://<host>:<port>/petals/services/RESTService/operation?param1=value1&param2=value2}} will produce the '{{operation}}' JBI operation.

h2. Samples

h3. Provide mode

In this sample, we are going to provide the Yahoo Weather Service ([http://developer.yahoo.com/weather/|http://developer.yahoo.com/weather/]) as JBI Service inside the JBI environment. It is possible by configuring a Service Unit in provider mode :

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:soap="http://petals.ow2.org/components/soap/version-3.1"
xmlns:sample="http://petals.ow2.org/soap/sample">
<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="true">

<!-- Import a Service into PEtALS => provides a Service. -->
<jbi:provides
interface-name="sample:YahooWeatherInterface"
service-name="sample:YahooWeatherService"
endpoint-name="YahooWeatherEndpoint">

<!-- CDK specific fields -->
<petalsCDK:mep xsi:nil="true"/>

<!-- WSDL file -->
<petalsCDK:wsdl>Weather.wsdl</petalsCDK:wsdl>

<!-- SOAP specific fields -->
<soap:address>
http://weather.yahooapis.com/forecastrss?p={/*[local-name()='getWeather'][1]/*[
localname()='citycode'][1]}&amp;u={/*[local-name()='getWeather'][1]/*[local-name()='unit'][1]}
</soap:address>
<!-- The previous address has been formatted for display purpose -->
<soap:mode>REST</soap:mode>
<soap:rest-http-method>GET</soap:rest-http-method>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

When receiving a JBI message on the activated JBI endpoint, the final address will be built from the JBI message payload.

\\
For example if the following JBI message :
{code:lang=xml}
<weat:getWeather xmlns:weat="http://petals.ow2.org/services/weather">
<citycode>FRXX0099</citycode>
<unit>c</unit>
</weat:getWeather>
{code}

is associated with the address parameter value :
{noformat}
http://weather.yahooapis.com/forecastrss?p={/*[localname()='getWeather'][1]/*[local-name()='citycode']
[1]}&amp;u={/*[local-name()='getWeather'][1]/*[local-name()='unit'][1]}
{noformat}

and produces the URI {{http://weather.yahooapis.com/forecastrss?p=FRXX0099&u=c}}.

\\
The JBI message response returned by the Yahoo Weather REST service is :
{code:lang=xml}
<rss version="2.0" xmlns:yweather="http://xml.weather.yahoo.com/ns/rss/1.0"
xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">
<channel>
<title>Yahoo! Weather - Toulouse, FR</title>
<link>http://us.rd.yahoo.com/dailynews/rss/weather/Toulouse__FR/*http://weather.yahoo.com/forecast/
FRXX0099_c.html</link>
<description>Yahoo! Weather for Toulouse, FR</description>
<language>en-us</language>
<lastBuildDate>Thu, 06 Mar 2008 3:00 pm CET</lastBuildDate>
<ttl>60</ttl>
<yweather:location city="Toulouse" country="FR" region=""/>
<yweather:units distance="km" pressure="mb" speed="kph" temperature="C"/>
<yweather:wind chill="3" direction="310" speed="37"/>
<yweather:atmosphere humidity="37" pressure="0" rising="0" visibility="999"/>
<yweather:astronomy sunrise="7:22 am" sunset="6:50 pm"/>
<image>
<title>Yahoo! Weather</title>
<width>142</width>
<height>18</height>
<link>http://weather.yahoo.com/</link>
<url>http://l.yimg.com/us.yimg.com/i/us/nws/th/main_142b.gif</url>
</image>
<item>
<title>Conditions for Toulouse, FR at 3:00 pm CET</title>
<geo:lat>43.61</geo:lat>
<geo:long>1.45</geo:long>
<link>http://us.rd.yahoo.com/dailynews/rss/weather/Toulouse__FR/*http://weather.yahoo.com/forecast/
FRXX0099_c.html</link>
<pubDate>Thu, 06 Mar 2008 3:00 pm CET</pubDate>
<yweather:condition code="28" date="Thu, 06 Mar 2008 3:00 pm CET" temp="8" text="Mostly
Cloudy"/>
<description>
<![CDATA[<img src="http://l.yimg.com/us.yimg.com/i/us/we/52/28.gif" /><br />
<b>Current Conditions:</b><br />
Mostly Cloudy, 8 C<BR /><BR />
<b>Forecast:</b><BR />
Thu - Mostly Cloudy. High: 10 Low: 4<br />
Fri - Cloudy. High: 10 Low: 4<br />
<br />
<a
href="http://us.rd.yahoo.com/dailynews/rss/weather/Toulouse__FR/*http://weather.yahoo.com/forecast/
FRXX0099_c.html">Full Forecast at Yahoo! Weather</a><BR/>
(provided by The Weather Channel)<br/>]]>
</description>
<yweather:forecast code="27" date="06 Mar 2008" day="Thu" high="10" low="4" text="Mostly
Cloudy"/>
<yweather:forecast code="26" date="07 Mar 2008" day="Fri" high="10" low="4" text="Cloudy"/>
<guid isPermaLink="false">FRXX0099_2008_03_06_15_0_CET</guid>
</item>
</channel>
</rss>
{code}

h3. Consume mode

In this sample, we are going to expose a JBI service as REST service. The Service Unit configuration which will be used is :

todo

h1. Web Service Notifications

todo

h2. Intoduction

todo

h2. Create a WS-N topic

todo

h2. Subscribe to WS-N producer

todo

h2. Send a WS notification from a JBI message

When the petals-bc-soap component receives a JBI message on a topic-activated endpoint, it is transformed into a WS-notification message and published on the linked topic.

As an example of SOAP notification message, if the JBI message payload is :

{code:lang=xml}
<text>This is a sample of JBI message payload...</text>
{code}

and if it is published on the *'TopicSample'* topic, the SOAP body payload of the notification message will be :

{code:lang=xml}
<wsnt:Notify>
<wsnt:NotificationMessage>
<wsnt:SubscriptionReference>
<wsa:Address xmlns:wsa="http://www.w3.org/2005/08/addressing">
http://127.0.0.1:8084/wsn-consumer/services/consumer
</wsa:Address>
</wsnt:SubscriptionReference>
<wsnt:Topic Dialect="xsd:anyURI">TopicSample</wsnt:Topic>
<wsnt:ProducerReference>
<wsa:Address xmlns:wsa="http://www.w3.org/2005/08/addressing">
http://127.0.0.1:8084/wsn-producer/services/producer
</wsa:Address>
</wsnt:ProducerReference>
<wsnt:Message>
<text>This is a sample of JBI message payload...</text>
</wsnt:Message>
</wsnt:NotificationMessage>
</wsnt:Notify>
{code}

h1. Security

h2. Introduction

The SOAP binding component provides WS security features through the Axis2 rampart module ([http://ws.apache.org/rampart/|http://ws.apache.org/rampart/]).

This module is based on Apache WSS4J ([http://ws.apache.org/wss4j/|http://ws.apache.org/wss4j/]), an implementation of the OASIS WS-security specification ([http://www.oasis-open.org/committees/wss|http://www.oasis-open.org/committees/wss]).

This module is natively provided by the binding component since the 3.0 release.

h2. Securing JBI Services

h3. Configuration

In order to enable WS-security, you must add specific extensions to the consumes section of the Service Unit. This configuration will tell Rampart which security mode to be applied. Here's an example of a jbi.xml providing a simple Rampart configuration, with UsernameToken and Timestamping authentification :

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:soap="http://petals.ow2.org/components/soap/version-3.1">
<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Expose a PEtALS Service => consumes a Service. -->
<jbi:consumes interface-name="helloworld:Helloworld" service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">

<!-- CDK specific fields -->
<petalsCDK:mep>InOut</petalsCDK:mep>

<!-- SOAP specific fields -->
<soap:address>UserPasswordSecuredService</soap:address>
<soap:remove-root>false</soap:remove-root>
<soap:mode>SOAP</soap:mode>
<soap:modules>rampart</soap:modules>
<soap:service-parameters>
<![CDATA[
<parameter name="InflowSecurity">
<action>
<items>UsernameToken Timestamp</items>
<passwordCallbackClass>
org.ow2.petals.usecase.soapsecurity.handler.RawCBHandler
</passwordCallbackClass>
</action>
</parameter>
]]>
</soap:service-parameters>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

On this example, an Axis2 service will be created (MyExampleService) and is secured by a defined security handler :
* The {{<soap:modules>rampart</soap:modules>}} tag allows to engage the rampart module for the UserPasswordSecuredService service.
* The {{<soap:service-parameters>}} tag allows to configure rampart for this service, using the InflowSecurity parameter (you can also use the OutflowSecurity parameter).

\\
The {{org.ow2.petals.usecase.soapsecurity.handler.RawCBHandler}} Class is the handler used by the service. The following code snippet is an example of Handler implementation to validate user/password credentials :
{code}
package org.ow2.petals.usecase.soapsecurity.handler;

import org.apache.ws.security.WSPasswordCallback;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import java.io.IOException;

public class RawCBHandler implements CallbackHandler {

public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException {
for (int i = 0; i < callbacks.length; i++) {
WSPasswordCallback pwcb = (WSPasswordCallback) callbacks[i];
String id = pwcb.getIdentifer();
if ("bob".equals(id)) {
pwcb.setPassword("bobPW");
}
}
}
}

todo

h2. Using WS-Policy

The [Apache Rampart|http://ws.apache.org/rampart/] module is used to apply policies when calling an external Web Service (ie in consumer mode). The current section explains how to configure the component to use this feature.

h3. Configuration

todo

h3. Usage

Once the Service Unit is deployed on the SOAP Binding Component, all the JBI messages sent to the new activated endpoint are transformed into SOAP messages and the Web Service client will use the Service Unit defined policy to call the Web Service. The Web Service client behaviour is exactly the same as a policy-enabled Axis2 based Web Service client.

An example of WS policy with PEtALS is provided in the PEtALS SOAP usecases at : [http://websvn.ow2.org/listing.php?repname=petals&path=/trunk/configurations/petals-soap/petals-soap-policy/|http://websvn.ow2.org/listing.php?repname=petals&path=/trunk/configurations/petals-soap/petals-soap-policy/].



h1. Samples

The SOAP binding component samples are available as packaged use cases. You can find them on {{trunk/configurations/petals-soap}} directory of the [Petals ESB forge|http://forge.ow2.org/plugins/scmsvn/index.php?group_id=213].

h1. Know problems

h2. "Transport out has not been set"

If the exception message "Transport out has not been set" occurs when invoking an external web-service, using the petals-bc-soap, it can be due to a wrong URL of the external web-service. Please check it and retry your test.
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}