{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

The petals-bc-soap component can expose an external Web Service as a JBI ServiceEndpoint. This is done by deploying a Service Unit on it :

{center}
!soap_provide.png!
*Provides an external Web Service as a JBI service*
{center}

When a message is received on a SOAP linked endpoint from the JBI environment, it is transformed into a SOAP message and sent to the Web Service. The address of the Web Service to send the SOAP message to is defined in the address extension of the deployed Service Unit.

\\
The SOAP message is created like this :
* The JBI message payload is wrapped in the SOAP body
* The JBI message attachments are used to create SOAP ones
* The JBI message exchange operation is used to create the SOAP action
* The JBI MEP is used to determine the SOAP MEP

\\
The external Web Service is called and the SOAP response is processed and returned to the JBI environment.

h3. Service Unit descriptor

The Service Unit descriptor file ({{jbi.xml}}) looks 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:wsdl>http://example.org/service/SampleWebService?wsdl</petalsCDK:wsdl>

<!-- SOAP specific fields -->
<soap:address>http://example.org/service/SampleWebService</soap:address>
<soap:soap-version>1.1</soap:soap-version>
<soap:add-root>false</soap:add-root>
<soap:chunked-mode>false</soap:chunked-mode>
<soap:cleanup-transport>true</soap:cleanup-transport>
<soap:mode>SOAP</soap:mode>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

\\
{include:0 CDK SU Provide Configuration}

\\
{center}
{table-plus}
|| Parameter || Description || Default || Required ||
| address | Address of the external Web Service to send JBI messages to. | \- | Yes |
| mode | The mode to be used to send SOAP message to the specified address. \\ Possible values are : {{SOAP}} for basic WebService calls, {{TOPIC}} for
WebService notifications and {{REST}} for REST service calls. | \- | Yes |
| soap-version | The SOAP version used to create SOAP messages. \\ \\ Possible values are {{11}} and {{12}}. | SOAP | No |
| synchronous-timeout | The timeout value when invoking a a service in the JBI bus. \\{info:title=Note}This value override the CDK value.{info} \\ \\ The value is expressed in milliseconds. | 2000 | No |
| proxy-host | The proxy host name. \\ \\ If it is not set, the proxy mode will be disabled and all others proxy parameters are ignored. | \- | No |
| proxy-port | The proxy host port. | \- | No |
| proxy-user | The proxy user. | \- | No |
| proxy-password | The proxy password. | \- | No |
| proxy-domain | The proxy domain. | \- | No |
| cleanup-transport | Cleanup the transport after the WebService call. \\ \\ Not cleaning up the transport can cause timeouts on large number of calls. \\ \\ Possible values are: {{true}}, {{false}}. | true | No |
| headers-filter | A value used to filter Normalized Message properties to be added to the outgoing SOAP message. All the normalized message properties which are {{org.w3c.dom.DocumentFragment}} instances. These values can be filtered at the Service Unit level with the headers-filter property. If the headers-filter property is set to '{{org.ow2.petals.soap.foo.\*, org.ow2.petals.soap.bar}}', all the DocumentFragment properties which are starting with '{{org.ow2.petals.soap.foo.\*}}' and with '{{org.ow2.petals.soap.bar}}' will be added to the outgoing SOAP Header (as children).| \- | No |
| inject-headers | Inject some additional headers to the outgoing SOAP message. All the elements of the {{org.w3c.dom.DocumentFragment}} Map which is available in the {{javax.jbi.messaging.protocol.headers}} message properties will be added if the Service Unit level property inject-headers is set to true.| false | No |
{table-plus}
*Configuration of a Service Unit to provide a service (SOAP)*
{center}

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 :

{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:sample="http://petals.ow2.org/sample"
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="sample:SampleProvider"
service-name="sample:SampleProviderService"
endpoint-name="SampleProvider">

<!-- CDK specific fields -->
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation>${input_operation}</petalsCDK:operation>

<!-- SOAP specific fields -->
<soap:address>RESTService</soap:address>
<soap:mode>REST</soap:mode>
<soap:rest-add-namespace-uri>
http://petals.ow2.org/sample
</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}

Each request to the REST URI {{http://<host>:<port>/petals/services/RESTService/}} will be forwarded to the SampleProviderEndpoint JBI endpoint.

An incoming request on the URL {{http://<host>:<port>/petals/services/RESTService/myOperation?param1=value1&param2=value2}} in GET mode will produce the following JBI message :
{code:lang=xml}
<myOperation>
<param1>value1</param1>
<param2>value2</param2>
</myOperation>
{code}

With the {{rest.add-namespace-*}} parameters specified in the previous configuration, the JBI message will be like :
{code:lang=xml}
<ns1:myOperation xmlns:ns1="http://petals.ow2.org/sample">
<ns1:param1>value1</ns1:param1>
<ns1:param2>value2</ns1:param2>
</ns1:myOperation>
{code}

Let's suppose that the JBI service returns a JBI response like :
{code:lang=xml}
<ns1:Response xmlns:ns1="http://petals.ow2.org/sample1"
xmlns:ns2="http://petals.ow2.org/sample2"
xmlns:ns3="http://petals.ow2.org/sample3">
<ns1:param1>value1</ns1:param1>
<ns2:param2>value2</ns2:param2>
<ns3:param3>value3</ns3:param3>
</ns1:Response>
{code}

If the {{rest.remove-prefix-on-response}} parameter is set to 'ns1,ns2', the message returned to the REST service consumer will be :
{code:lang=xml}
<Response xmlns:ns1="http://petals.ow2.org/sample1"
xmlns:ns2="http://petals.ow2.org/sample2"
xmlns:ns3="http://petals.ow2.org/sample3">
<param1>value1</param1>
<param2>value2</param2>
<ns3:param3>value3</ns3:param3>
</Response>
{code}

If the {{rest.remove-prefix-on-response}} parameter is set to '*', the message returned to the REST service consumer will be :
{code:lang=xml}
<Response xmlns:ns1="http://petals.ow2.org/sample1"
xmlns:ns2="http://petals.ow2.org/sample2"
xmlns:ns3="http://petals.ow2.org/sample3">
<param1>value1</param1>
<param2>value2</param2>
<param3>value3</param3>
</Response>
{code}

h1. Web Service Notifications

h2. Intoduction

The petals-bc-soap offers a Web Service Notification feature. It works as :

{center}
!soap_topic.png!
*Handling Web Service notifications*
{center}

WS-N is a family of related specifications that define a standard Web Service approach to notification using a topic-based publish/subscribe pattern. You can get the WS-N specification [here|http://www.oasis-open.org/committees/wsn]. The SOAP binding component uses the petals-ws-star library to provide this feature.

\\
As defined in the WS-N specification, each notification consumer must subscribe to the notification producer to receive notification messages. In PEtALS, a topic is linked to a JBI endpoint. Each time that a message is received on this endpoint, a notification message will be sent to notification WS consumers (see the above picture).

h2. Create a WS-N topic

To create a WS-N topic, you need to deploy a service unit with a specific address format :
{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:TopicInterface"
service-name="sample:TopicService"
endpoint-name="TopicEndpoint">

<!-- SOAP specific fields -->
<soap:address>TopicSample</soap:address>
<soap:mode>TOPIC</soap:mode> 1
...
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
# With the TOPIC mode, the topic specified in the address parameter will be created during Service Unit startup.

After deployment, a new JBI endpoint is available : TopicEndpoint. Each JBI message sent to this endpoint will be published on the topic. A WS-N producer is automatically created. It is in charge of handle the topic and send notification messages to all subscribers.

{note:title=Note}
The topics are persisted by the component since the release 3.1 so that all the required data is reloaded on restart.
{note}

h2. Subscribe to WS-N producer

In order to receive WS-Notifications, the consumers MUST subscribe to these notifications to the WS-N producer.

To subscribe to WS notification, the notification consumer must send a specific SOAP message to the notification producer. In the SOAP BC, subscription URL is {{http://HOST:PORT/wsn/producer}} where :
* HOST is the host you have installed the SOAP BC
* PORT is the port where the SOAP BC listens to incoming SOAP messages

An example of a SOAP subscribe message is :
{code:lang=xml}
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
<wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
http://localhost:8084/wsn-consumer/services/consumer
</wsa:To>
<wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeRequest
</wsa:Action>
<wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
uuid:9888fa43-281f-ea0f-ec21-09e9119366c6
</wsa:MessageID>
<wsa:From xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>http://www.w3.org/2005/08/addressing/role/anonymous</wsa:Address>
</wsa:From>
</soap:Header>
<soap:Body>
<wsnt:Subscribe xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
<wsnt:ConsumerReference>
<wsa:Address xmlns:wsa="http://www.w3.org/2005/08/addressing">
http://127.0.0.1:8084/wsn-consumer/services/consumer 1
</wsa:Address>
</wsnt:ConsumerReference>
<wsnt:Filter>
<wsnt:TopicExpression Dialect="xsd:anyURI">TopicSample</wsnt:TopicExpression> 2
</wsnt:Filter>
</wsnt:Subscribe>
</soap:Body>
</soap:Envelope>
{code}
# The address to send notifications messages to. This can be simply a Web Service endpoint which can handle notification message
# The name of the topic to subscribe to

\\
Subscribers can use the PEtALS WS-N client API to subscribe to topics. It can be done like this :
{code}
package org.ow2.petals.binding.soap.wsn;

import java.net.URI;
import javax.xml.namespace.QName;
import org.ow2.petals.ws.addressing.EndpointReference;
import org.ow2.petals.ws.client.SubscriptionClient;
import org.ow2.petals.ws.client.WsnProducerClient;
import org.ow2.petals.ws.fault.WsnFault;
import org.ow2.petals.ws.notification.TopicExpressionFilter;

/**
* Web service notification subscription.
*
*/
public class SubscribeClient {

/**
* @param args
*/
public static void main(String[] args) {
EndpointReference sourceEPR = new EndpointReference(URI.create("http://localhost:9090/wsn-consumer/"));
EndpointReference destinationEPR =
new EndpointReference(URI.create("http://localhost:9090/wsn-consumer/service/consumer"));
WsnProducerClient client = new WsnProducerClient(sourceEPR,
destinationEPR);
TopicExpressionFilter filter = null;
try {
filter = new TopicExpressionFilter(new QName("topicSample"));
} catch (WsnFault e1) {
e1.printStackTrace();
}
SubscriptionClient subsClient = null;
try {
subsClient = client.subscribe(sourceEPR, filter, null);
} catch (WsnFault e) {
e.printStackTrace();
}
}
}
{code}

\\
{info:title=Note}
All the subscriptions are persisted in the component work folder to be able to reload subscriptions on componentrestart.
{info}

\\
{info:title=Note}
If there are N subscriptions for the same notification consumer, the notification message will be sent N times. The first unsubscribe call will remove all the subscriptions for this consumer.
{info}

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");
}
}
}
}
{code}

This class MUST be in the service classloader, the easiest way is to package it in the service unit. It will be handled by the SOAP binding component and the Rampart module.

{note:title=Note}
If you use maven2 to package you service unit, you just have to add this java class under a {{src/main/java}} directory of your jbi-service-unit project or add a dependency to the handler library.
{note}

The service is now secured with Rampart. If a SOAP message without security headers is handled by the service, a SOAP fault will be returned with message like: "_Incoming message does not contain required Security header_".

h3. Client side

The SOAP header must contains the required security elements like in the following SOAP message snippet :
{code:lang=xml}
<soapenv:Header>
<wsse:Security
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
soapenv:mustUnderstand="1">
<wsu:Timestamp
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="Timestamp-26598747">
<wsu:Created>2007-07-30T14:59:34.944Z</wsu:Created>
<wsu:Expires>2007-07-30T15:04:34.944Z</wsu:Expires>
</wsu:Timestamp>
<wsse:UsernameToken
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="UsernameToken-6427893">
<wsse:Username>bob</wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-
1.0#PasswordDigest">
0ziDIJ4Gd0XHbbbB/rgasDpOZJY=
</wsse:Password>
<wsse:Nonce>
fqgz0lkb7/ezFiY7Km4qvg==
</wsse:Nonce>
<wsu:Created>
2007-07-30T14:59:34.944Z
</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
{code}

The following code snippet shows how to engage the rampaet module on the client side and how to call the Web Service :
{code}
ConfigurationContext ctx =
ConfigurationContextFactory
.createConfigurationContextFromFileSystem(axis2ConfPath, null);

ServiceClient client = new ServiceClient(ctx, null);
OMElement payload = getSayHelloOMElement(sayHelloStr);

Options options = new Options();
options.setProperty(WSSHandlerConstants.OUTFLOW_SECURITY, getOutflowConfiguration("bob"));
client.engageModule(new QName("rampart"));
options.setTo(targetEPR);
options.setAction("sayHello");

client.setOptions(options);
result = client.sendReceive(payload);
{code}

The {{axis2ConfPath}} directory must point to a directory in which a {{modules}} directory contains the {{rampart-1.2.mar}} module used by the client. The code also uses a Class handler which is similar to the service's one, and will provide the required user and password :
{code}
package org.ow2.petals.security.client.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 MyExampleClientHandler 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");
}
}
}
}
{code}

In this example, the user name is sent in {{plain clear text}} in the request. Depending on your security needs, you should use a secured transport layer (such as HTTPS), or another Rampart configuration to encrypt the information (and even the body content if required). For more Rampart configuration examples, you should have a look at the samples provided by Apache in the rampart distribution at : [http://www.apache.org/dyn/closer.cgi/ws/rampart/1_3|http://www.apache.org/dyn/closer.cgi/ws/rampart/1_3].

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

The WS-Policy configuration is defined at the Service Unit level like in the following Service Unit descriptor snippet (jbi.xml) :
{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:PolicyInterface"
service-name="sample:PolicyService"
endpoint-name="PolicyEndpoint">

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

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

<!-- SOAP specific fields -->
<soap:address>http://localhost:8888/axis2/services/PolicyService</soap:address>
<soap:mode>SOAP</soap:mode>
<soap:policy-path>policy</soap:policy-patth>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

\\
The WS-Policy is activated when the field {{policy-path}} is defined in the Service Unit (the Rampart module is automatically engaged if needed). This path is relative to the Service Unit root path. With the previous declaration, the Service Unit strucutre must be :
{noformat}
my-shared-library.zip
+ META-INF
- jbi.xml
+ policy
- client.jks
- client.properties
- policy.xml
- sample.wsdl
- su-policy-sample.jar
{noformat}

\\
In the policy path, the {{policy.xml}} contains the policy decriptor provided by the Web Service (in the current version, the policy can not be retrieved from the WSDL description). It also contains the keystore and a properties configuration file used by Rampart at runtime.

{note:title=Note}
The current version of the component does not extract the policy description from the WSDL one. You must define it in the {{policy.xml}} file.
{note}

\\
An example of policy description file (taken from Rampart samples) could be :
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<wsp:Policy wsu:Id="SigOnly"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
<sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/
IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:RequireThumbprintReference/>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken=
"http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
<wsp:Policy>
<sp:RequireThumbprintReference/>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:TripleDesRsa15/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:OnlySignEntireHeadersAndBody/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:MustSupportRefKeyIdentifier/>
<sp:MustSupportRefIssuerSerial/>
</wsp:Policy>
</sp:Wss10>
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
</sp:SignedParts>
<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:user>client</ramp:user>
<ramp:encryptionUser>service</ramp:encryptionUser>
<ramp:passwordCallbackClass>
org.apache.rampart.samples.policy.sample02.PWCBHandler
</ramp:passwordCallbackClass>
<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">
JKS
</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">
client.jks
</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">
apache
</ramp:property>
</ramp:crypto>
</ramp:signatureCrypto>
</ramp:RampartConfig>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
{code}

The extension {{RampartConfig}} is used by Rampart for configuration purposes. With the previous sample, the passwordCallbackClass : {{org.apache.rampart.samples.policy.sample02.PWCBHandler}} must be found in the service classpath (it will be automatically included if the class is packaged in the Service Unit, in a JAR for example).

\\
{info:title=Info}
You can find more examples on how to use Rampart on the Rampart samples page at : [http://ws.apache.org/rampart/samples.html|http://ws.apache.org/rampart/samples.html]
{info}

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}