servicemix-http

ServiceMix ships with a JBI compliant HTTP/SOAP binding component named servicemix-http.

Here are the main features:

JBI compliant Binding Component
Usable in a lightweight mode in servicemix.xml configuration files
Integrated HTTP server based on Jetty 6
HTTP Client using Jakarta Commons HTTP Client
Highly performant and scalable using Jetty 6 continuations
SOAP 1.1 and 1.2 support
MIME attachments
WS-Addressing support
WSDL based and XBean based deployments
Support for all MEPs as consumers or providers
SSL support
WS-Security support

New HTTP Endpoints

The new HTTP endpoints are documented here.

Installation

Installing the servicemix-http component can be done in several ways:

drop the installer zip in an hotdeploy directory monitored by ServiceMix
using ant tasks

Note that when using ant tasks, the component is not started, you will have to start it manually using ant tasks or a console.

Configuration

Several parameters can be configured using a JMX console.

Configuration

Name	Type	Description	Default
streamingEnabled	boolean	send client side requests using HTTP streaming	false
jettyConnectorClassName	String	Jetty connector class name	org.mortbay.nio.SelectChannelConnector
jettyThreadPoolSize	int	thread pool size for server side requests	255
maxConnectionsPerHost	int	max number of simultaneous connections to a given host	32
maxTotalConnections	int	max number of total simultaneous connections	256

XBean deployment

You can deploy Service Units containing a file named xbean.xml for activating consumer and provider endpoints.

This xml file should respect the given syntax, though this is a spring based xml configuration file from where all beans of class HttpEndpoint are retrieved.
See a full example here. Note that you have to define the http namespace with

<beans xmlns:http="http://servicemix.apache.org/http/1.0">
    ...
</beans>

Any numbers of endpoints can be specified in the xbean.xml file.

Consumer endpoint

A consumer endpoint is a server-side http endpoint that will consume plain HTTP, or HTTP+SOAP requests and send them into the NMR to a given JBI endpoint, which is called the proxied endpoint.

Following is an example of an http consumer endpoint.

<http:endpoint service="test:MyConsumerService"
               endpoint="myConsumer"
               role="consumer" 
               locationURI="http://localhost:8192/Service/"
               defaultMep="http://www.w3.org/2004/08/wsdl/in-out" />

Consumer endpoint attributes

Name	Type	Description	Required
service	QName	the service name of the proxied endpoint	yes
endpoint	String	the endpoint name of the proxied endpoint	yes
interfaceName	QName	the interface name of the proxied endpoint
targetService	QName	the service name of the target endpoint	no (defaults to the service attribute)
targetEndpoint	String	the endpoint name of the target endpoint	no (defaults to the endpoint attribute)
targetInterfaceName	QName	the interface name of the target endpoint
role	String	must be 'consumer'	yes
locationURI	URI	the http url where this proxy endpoint will be exposed	yes
defaultMEP	URI	the default MEP uri to use	no
defaultOperation	QName	the default operation name to set on the JBI exchange. if not set, it defaults to the QName of the root xml element	no
soap	boolean	if set, the component will parse the soap requests and send the content into the NMR	no (defaults to false)
soapVersion	string	can be set to '1.1' to force the use of SOAP 1.1 messages	no
wsdlResource	Spring resource	if set, the wsdl will be retrieved from the given Spring resource	no
authMethod	string	HTTP authentication method to use, e.g. basic	no

The locationUri is usually something like *http://0.0.0.0:8192/jbi/Service*
The 0.0.0.0 IP address binds the server socket to all networks that the host
is in. If you use localhost, you will only be able to access the URL from
the same computer.

If you deploy your service unit to a ServiceMix Web application in Tomcat, the URLs of your services will be rewritten. For instance, a service with an XBean file specifying the service location URI:

http://0.0.0.0:8192/MyService

... will be published at:

http://url.to.your.servicemix-web/jbi/MyService

... instead.

The targetService, targetEndpoint and targetInterfaceName attributes can be used to specify the routing method to use (routing by interface, service or endpoint) and is also useful to allow several proxy endpoints to be created for the same JBI endpoint. For example to create an HTTP only endpoint and an HTTP+SOAP endpoint, both http endpoints will have the same targetEndpoint and targetService, but they must have different endpoint names.

Provider endpoint

A provider endpoint is a client-side jbi endpoint which can receive requests from the NMR and send them to a given url where the service is provided.

Here is an example of an http provider endpoint:

<http:endpoint service="test:MyProviderService"
               endpoint="myProvider"
               role="provider" 
               locationURI="http://localhost:8192/Service/"
               wsdlResource="classpath:provider.wsdl" />

Provider endpoint attributes

Name	Type	Description	Required
service	QName	the service name of the exposed jbi endpoint	yes
endpoint	String	the endpoint name of the exposed jbi endpoint	yes
interfaceName	QName	the interface name of the exposed jbi endpoint	no
role	String	must be 'provider'	yes
locationURI	URI	the http url of the target service	yes
soap	boolean	if set, the component will parse the soap requests and send the content into the NMR	no (defaults to false)
soapAction	String	the SOAPAction header to send when invoking the web service	no (defaults to "")
wsdlResource	Spring resource	if set, the wsdl will be retrieved from the given Spring resource	no

It is important to note that you need to include the classpath element in your xbean.xml if you are deploying the HTTP Provider in a service unit so that the wsdlResource can correctly find the classpath element. Also you need to ensure that the service name and endpoint match the service and port elements of the WSDL that you wish to use to correctly return WSDL for the endpoint, remembering that the service name will use the targetNamespace for the WSDL.

Basic authentication configuration

The provider endpoint supports basic authentication.

Basic authentication credentials are passed in plain text across the network. Please use additional encryption for better security, or use a stronger mechanism other than basic authentication.

Basic authentication for a servicemix-http provider can be setup as follows:

<http:endpoint service="testBasicAuth:MyProviderService"
  endpoint="myProvider"
  role="provider"
  locationURI="https://localhost:8193/Service/">
  <http:basicAuthentication>
    <http:basicAuthCredentials username="testuser" password="testpass" />
  </http:basicAuthentication>
</http:endpoint>

... and for a servicemix-http consumer:

<http:endpoint service="testBasicAuth:MyConsumerService"
  endpoint="myConsumer"
  role="consumer"
  targetService="..."
  authMethod="basic"
  locationURI="https://localhost:8193/Service/">
</http:endpoint>

BasicAuthCredentials attributes

Name	Type	Description	Required
username	String	Authentication username
password	String	Authentication password

SSL configuration

Both consumer and provider endpoints support SSL.

SSL parameters can be provided using the following syntax:

<http:endpoint service="testSsl:MyConsumerService"
  endpoint="myConsumer"
  role="consumer" 
  locationURI="https://localhost:8193/Service/"
  defaultMep="http://www.w3.org/2004/08/wsdl/in-out">
  <http:ssl>
    <http:sslParameters keyStore="classpath:org/apache/servicemix/http/server.keystore"
    keyStorePassword="password"/>
  </http:ssl>
</http:endpoint>

<http:endpoint service="testSsl:MyProviderService"
  endpoint="myProvider"
  role="provider" 
  locationURI="https://localhost:8193/Service/">
  <http:ssl>
    <http:sslParameters keyStore="classpath:org/apache/servicemix/http/server.keystore"
      keyStorePassword="password"
      trustStore="classpath:org/apache/servicemix/http/client.keystore"
      trustStorePassword="password"/>
  </http:ssl>
</http:endpoint>

SSL attributes

Name	Type	Description	Required
keyPassword	String	key password	Defaults to keyStorePassword
keyStore	URL	url to access the key store	Yes (defaults to system property 'javax.net.ssl.keyStore')
keyStorePassword	String	the password to access the keystore	Yes (defaults to system property 'javax.net.ssl.keyStorePassword')
keyStoreType	String	type of the key store	JKS
trustStore	URL	url to access the trust store
trustStorePassword	String	the password to access the trust store	If trustStore is specified, defaults to system property 'javax.net.ssl.trustStorePassword'
trustStoreType	String	type of the trust store	JKS
protocol	String	standard name of the requested secure socket protocol	TLS
algorithm	String	algorithm used for key management	SunX509
wantClientAuth	boolean	configures the socket for consumer endpoints to accept client side authentication	false
needClientAuth	boolean	configures the socket for consumer endpoints to require client side authentication	false

WSDL Deployment

In addition to xbean based deployment, the component accepts WSDL-based deployment.
The service unit may contain any number of WSDL files, each one being parsed and activating the specified endpoints.
To retrieve the necessary information from the wsdl, the component can recognize a jbi extension, in addition to the standard http and soap bindings, which specified the role of the component and the default MEP to use for JBI exchanges.

Here is an example of a WSDL:

<definitions name='Consumer' 
             targetNamespace='http://http.servicemix.org/Test' 
             xmlns:tns='http://http.servicemix.org/Test' 
             xmlns:http='http://schemas.xmlsoap.org/wsdl/http/' 
             xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' 
             xmlns='http://schemas.xmlsoap.org/wsdl/'
             xmlns:jbi='http://servicemix.org/wsdl/jbi/'>

    <portType name='ConsumerInterface'>
    </portType>

    <binding name='ConsumerSoapBinding' type='tns:ConsumerInterface'>
        <soap:binding transport="http"/>
    </binding>

    <binding name='ConsumerHttpBinding' type='tns:ConsumerInterface'>
        <http:binding verb="POST"></http:binding>
    </binding>

    <service name='ConsumerInOnly'>
        <port name='TestEndpoint' binding='tns:ConsumerSoapBinding'>
            <soap:address location="http://localhost:8192/InOnly"/>
            <jbi:endpoint role="consumer" defaultMep='in-only'/>
        </port>
    </service>

    <service name='ConsumerInOut'>
        <port name='TestEndpoint' binding='tns:ConsumerHttpBinding'>
            <http:address location="http://localhost:8192/InOut"/>
            <jbi:endpoint role="consumer" defaultMep='in-out'/>
        </port>
    </service>
    
</definitions>

Lightweight mode

The servicemix-http component can also be configured in a spring/xbean configuration file, for use in an embedded ServiceMix.
Here is an example of such a configuration:

<sm:activationSpec>
  <sm:component>
    <http:component>
      <http:endpoints>
        <http:endpoint service="test:dummy"
                       endpoint="dummy"
                       role="consumer" 
                       soap="true"
                       locationURI="http://localhost:8192/Service/"
                       defaultMep="http://www.w3.org/2004/08/wsdl/in-out" />

        <http:endpoint service="test:MyProviderService"
                       endpoint="myProvider"
                       role="provider" 
                       locationURI="http://localhost:8192/Service/" />
      </http:endpoints>
    </http:component>
  </sm:component>
</sm:activationSpec>

Classpath issues when embedding servicemix-http component

When using the servicemix.xml configuration file to create http endpoints, you must include the servicemix-http-xxx.jar in your classpath.
You will find this file inside the component installer (./components/servicemix-http-xxx.zip).
Failing this, an IllegalArgumentException will be thrown with the following message:
Component name: xxxxxx is bound to an object which is not a JBI component, it is of type: javax.xml.namespace.QName

Accessing WSDLs

WSDLs for consumer endpoints are retrieved using the following method:

for a WSDL based deployed endpoint, the WSL will be used as is
for an XBean based deployed endpoint, the WSDL will be retrieved from the wsdlResource attribute
if this information is not provided, the component will try to generate a WSDL by retrieving the target endpoint WSDL and adding the relevant informations to it.

WSDLs are accessible with the standard '?wsdl' query string.

For example, the WSDL for the consumer endpoint seen in the 'WSDL Deployment' section will be available at
http://localhost:8192/InOnly/?wsdl

You can also browse the list of available services on a given port:

http://localhost:8192/

WS-Addressing

When used on a SOAP consumer endpoint, servicemix-http handles the WS-Adressing Action and To headers.

wsa:Action

The wsa:Action header can be used to specify the target interface name and operation to use for the JBI exchange.

The header uses the following syntax:

[target namespace][delimiter][interface name][delimiter][operation name]

where:

[delimiter] is ":" when the [target namespace] is a URN, otherwise "/".
[target namespace] is the namespace of the interface.
[interface name] is the name of the interface.
[operation name] is the name of the operation.

For example, the following header

<wsa:Action>http://example.com/stockquote/StockQuoteInterface/GetLastTradePrice</wsa:Action>

will be used to address the JBI exchange with the following properties:

interface name: {http://example.com/stockquote\}StockQuoteInterface
operation name: {http://example.com/stockquote\}GetLastTradePrice

wsa:To

The wsa:To header specifies the target JBI service name and endpoint name.