{section}
{column}
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
todo
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
todo
h2. Introduction
todo
h2. Configuration
todo
h3. Provide mode : Provide access to external REST Service
todo
h3. Consume mode : Expose JBI Service as as REST Service
todo
h2. Samples
todo
h3. Provide mode
todo
h3. Consume mode
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
todo
h3. Client side
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}
{column}
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
todo
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
todo
h2. Introduction
todo
h2. Configuration
todo
h3. Provide mode : Provide access to external REST Service
todo
h3. Consume mode : Expose JBI Service as as REST Service
todo
h2. Samples
todo
h3. Provide mode
todo
h3. Consume mode
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
todo
h3. Client side
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}