Working with Transports

A transport is responsible for carrying messages that are in a specific format. WSO2 ESB supports all the widely used transports including HTTP/s, JMS, and VFS, and domain-specific transports like FIX. This page describes the various methods for configuring and enabling transports in WSO2 Carbon and Carbon-based applications such as WSO2 ESB. 

Transports architecture

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

• org.apache.axis2.transport.TransportListener - Implementations of this interface specify how incoming messages are received and processed before handing them over to the Axis2 engine for further processing.
• org.apache.axis2.transport.TransportSender - Implementations of this interface specify how a message can be sent out from the Axis2 engine.

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. You configure, enable, and manage transport listeners and senders independently of each other. For example, you could enable just the JMS transport sender without having to enable the JMS transport listener.

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 <PRODUCT_HOME>/repository/conf/axis2 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. Some transports are already configured and enabled by default, including the HTTP and HTTPS transports.

A transport receiver configuration looks similar to the following:

<transportReceiver name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpListener">
      <parameter name="port">9280</parameter>
  </transportReceiver>

<transportResiever> has the following attributes and elements:

• name - A mandatory attribute which indicates a unique name for the transport receiver.
• class - A mandatory attribute which indicates the transport receiver implementation class.
• parameters - Configuration parameters for the transport receiver, such as the port in the example above. Parameters should be included as child elements of the <transportReceiver> element.

Similarly <transportSender> elements can be used to configure and enable transport senders in WSO2 Carbon. Following is the PassThrough transport sender configuration that comes with WSO2 Carbon by default:

<transportSender name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpSender">
      <parameter name="non-blocking" locked="false">true</parameter>
</transportSender>

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. Additionally, an inaccurate transport configuration (such as a wrong parameter value) might cause the transport not to be enabled properly.

Using the management console

As an alternative to the traditional axis2.xml file based configuration method, you can use the management console to manage transport receivers and senders. Any changes you make to transport configurations in the management console are saved in the embedded registry and take effect on the next server restart.

To access transports in the management console, click Transports under the Manage menu. The Transport Management screen allows you to configure, enable, or disable individual transport receivers and senders. For more information, see Configuring Transports and Enabling and Disabling Transports.

The management console also allows you to add new parameters to the transport configurations. It does not allow you to disable the HTTP and HTTPS transports, because these transports are required by the management console and all the related administrative services.

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

Configuring servlet transports in standalone mode using the catalina-server.xml file

In addition to the methods discussed above, you can globally configure transport receivers using the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file when the server is running in standalone mode (that is, the server is not running in a servlet container). By default, you will find the HTTP and HTTPS servlet transports configured in this file. The XML syntax to configure transports in the catalina-server.xml file is similar to the syntax used in the axis2.xml file, except the <transport> element takes the place of the <transportReceiver> element. The default HTTP receiver configuration specified in the catalina-server.xml file is as follows:

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

Transport receivers configured in catalina-server.xml will be loaded through a special Transport Manager implementation. Therefore, the classes specified in the <transport> element must implement the interface org.wso2.carbon.server.transports.Transport. Currently, only the default servlet transports can be configured from the catalina-server.xml file.

Configuring transports at the service level

WSO2 Carbon and Carbon based products allow the user to configure transports at the service level. Transports configured at the service level affect 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 the service level.

To configure a transport at the service level, you edit the service's XML file or specify the service-level transport parameters in the proxy service configuration in the management console. For more information, see Working with Services.