WSO2 Carbon Transports Catalog

WSO2 Carbon Transports Catalog

Describes all the transports available on the WSO2 ESB including the optional transports. This guide also contains how to configure each and every transport.

Contents

Introduction

WSO2 Carbon is the base platform on which all WSO2 Java products are developed. Built on OSGi, Carbon encapsulates all major SOA functionality such as data services, routing, mediation, transformation, business process management, rules, security, caching, throttling and monitoring. With WSO2 Carbon these capabilities are no longer tied to individual products. Rather, they are made available as a collection of highly reusable and easily maintainable components.

WSO2 Carbon supports a variety of transports which makes Carbon based products capable of receicing and sending messages over a multitude of transport and application level protocols. Transport management is therefore one of the most crucial functionalities of WSO2 Carbon. This functionality is implemented mainly in the Carbon core component which combines with a set of transport specific components to load, enable, manage and persist transport related functionality and configurations.

The purpose of this document is to introduce the set of transports supports by WSO2 Carbon and formally describe how each transport can be configured and setup for a particular deployment scenario. Configuration parameters associated with each transport are discussed in detail and samples will be referred to where appropriate.

Documentation Conventions

WSO2 Carbon Transports Architecture

All transports currently supported by WSO2 Carbon are directly or indirectly based on the Apache Axis2 transports framework. This framework provides two main interfaces that each transport implementation must implement.

Because each transport implementation has to implement the above two interfaces, each transport generally contains a transport receiver/listener implementation and a transport sender implementation. Axis2 transport framework enables the user to configure, enable and manage transport listeners and senders independently of each other. For example one may enable only the JMS transport sender without having to enable JMS transport listener. WSO2 Carbon provides the user the same capability.

Configuring and Enabling WSO2 Carbon Transports

There are two methods to globally configure and enable transports in WSO2 Carbon or any Carbon based solution.

Globally enabled and configured transports will effect all the services deployed on the Carbon instance.

Using the axis2.xml File

WSO2 Carbon and all Carbon based products ship with a configuration file named axis2.xml. This XML configuration file can be found at $CARBON_HOME/conf directory. This is similar to the axis2.xml file that ships with Apache Axis2 and Apache Synapse. It contains the global configuration for WSO2 Carbon and the Carbon based products. The axis2.xml configuration generally includes configuration details for modules, phases, handlers, global configuration parameters and transports. The elements <transportReceiver> and <transportSender> are used to configure transport receivers and senders respectively. If you open up an axis2.xml file that comes with WSO2 Carbon or any Carbon based product in a text editor, you will see that some transports are already configured and enabled by default, including the HTTP and HTTPS transports.

The HTTP transport receiver configuration would be something similar to the following.

  <transportReceiver name="http" class="org.wso2.carbon.core.transports.http.HttpTransportListener">
      <parameter name="port">9763</parameter>
  </transportReceiver>

The 'name' and 'class' attributes of the <transportReceiver> element are mandatory and they should indicate a unique name for the transport receiver and the transport receiver implementation class respectively. Configuration parameters for the transport receiver can be specified using <parameter> elements which should be included as child elements of the <transportReceiver> element. In the above example we have defined one parameter named 'port' for the HTTP transport receiver.

Similarly <transportSender> elements can be used to configure and enable transport senders in WSO2 Carbon. Given below is the HTTP transport sender configuration that comes with WSO2 Carbon by default. It contains three parameters.

  <transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
      <parameter name="PROTOCOL">HTTP/1.1</parameter>
      <parameter name="Transfer-Encoding">chunked</parameter>

      <parameter name="OmitSOAP12Action">true</parameter>
  </transportSender>

Please be aware that axis2.xml file will be loaded to the memory only during server startup. Therefore any changes made to the file while the server is up and running has no effect. In such cases the server must be restarted for the changes to take effect. Also one need to keep in mind the fact that simply having <transportReceiver> and <transportSender> elements in the axis2.xml file causes those transports to be loaded and activated during server startup. Therefore any dependency jars required by those transport implementations must be included in the server classpath to prevent the server from running into exceptions at startup. In addition to that, an inaccurate transport configuration (eg: a wrong parameter value) might cause the transport to be not enabled properly.

This method of configuration is mainly intendedd for advanced users.

Using the WSO2 Carbon Management Console

As an alternative to the traditional axis2.xml file based configuration method, one might use the WSO2 Carbon Management Console to manage transport receivers and senders. (Note: Earlier versions of WSO2 Carbon did not enable the user to manage transport 'senders' through the management console. This functionality was first intriduces in WSO2 Carbon 2.0) Carbon Management Console loads transport configurations from the embedded registry and any changes made to the configurations through the UI will also be saved back into the registry. To manage transports from the Management Console the you must first login to the server management console. Then click on 'Transports' under the 'Manage' menu to the left of the screen. This will take you to the 'Transport Management' home page from where you can configure, enable or disable individual transport receivers and senders. More information on using the 'Transport Management' home page can be found by clicking on the 'Help' link at the top of the 'Transport Management' home page.

As of WSO2 Carbon version 2.0, the management console also allows adding new parameters to the transport configurations. Also note that Carbon Management Console does not allow the user to disable HTTP, HTTPS transports. This is because those transports are required by the management console and all the related administrative services.

When a transport is enabled from the management console, its configuration will be saved in the registry and will be loaded automatically during the next server startup. However keep in mind that transport configurations specified in the axis2.xml get higher priority over configurations stored in the registry. Therefore if the same transport is enabled in the axis2.xml as well as in the registry, transport configuration in the axis2.xml will be loaded and activated.

This method of configuration is mainly intended for relatively novice users. However it is very useful even for advanced users because it enables one to try out different transport settings without having to restart the server many times.

Configuring Servlet Transports in the Standalone Mode Using the transports.xml File

In addition to the two methods discussed above there is a third method to globally configure transport RECEIVERS in Carbon which works ONLY when Carbon is running in the standalone mode (ie no external servelet container is being used to deploy Carbon). By default WSO2 Carbon and all Carbon based products run in the standalone mode and hence it is important that users be aware of this configuration method.

When Carbon is running in the standalone mode one could use the $CARBON_HOME/conf/transports.xml file to specify transport receiver configurations. By default you will find the HTTP and HTTPS servlet transports configured in this file. The XML syntax to configure transports in transports.xml file is similar to the syntax used in the axis2.xml file, with only difference being the <transport> element taking the place of <transportReceiver> element. The default HTTP receiver configuration specified in the transports.xml file is given below.

  <transport name="http" class="org.wso2.carbon.server.transports.http.HttpTransport">
      <parameter name="port">9763</parameter>
      <parameter name="maxHttpHeaderSize">8192</parameter>
      <parameter name="maxThreads">150</parameter>
      <parameter name="minSpareThreads">25</parameter>
      <parameter name="maxSpareThreads">75</parameter>
      <parameter name="enableLookups">false</parameter>
      <parameter name="disableUploadTimeout">false</parameter>
      <parameter name="clientAuth">false</parameter>
      <parameter name="maxKeepAliveRequests">100</parameter>
      <parameter name="acceptCount">100</parameter>
      <parameter name="compression">force</parameter>
      <parameter name="compressionMinSize">2048</parameter>
      <parameter name="noCompressionUserAgents">gozilla, traviata</parameter>
      <parameter name="compressableMimeType">
          text/html,text/javascript,application/x-javascript,application/javascript,application/xml,text/css,application/xslt+xml,text/xsl,image/gif,image/jpg,image/jpeg
      </parameter>
  </transport>

However there is a fundamental difference between transports configured in axis2.xml and transports configured in transports.xml. Transport receivers configured in transports.xml will be loaded through a special Transport Manager implementation in Carbon. Therefore the classes specified in the <transport> element must implement the interface org.wso2.carbon.server.transports.Transport. Currently only the default servlet transports of Carbon can be configured from the transports.xml file.

Configuring Transports at Service Level

WSO2 Carbon and Carbon based products enable the user to configure transports at service level. Transports configured at the service level will effect individual services and not all the services deployed on the Carbon instance. Some transport implementations such as JMS and FIX mandate configuring certain transport parameters at service level.

Service level transport configuration is performed by editing the service.xml file associated with each service. When dealing with proxy services (for example in WSO2 ESB) using the Carbon's proxyadmin component, service level transport parameters should be specified in the proxy service configuration by using the provided proxy service management tools in the Carbon management console.

WSO2 Carbon Transports

As of Carbon v2.0 the following transport implementations are supported.

The remainder of this document discusses these transport implementations in detail, highlighting the configuration parameters associated with them.

HTTP Servlet Transport Implementation

The transport receiver implementation of the Carbon HTTP transport is available in the Carbon core component. The transport sender implementation comes from the Apache Axis2 transport module. This transport is shipped with WSO2 Carbon and all WSO2 Carbon based products. All Carbon based products except for WSO2 ESB use this transport as the default HTTP transport. The two classes which implement the listener and sender APIs are org.wso2.carbon.core.transports.http.HttpTransportListener and org.apache.axis2.transport.http.CommonsHTTPTransportSender respectively. It is important to note that this is a blocking HTTP transport implementation, meaning that I/O threads get blocked while received messages are processed completely by the underlying Axis2 engine.

Transport Receiver Parameters:

Parameter Name Description Requried Possible Values Default Value
port The port number on which this transport receiver should listen for incoming messages. Yes A positive integer less than 65535
proxyPort When used this transport listener will accept messages arriving through a HTTP proxy server which listenes on the specified proxy port. Apache mod_proxy should be enabled on the proxy server. All the WSDLs generated will contain the proxy port value as the listener port. No A positive integer less than 65535

When using org.wso2.carbon.core.transports.http.HttpTransportListener as the transport receiver implementation, HTTP servlet transport should be configured in the $CARBON_HOME/conf/transports.xml file. The transport class that should be specified in the transports.xml file is org.wso2.carbon.server.transports.http.HttpTransport. This servlet transport implementation can be further tuned up using the following parameters.

Parameter Name Description Requried Possible Values Default Value
port The port over which this transport receiver will listen for incoming messages. Yes A positive integer less than 65535
proxyPort When used this transport listener will accept messages arriving through a HTTP proxy server which listenes on the specified proxy port. Apache mod_proxy should be enabled on the proxy server. All the WSDLs generated will contain the proxy port value as the listener port. No A positive integer less than 65535
maxHttpHeaderSize The maximum size of the HTTP request and response header in bytes. No A positive integer 4096
maxThreads The maximum number of worker threads created by the receiver to handle incoming requests. This parameter largely determines the number of concurrent connections that can be handled by the transport. No A positive integer 40
enableLookups Use this parameter to enable DNS lookups in order to return the actual host name of the remote client. Disabling DNS lookups at transport level generally improves performance. No true, false true
disableUploadTimeout This flag allows the servlet container to use a different, longer connection timeout while a servlet is being executed, which in the end allows either the servlet a longer amount of time to complete its execution, or a longer timeout during data upload. No true, false true
clientAuth Set to true if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to want if you want the SSL stack to request a client Certificate, but not fail if one isn't presented. A false value (which is the default) will not require a certificate chain unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication. No true, false, want false
maxKeepAliveRequests The maximum number of HTTP requests which can be pipelined until the connection is closed by the server. Setting this attribute to 1 will disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining. Setting this to -1 will allow an unlimited amount of pipelined or keep-alive HTTP requests. No -1 or any positive integer 100
acceptCount The maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. No A positive integer 10
compression Use this parameter to enable content compression and save server bandwidth. No on, off, force off
noCompressionUserAgents Indicate a list of regular expressions matching user-agents of HTTP clients for which compression should not be used, because these clients, although they do advertise support for the feature, have a broken implementation. No A comma separated list of regular expressions empty string
compressableMimeType Use this parameter to indicate a list of MIME types for which HTTP compression may be used. No A comma separated list of valid mime types text/html,text/xml,text/plain

This is only a subset of all the supported parameters. The servlet HTTP transport uses the org.apache.catalina.connector.Connector implementation from Apache Tomcat. So the servlet HTTP transport actually accepts any parameter accepted by the connector implementation. Please refer Apache Tomcat connector configuration reference for more information and a complete list of supported parameters.

Transport Sender Parameters:

Parameter Name Description Requried Possible Values Default Value
PROTOCOL The version of HTTP protocol to be used for outgoing messages. No HTTP/1.0, HTTP/1.1 HTTP/1.1
Transfer-Encoding Effective only when the HTTP version is 1.1 (ie the value of the PROTOCOL parameter should be HTTP/1.1). Use this parameter to enable chunking support for the transport sender. No chunked Not Chunked
SocketTimeout The socket timeout value in milliseconds, for out bound connections. No A positive integer 60000 ms
ConnectionTimeout The connection timeout value in milliseconds, for out bound connections. No A positive integer 60000 ms
OmitSOAP12Action Set this parameter to 'true' if you need to disable the soapaction for SOAP 1.2 messages. No true, false false

HTTPS Servlet Transport Implementation

Similar to the HTTP transport described above this transport too consists of a receiver implementation which comes from the Carbon core component and a sender implementation which comes from the Apache Axis2 transport module. In fact this transport uses the exact same transport sender implementation as the HTTP transport. So the two classes that should be specified in the configuration are org.wso2.carbon.core.transports.http.HttpsTransportListener and org.apache.axis2.transport.http.CommonsHTTPTransportSender for the receiver and sender in the specified order. The configuration parameters associated with the receiver and the sender are same as in the case of HTTP transport. Note that this is also a blocking transport implementation.

However when using the org.wso2.carbon.core.transports.http.HttpsTransportListener class as the receiver implementation we need to specify the servlet HTTPS transport configuration in the transports.xml file. The class that should be specified as the transport implementation is org.wso2.carbon.server.transports.http.HttpsTransport. In addition to the configuration parameters supported by the HTTP servlet transport, HTTPS servlet transport supports the following configuration parameters.

Parameter Name Description Requried Possible Values Default Value
sslProtocol Transport level security protocol to be used No TLS, SSL TLS
keystore Path to the keystore which should be used for encryption/decryption Yes A valid file path to a keystore file
keypass Password to access the specified keystore Yes A valid password

Similar to the servlet HTTP transport, this transport is also based on Apache Tomcat's connector implementation. Please refer Tomcat connector configuration reference for a complete list of supported parameters.

HTTP-NIO Transport Implementation

HTTP-NIO transport is actually a module of the Apache Synapse project. Apache Synapse as well as WSO2 ESB ship the HTTP-NIO transport as the default HTTP transport implementation. The two classes that implement the receiver and sender APIs are org.apache.synapse.transport.nhttp.HttpCoreNIOListener and org.apache.synapse.transport.nhttp.HttpCoreNIOSender respectively. These classes are available in the jar file named synapse-nhttp-transport.jar. This non-blocking transport implementation is one of the secrets behind the blistering performance figures of Apache Synapse and WSO2 ESB. The transport implementation is based on Apache HTTP Core - NIO and uses a configurable pool of non blocking worker threads to grab incoming HTTP messages off the wire.

Transport Receiver Parameters:

Parameter Name Description Requried Possible Values Default Value
port The port on which this transport receiver should listen for incoming messages. No A positive integer less than 65535 8280
non-blocking Setting this parameter to true is vital for reliable messaging and a number of other scenarios to work properly. Yes true
bind-address The address of the interface to which the transport listener should bind. No A host name or an IP address 127.0.0.1
hostname The host name of the server to be displayed in service EPRs, WSDLs etc. This parameter takes effect only when the WSDLEPRPrefix parameter is not set. No A host name or an IP address localhost
WSDLEPRPrefix A URL prefix which wil be added to all service EPRs and EPRs in WSDLs etc. No A URL of the form <protocol>://<hostname>:<port>/

Transport Sender Parameters:

Parameter Name Description Requried Possible Values Default Value
http.proxyHost If the outgoing messages should be sent through an HTTP proxy server use this parameter to specify the target proxy. No A host name or an IP address
http.proxyPort The port through which the target proxy accepts HTTP traffic. No A positive integer less than 65535
http.nonProxyHosts Tthe list of hosts to which the HTTP traffic should be sent directly without going through the proxy. No A list of host names or IP addresses separated by '|'
non-blocking Setting this parameter to true is vital for reliable messaging and a number of other scenarios to work properly. Yes true

HTTPS-NIO Transport Implementation

HTTPS-NIO transport is also a module that comes from the Apache Synapse code base. The receiver class is named org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener whereas the sender class is named org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender. As far as the actual implementation of the transport is concerened these two classes simply extend the HTTP-NIO implementation by adding SSL support to it. Therefore they support all the configuration parameters supported by the HTTP-NIO receiver and sender. In addition to that, both HTTPS-NIO listener and the HTTPS-NIO sender support the following two parameters. The above mentioned classes are available in the synapse-nhttp-transport.jar bundle.

Transport Prameters (Common to both receiver and the sender):

Parameter Name Description Requried Possible Values Default Value
keystore The keystore to be used by the receiver or the sender should be specified here along with its related parameters as an XML fragment. The path to the keystore file, its type and the passwords to access the keystore should be stated in the XML. The keystore would be used by the transport to initialize a set of key managers. Yes
<parameter name="keystore">
    <KeyStore>
        <Location>lib/identity.jks</Location>
        <Type>JKS</Type>
        <Password>password</Password>
        <KeyPassword>password</KeyPassword>
    </KeyStore>
</parameter>
truststore The trust store to be used by the receiver or the sender should be specified here along with its related parameters as an XML fragment. The location of the trust store file, its type and the password should be stated in the XML body. The truststore is used by the transport to initialize a set of trust managers. Yes
<parameter name="truststore">
    <TrustStore>
        <Location>lib/identity.jks</Location>
        <Type>JKS</Type>
        <Password>password</Password>
    </TrustStore>
</parameter>
                        

MailTo Transport Implementation

The polling MailTo transport supports sending messages (E-Mail) over SMTP and receiving messages over POP3 or IMAP. This transport implementation is available as a module of the WS-Commons Transports project. The receiver and sender classes that should be included in the Carbon configuration to enable the MailTo transport are org.apache.axis2.transport.mail.MailTransportListener and org.apache.axis2.transport.mail.MailTransportSender respectively. The jar consisting of the transport implementation is named axis2-transport-mail.jar.

The mail transport receiver should be configured at service level. That is each service configuration should explicitly state the mail transport receiver configuration. This is required to enable different services to receive mails over different mail accounts and configurations. However transport sender is generally configured globally so that all services can share the same transport sender configuration.

Service Level Transport Receiver Parameters:

The MailTo transport listener implementation can be configured by setting the parameters described in JavaMail API documentation. For IMAP related properties refer the documentation for com.sum.mail.imap package. For POP3 properties please refer the documentation for com.sun.mail.pop3 package. Apart from the parameters describes in JavaMail API documentation, MailTo transport listener supports following transport parameters.

Parameter Name Description Requried Possible Values Default Value
transport.mail.Address The mail address from which this service should fetch incoming mails Yes A valid e-mail address
transport.mail.Folder The mail folder in the server from which the listener should fetchincoming mails. No A valid mail folder name (eg: inbox) inbox folder if that is available or else the root folder
transport.mail.Protocol The mail protocol to be used to receive messages No pop3, imap imap
transport.mail.PreserveHeaders A comma separated list of mail header names that this receiver should preserve in all incoming messages. No A comma separated list
transport.mail.RemoveHeaders A comma separated list of mail header names that this receiver should remove from incoming messages No A comma separated list
transport.mail.ActionAfterProcess Action to perform on the mails after processing them No MOVE, DELETE DELETE
transport.mail.ActionAfterFailure Action to perform on the mails after a failure occurs while processing them No MOVE, DELETE DELETE
transport.mail.MoveAfterProcess Folder to move the mails after processing them Required if ActionAfterProcess is MOVE A valid mail folder name
transport.mail.MoveAfterFailure Folder to move the mails after encountering a failure Required if ActionAfterFailure is MOVE A valid mail folder name
transport.mail.ProcessInParallel Whether the receiver should incoming mails in parallel or not (works only if the mail protocol supports that - eg: IMAP) No true, false false
transport.ConcurrentPollingAllowed Whether the receiver should poll for multiple messages concurrently No true, false false
transport.mail.MaxRetryCount Maximum number of retry operations to be performed when fetching incoming mails Yes A positive integer
transport.mail.ReconnectTimeout The reconnect timeout in milliseconds to be used when fetching incoming mails Yes A positive integer

Global Transport Sender Parameters:

For a list of parameters supported by the MailTo transport sender please refer the API documentation for JavaMail com.sun.mail.smtp package. In addition to the parameters described there the MailTo transport sender supports following parameters.

Parameter Name Description Requried Possible Values Default Value
transport.mail.SMTPBccAddresses If one or more e-mail addresses need to be specified as BCC addresses for outgoing mails, this parameter can be used. No A comma separated list of e-mail addresses
transport.mail.Format Format of the outgoing mail No Text, Multipart Text

Please refer WSO2 ESB sample 256 on how to use the MailTo transport with ESB proxy services.

JMS Transport Implementation

JMS (Java Message Service) transport implementation also comes from the WS-Commons Transports project. All the relevant classes are packed into the axis2-transport-jms-<version>.jar and the classes org.apache.axis2.transport.jms.JMSListener and org.apache.axis2.transport.jms.JMSSender act as the transport receiver and the sender respectively. The JMS transport implementation requires an active JMS server instance to be able to receive and send messages. We recommend using Apache ActiveMQ JMS server but other implementations such as Apache Qpid and Tibco are also supported. You also need to put the cliet jars for your JMS server in Carbon classpath. In case of Apache ActiveMQ you need to put the following jars in the classpath.

These jar files can be obtained by downloading the latest version of Apache ActiveMQ (v5.2.0 recommended). Extract the downloaded archive and find the required dependencies in the $ACTIVEMQ_HOME/lib directory. You need to copy these jar files over to $CARBON_HOME/repository/components/lib directory for Carbon to be able to pick them up at runtime.

Configuration parameters for JMS receiver and the sender are XML fragments that represent JMS connection factories. A typical JMS parameter configuration would look like this.

  <parameter name="myTopicConnectionFactory">
      <parameter name="java.naming.factory.initial">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
      <parameter name="java.naming.provider.url">tcp://localhost:61616</parameter>
      <parameter name="transport.jms.ConnectionFactoryJNDIName">TopicConnectionFactory</parameter>
      <parameter name="transport.jms.ConnectionFactoryType">topic</parameter>
  </parameter>

This is a bare minimal JMS connection factory configuration which consists of four connection factory parameters. JMS connection factory parameters are described in detail below.

JMS Connection Factory Parameters:

Parameter Name Description Requried Possible Values Default Value
java.naming.factory.initial JNDI initial context factory class. The class must implement the java.naming.spi.InitialContextFactory interface. Yes A valid class name
java.naming.provider.url URL of the JNDI provider Yes A valid URL
java.naming.security.principal JNDI Username No
java.naming.security.credentials JNDI password No
transport.Transactionality Desired mode of transactionality No none, local, jta none
transport.UserTxnJNDIName JNDI name to be used to require user transaction No java:comp/UserTransaction
transport.CacheUserTxn Whether caching for user transactions should be enabled or not No true, false true
transport.jms.SessionTransacted Whether the JMS session be transacted or not No true, false true if transactionality is 'local'
transport.jms.SessionAcknowledgement JMS session acknowledgement mode No AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED AUTO_ACKNOWLEDGE
transport.jms.ConnectionFactoryJNDIName The JNDI name of the connection factory Yes
transport.jms.ConnectionFactoryType Type of the connection factory No queue, topic queue
transport.jms.JMSSpecVersion JMS API version No 1.1, 1.0.2b 1.1
transport.jms.UserName The JMS connection username No
transport.jms.Password The JMS connection password No
transport.jms.Destination The JNDI name of the destination No Defaults to service name
transport.jms.DestinationType Type of the destination No queue, topic queue
transport.jms.DefaultReplyDestination JNDI name of the default reply destination No
transport.jms.DefaultReplyDestinationType Type of the reply destination No queue, topic Defaults to the type of the destination
transport.jms.MessageSelector Message selector implementation No
transport.jms.SubscriptionDurable Whether the connection factory is subscription durable or not No true, false false
transport.jms.DurableSubscriberName Name of the durable subscriber Yes if the subscription durable is turned on
transport.jms.PubSubNoLocal Whether the messages should be published by the same connection they were received No true, false false
transport.jms.CacheLevel JMS resource cache level No none, connection, session, consumer, producer, auto auto
transport.jms.ReceiveTimeout Time to wait for a JMS message during polling. Set this parameter value to a negative integer to wait indefinitely. Set to zero to prevent waiting. No Number of milliseconds to wait 1000 ms
transport.jms.ConcurrentConsumers Number of concurrent threads to be started to consume messages when polling. No Any positive integer - For topics this must be always 1 1
transport.jms.MaxConcurrentConsumers Maximum number of concurrent threads to use during polling. No Any positive integer - For topics this must be always 1 1
transport.jms.IdleTaskLimit The number of idle runs per thread before it dies out No Any positive integer 10
transport.jms.MaxMessagesPerTask The maximum number of successful message receipts per thread No Any positive integer - Use -1 to indicate infinity -1
transport.jms.InitialReconnectDuration Initial reconnection attempts duration in milliseconds No Any positive integer 10000 ms
transport.jms.ReconnectProgressFactor Factor by which the reconnection duration will be increased No Any positive integer 2
transport.jms.MaxReconnectDuration Maximum reconnection duration in milliseconds No 3600000 ms (1 hr)

JMS transport implementation has some parameters that should be configured at service level, ie in service.xml files of individual services.

Service Level JMS Configuration Parameters:

Parameter Name Description Requried Possible Values Default Value
transport.jms.ConnectionFactory Name of the JMS connection factory the service should use No A name of an already defined connection factory default
transport.jms.PublishEPR JMS EPR to be published in the WSDL No A JMS EPR

Please refer WSO2 ESB samples 250, 251, 252 and 253 on using the JMS transport in a number of very useful scenarios.

VFS Transport Implementation

VFS (Virtual File System) transport implementation is a module which belongs to the Apache Synapse project. Classes org.apache.synapse.transport.vfs.VFSTransportListener and org.apache.synapse.transport.vfs.VFSTransportSender implement the listener and sender APIs and the necessary classes can be found in the synapse-vfs-transport.jar file. Unlike the transports described previously, VFS transport does not have any global parameters to be configured. Rather, it has a set of service level parameters that needs to be specified for each service. VFS transport implementation is mainly used and mostly effective in WSO2 ESB.

The VFS transport implementation is based on Apache Commons VFS implementation. Therefore commons-vfs.jar file should be included in the Carbon classpath to enable the VFS transport.

VFS Service Level Parameters:

Parameter Name Description Requried Possible Values Default Value
transport.vfs.FileURI The file URL from where the input files should be fetched Yes A valid file URL of the form file://<path>
transport.vfs.ContentType Content type of the files transferred over the transport Yes A valid content type for the files (eg: text/xml)
transport.vfs.FileNamePattern If the VFS listener should read only a subset of all the files available in the specified file URI location this parameter can be used to select those files by name using a regular expression No A regular expression to select files by name (eg:.*\.xml)
transport.PollInterval The polling interval in milliseconds for the transport receiver to poll the file URI location No A positive integer
transport.vfs.ActionAfterProcess Action to perform over the files after processed by the transport No MOVE, DELETE DELETE
transport.vfs.ActionAfterFailure Action to perform over the files after processed by the transport No MOVE, DELETE DELETE
transport.vfs.MoveAfterProcess The location to move the files after processing Required if ActionAfterProcess is MOVE A valid file URI
transport.vfs.MoveAfterFailure The location to move the files after a failure occurs Required if ActionAfterFailure is MOVE A valid file URI
transport.vfs.ReplyFileURI The location to which reply files should be written by the transport No A valid file URI
transport.vfs.ReplyFileName The name for reply files written by the transport No A valid file name response.xml
transport.vfs.MoveTimestampFormat The pattern/format of the timestamps added to file names as prefixes when moving files (See the API documentation of java.text.SimpleDateFormat for details) No A valid timestamp pattern (eg: yyyy-MM-dd'T'HH:mm:ss.SSSZ)
transport.vfs.Streaming If files should be transferred in streaming mode or not No true, false false
transport.vfs.ReconnectTimeout Reconnect timeout value in seconds to be used in case of an error when transferring files No A positive integer 30 seconds
transport.vfs.MaxRetryCount Maximum number of retry attempts to carry out in case of errors No A positive integer 3
transport.vfs.Append When writing the response to a file, if the response should be appended to the response file this parameter should be set to true. By default the response file will be completely overwritten. No true, false false

Please refer WSO2 ESB sample 254 on how to use the VFS transport in real world applications.

TCP Transport Implementation

The TCP transport implementation is a fairly new addition to the Apache WS-Commons Transports project. Even though this transport is still in its early days, it is good enough to be used in production environments. The two classes that act as the transport listener and the sender are org.apache.axis2.transport.tcp.TCPServer and org.apache.axis2.transport.tcp.TCPTransportSender respectively. In order to use the transport axis2-transport-tcp.jar should be added to the Carbon classpath.

Transport Receiver Parameters:

Parameter Name Description Requried Possible Values Default Value
port The port on which the TCP server should listen for incoming messages No A positive integer less than 65535 8000
hostname The host name of the server to be displayed in WSDLs etc No A valid host name or an IP address

Transport Sender Parameters:

The TCP transport sender does not accept any configuration parameters as of now.

Local Transport Implementation

Apache Axis2's local transport implementation is used to make internal service calls and transfer data within the Axis2 instance. The class org.apache.axis2.transport.local.LocalTransportSender implements the sender API and the transport does not have a receiver implementation as of now. Local transport does not accept any configuration parameters as of now.

UDP Transport Implementation

The UDP transport implementation is also a rather newly added component to the Apache WS-Commons Transports project. Classes org.apache.axis2.transport.udp.UDPListener and org.apache.axis2.transport.udp.UDPSender implement the Axis2 transport listener and sender APIs respectively. The axis2-transport-udp.jar archive file contains these implementation classes.

FIX Transport Implementation

FIX (Financial Information eXchang) transport implementation is a module developed under the Apache Synapse project. This transport is mainly used with WSO2 ESB in conjunction with proxy services. Class org.apache.synapse.transport.fix.FIXTransportListener acts as the transport receiver whereas the org.apache.synapse.transport.fix.FIXTransportSender acts as the transport sender implementation. These classes can be found in the synapse-fix-transport.jar file. The transport implementation is based on Quickfix/J open source FIX engine and hence the following additional dependencies are required to enable the FIX transport.

Download Quickfix/J from here and in the distribution archive you will find all the dependencies listed above. Also please refer to Quickfix/J documentation on configuring FIX acceptors and initiators.

FIX transport does not support any global parameters. All the FIX configuration parameters should be specified at service level.

Service Level FIX Parameters:

Parameter Name Description Requried Possible Values Default Value
transport.fix.AcceptorConfigURL URL to the Quickfix/J acceptor configuration file (see notes below) Required for receiving messages over FIX A valid URL
transport.fix.InitiatorConfigURL URL to the Quickfix/J initiator configuration file (see notes below) Required for sending messages over FIX A valid URL
transport.fix.AcceptorLogFactory Log factory implementation to be used for the FIX acceptor (Determines how logging is done at the acceptor level) No console, file, jdbc Logging disabled
transport.fix.InitiatorLogFactory Log factory implementation to be used for the FIX acceptor (Determines how logging is done at the acceptor level) No console, file, jdbc Logging disabled
transport.fix.AcceptorMessageStore Message store mechanism to be used with the acceptor (Determines how the FIX message store is maintained) No memory, file, sleepycat, jdbc memory
transport.fix.InitiatorMessageStore Message store mechanism to be used with the initiator (Determines how the FIX message store is maintained) No memory, file, sleepycat, jdbc memory
transport.fix.ResponseDeliverToCompID If the reponse FIX messages should be delivered to a location different from the location the request was originated use this property to set the DeliverToCompID field of the FIX messages. No
transport.fix.ResponseDeliverToSubID If the reponse FIX messages should be delivered to a location different from the location the request was originated use this property to set the DeliverToSubID field of the FIX messages. No
transport.fix.ResponseDeliverToLocationID If the reponse FIX messages should be delivered to a location different from the location the request was originated use this property to set the DeliverToLocationID field of the FIX messages. No
transport.fix.SendAllToInSequence By default all received FIX messages (including responses) will be directed to the in sequence of the proxy service. Use this property to override that behavior. No true, false true
transport.fix.BeginStringValidation Whether the transport should validate BeginString values when forwrding FIX messages across sessions. No true, false true
transport.fix.DropExtraResponses In situation where the FIX recipient sends multiple responses per request use this parameter to drop excessive responses and use only the first one. No true, false false

Please refer WSO2 ESB samples 257 and 258 for more details on using the FIX transport in practice.

Future Work

Currently there is an effort to develop an SMS transport for Apache Axis2. Once this is completed and constributed to WS-Commons Transports it will be available for all WSO2 Carbon based products.