Petals Documentation > Petals ESB > Petals Components > Components User Guide > Petals-BC-SOAP

Petals-BC-SOAP

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/.

Features

The petals-bc-soap is based on the petals-cdk v4.x, Apache Axis2 v1.4.1 (http://ws.apache.org/axis2/) and Mortbay Jetty v6.1.4 (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.

Component Configuration

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

<?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>
Warning
Only the last part of this file can be modified.


Unable to render {include} Couldn't find a page to include called: 0 CDK Component Configuration Table


Definition of CDK parameter scope :

  • Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
  • Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.


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.

Service Configuration

Send a JBI message to an external Web Service

todo

Service Unit descriptor

todo

Send a JBI message from an incoming SOAP message

todo

Service Unit descriptor

todo

REST Services

Introduction

The SOAP binding component provides REST (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.

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".

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 : 

<?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>
  • 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.

Consume mode : Expose JBI Service as as REST Service

<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>
  • 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.

Samples

Provide mode

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

<?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>

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 :

<weat:getWeather xmlns:weat="http://petals.ow2.org/services/weather">
    <citycode>FRXX0099</citycode>
    <unit>c</unit>
</weat:getWeather>

is associated with the address parameter value :

http://weather.yahooapis.com/forecastrss?p={/*[localname()='getWeather'][1]/*[local-name()='citycode']
[1]}&amp;u={/*[local-name()='getWeather'][1]/*[local-name()='unit'][1]}

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 :

<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>

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

Web Service Notifications

todo

Intoduction

todo

Create a WS-N topic

todo

Subscribe to WS-N producer

todo

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 :

<text>This is a sample of JBI message payload...</text>

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

<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>

Security

Introduction

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

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

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

Securing JBI Services

Configuration

todo

Client side

todo

Using WS-Policy

The Apache 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.

Configuration

todo

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/.

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.

Know problems

"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.
Table of contents
Contributors
No contributors found for: authors on selected page(s)
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.