This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

FAQ

Owned by Rukshani Weerasinha (Unlicensed)
Last updated: Nov 27, 2016 by Former user (Deleted)
15 min read

 

General ESB Questions

What is WSO2 ESB?

WSO2 ESB is a fast, lightweight, open source Enterprise Service Bus implementation. It supports message routing, inter-mediation, transformation, logging, load balancing, fail over routing, task scheduling, eventing and much more.

What makes WSO2 ESB unique?

WSO2 ESB is fast and able to handle thousands of concurrent connections with constant memory usage. It comes with a rich set of mediators to support almost any integration scenario out of the box. It is also easily extensible and highly customizable. The feature-rich admin console makes it very easy to configure, control and monitor the ESB runtime.

What is the open source license of WSO2 ESB?

It is released under Apache Software License Version 2.0, one of the most business-friendly licenses available today.

How do I get WSO2 ESB?

Go to http://wso2.com/products/enterprise-service-bus/ and download the binary distribution, or click the link at the bottom of the page to access the source code. WSO2 ESB is distributed completely free of charge.

Does WSO2 ESB have performance comparisons with other popular ESBs?

Yes, the results of several rounds of performance comparisons are available in the following article: http://wso2.org/library/articles/2013/01/esb-performance-65.

Is their commercial support available for WSO2 ESB?

We are committed to ensuring that your enterprise middleware deployment is completely supported from evaluation to production. Our unique approach ensures that all support leverages our open development methodology and is provided by the very same engineers who build the technology. For more details and to take advantage of this unique opportunity, see WSO2 Support.

Can I get involved with the ESB development activities?

Not only you are allowed, but it is encouraged. You can start by subscribing to carbon-dev@wso2.org and architecture@wso2.org mailing lists. Feel free to provide ideas, feedback and help make our code better. You can also report bugs on https://wso2.org/jira/browse/ESBJAVA and submit patches. For more information on our mailing lists, refer to http://wso2.org/mail.

Core Carbon Questions

What are the technologies used underneath WSO2 ESB?

WSO2 ESB is built on top of WSO2 Carbon, an OSGi based components framework for SOA. It uses Apache Synapse (http://synapse.apache.org) as the underlying mediation engine. Java is the primary programming language used to develop WSO2 ESB.

What are the minimum requirements to run WSO2 ESB?

Refer to ESB system requirements.

What should I do if I get the following error when I try to start WSO2 ESB?
[ERROR] CARBON is supported only on JDK 1.7 and 1.8

You need to have Oracle JDK 1.7.*/1.8.* installed. You cannot start WSO2 ESB with Oracle JDK 1.6.* or lower. For more information, see Installation Prerequisites.

What makes WSO2 ESB fast and high-performant?

The mediation core of WSO2 ESB is designed to be completely asynchronous, non-blocking and streaming. It comes with a non-blocking HTTP transport adapter based on Apache HTTP Core-NIO, which is capable of handling a large number of concurrent connections. WSO2 ESB also uses Apache AXIOM, a StAX based XML infoset model, to process XML and SOAP. This enables WSO2 ESB to stream messages through the mediation engine without having to invoke slow XML processing routines for each and every message.

Does WSO2 ESB support clustering?

Yes, it supports clustered deployment. WSO2 ESB uses the Apache Axis2 clustering framework to support the following two clustering schemes:

  • Multicast based clustering
  • Well known addressing based clustering
In what occasions do I have to deploy a third-party library into WSO2 ESB?

When enabling a new transport you will have to deploy the libraries required by the transport implementation (eg: When enabling JMS you need to deploy the client libraries required to connect to your JMS broker)

When adding a custom mediator or a task, you may have to deploy the dependencies required by the custom code.

How do I deploy a third-party library into the ESB?

Copy any third-party jars into $ESB_HOME/repository/components/lib directory and restart the server. WSO2 ESB converts those jars to OSGi bundles and place them in <ESB_HOME>/repository/components/dropins directory.

Can I extend the management console UI to add custom UIs?

Yes, you can extend the management console easily by writing a custom UI component and simply deploying the OSGi bundle.

Can I use a primary user store to manage and authenticate WSO2 ESB users?

Yes you can connect WSO2 ESB with any primary user store implementation. The user store could be LDAP based, JDBC based or a custom developed user store. For more information, refer to User Management.

Does WSO2 ESB interop with a .net client/service?

Yes, it does with both. WSO2 ESB can be easily configured to bridge Java services with .NET clients and .NET services with Java clients.

Does WSO2 ESB support hessian binary web service protocol

Yes, it does.

I don't want some of the features that come with WSO2 ESB. Can I get rid of them?

Yes, WSO2 ESB is lean and allows you to maintain just the right set of features required at the time. Simply login to the ESB management console and uninstall any unwanted features from the list of Installed Features.

Can I add support for other language for the management console ?

Yes, WSO2 ESB comes with a UI framework which supports i18n (internationalization) which lets you to use a language of your choice for the management console.

Mediation-Related Questions

What is a proxy service?

A proxy service is a virtual service hosted on the ESB. It can accept requests from service clients, just like a real Web service. A proxy service can process requests and forward them to an actual Web service (back-end service) to be further processed. The responses coming back from the back-end service can be routed back to the original client. Proxy services are mostly used to expose an existing service over a different transport, format or QoS configuration.

Does WSO2 ESB have support for transactions?

Yes, it has support for distributed transaction, local JMS transactions, and distributed JMS transactions.

Where do I have to put my custom mediators in WSO2 ESB?

In the current version, you can place any non-OSGi custom mediators and class mediators in <ESB_HOME>/repository/components/libs and OSGi bundles in <ESB_HOME>/repository/components/dropins.

Where does WSO2 ESB load its configuration from?

WSO2 ESB reads its mediation configuration from a set of XML files located in the <ESB_HOME>/repository/deployment/server/synapse-configs/<node> directory. XML files are written in the Synapse configuration language. Any changes done to the configuration through the UI are saved back to the configuration files. (Configuration is also written to the registry by default).

Can I get the ESB to load mediation configuration from the registry?

Yes you can. The necessary steps are given in section, Working with the Registry .

What is a mediator?

A mediator is the basic message processing unit in the ESB. A mediator can take a message, carry out some predefined actions on it and output the modified message. WSO2 ESB ships with a range of mediators capable of carrying out various tasks on input messages.

  • Log mediator - Logs the input message.
  • Send mediator - Sends the input message to a given endpoint.
  • XSLT mediator - Transforms the input message using a given XSLT.
What is a sequence?

A sequence is an ordered list of mediators (a mediator chain). When a sequence is given a message, it will go through all the mediators in the sequence. A sequence can also handover messages to other sequences.

What is an Endpoint?

An endpoint is the entry point to a service, process, or a queue or topic destination. It defines the destination for a message.

Can Endpoints perform error handling?

Yes, see Endpoint Error Handling. 

What are local entries?

Local entries can be used to hold various configuration elements required by sequences and proxy services. Usually, they are used to hold WSDLs, XSDs, XSLT files etc. A local entry can contain XML content as well as plain text content and configured to load content from a remote file too.

How can a sequence refer to another sequence?

To refer to a sequence named foo use the sequence mediator as follows:

<sequence key="foo"/>

You can also refer to dynamic sequences saved in the registry by specifying the registry key to the sequence resource as follows:

<sequence key="gov:/dev/sequences/foo"/>

The above sequence mediator will load the sequence configuration from the resource at /dev/sequences/foo in the governance registry.

How does dynamic endpoints and sequences work?

Dynamic endpoints and sequences are just XML configuration bits saved in the registry. These configurations are loaded to the mediation configuration at runtime. Once loaded they will be cached for a specified duration in the memory. Once the cache is expired, it will be loaded again from the registry. Therefore, changes done to dynamic sequences and endpoints at runtime will take effect once the ESB reloads them after a cache timeout.

To use dynamic sequences and endpoints, the mediation registry must be included in the mediation configuration as follows:

<sequence key="foo"/> 
<registry xmlns="http://ws.apache.org/ns/synapse" provider="org.wso2.carbon.mediation.registry.WSO2Registry"> 
   <parameter name="cachableDuration">15000</parameter> 
</registry>

This configuration can be found in a file named registry.xml in $ESB_HOME/repository/conf/synapse-config directory by default. Note how the cache duration is set to 15000 ms (15s). This duration can be reduced or extended as necessary by editing the registry.xml file or through the configuration source editor in the UI.

How can I change the endpoint dynamically?

If you want to change the endpoint dynamically per each message, use a header mediator to calculate the new 'To' address.

<header name="To" expression="XPath to create the address dynamically"/>
I have heard of dynamic sequences and endpoints. Are there also dynamic proxy services?

WSO2 ESB does not support dynamic proxy services. But a proxy service may use a dynamic endpoint as the target endpoint and dynamic sequences as the in sequence and the out sequence. This effectively makes the entire proxy service dynamic.

How can I create load balance endpoint templates?

Load balance endpoint templates cannot be created in the user interface at present. However, you can create them using the source view as follows.

  1. Open the ESB management console and click Templates under Service Bus in the Main tab.
  2. Click Add Endpoint Template in the Templates page. Then click one one of the endpoint template types that will be displayed (e.g., Address Endpoint Template).
  3. Enter a name for the new template in the template page (Address Endpoint Template in this example) and click Switch to source view).

  4. Enter the following configuration in the source view.

    <template xmlns="http://ws.apache.org/ns/synapse" name="LBEndpointTemplate">
<parameter name="ep1Url"/> <parameter name="ep2Url"/> <parameter name="name"/> <parameter name="uri"/>
<endpoint name="$name">
<loadbalance algorithm="org.apache.synapse.endpoints.algorithms.RoundRobin">
<endpoint name="ep1"> <address uri="$ep1Url" /> </endpoint>
<endpoint name="ep2"> <address uri="$ep2Url" /> </endpoint>
</loadbalance> </endpoint></template>

  5. Click Save & Close. You will see the load balance endpoint template you created in the Templates window. This template can be used to create load balance endpoints as shown in the configuration below.

    <endpoint xmlns="http://ws.apache.org/ns/synapse" template="LBEndpointTemplate" name="LBSenderTmplEndpoint" uri="">
   <parameter name="ep1Url" value="http://localhost:9000/services/SimpleStockQuoteService"/>   <parameter name="ep2Url" value="http://localhost:9001/services/SimpleStockQuoteService"/>
</endpoint>
How can I implement a persistence mechanism within my mediation chain?

You have two options.

  • Use dbreport and dblookup mediators to persist the message into a database and look it up later from the database.
  • Use JMS transport in which you can use a JMS broker to persist the message.
I have some dynamic sequences which are loaded from the registry. What will happen to my ESB if the registry goes down or registry becomes unusable for a while?

If the dynamic sequences are loaded to the memory at least once, the ESB will continue to use the cached version of the sequence, as long as the registry is unreachable. A warning will be logged every time ESB attempts to load the sequence from the registry and fails. As soon as the registry comes back on-line, ESB will load the sequence from the registry.

What is the recommended approach for dealing with *.back files that are created when there is an error in an ESB artifact?

You can delete the *.back file manually from the file system once you fix the error in the artifact. If an artifact fails during the process of creating it via the management console, the artifact can be deleted via the management console and the *.back file that is created will be deleted automatically.

Note

If you upload an erroneous artifact through a CAR file, a *.back file will not be created even if the deployment fails.

How can you preserve a large CDATA block in WSO2 ESB?

In WSO2 ESB, all message that need to be built are parsed using AXIOM as the object model which relies on a standard StAX implementation library named Woodstox. When it comes to parsing CDATA sections there are few ambiguities in the StAX specification which result in multiple interpretations of what to do when non-coalescing mode is activated (javax.xml.stream.isCoalescing=false). What Woodstox adheres to when it comes to large CDATA sections is to break them up to several pieces based on the buffer size. This shouldn't be a problem because most clients should be able to handle multiple consecutive CDATA sections.

However when it becomes a problem, Woodstox can be configured to increase the size of the text segment it reads. By setting this value to the maximum Integer value, Woodstox will not break up the CDATA sections until it reaches the configured value.

To configure this, add the following entry to <ESB_HOME>/XMLInputFactory.properties file.

com.ctc.wstx.minTextSegment=2147483647

Transports-Related Questions

For full details on transports, see Working with Transports.

What are the transports supported by the WSO2 ESB?

For a complete list, see ESB Transports.

Do I need an external JMS broker for the JMS transport?

Yes, WSO2 ESB requires an external JMS broker like Apache ActiveMQ (http://activemq.apache.org).

Does WSO2 ESB support AMQP?

WSO2 ESB supports AMQP through its JMS transport. The JMS transport can be configured to connect to an AMQP broker as if it was connecting to a JMS broker. This functionality has been tested with Apache Qpid (http://qpid.apache.org) and RabbitMQ.

How can I change the host name in WSO2 ESB?

Edit parameter bind-address in http/https transport receiver to change the host name of WSO2 ESB. This hostname will be displayed on service endpoints and generated WSDLs.

I have several JMS connection factories defined under the JMS transport receiver in the axis2.xml. How can I get a particular proxy service to receive messages from one of those connection factories?

You can specify the preferred connection factory by adding the following parameter to the proxy service configuration.

<parameter name="transport.jms.ConnectionFactory">MyConnectionFactory</parameter>

Replace 'MyConnectionFactory' with the name of the appropriate connection factory. If the above parameter is not specified, proxy service will bind to the connection factory named 'default'.

Does WSO2 ESB support two way JMS scenario (request/response) ?

Yes, refer to sample 264, which demonstrates exactly the JMS request/response scenario.

What are the JMS brokers that work with WSO2 ESB?

Any JMS broker that provides JNDI support can be integrated with WSO2 ESB. The default configurations are for Apache ActiveMQ. WSO2 ESB has also been tested with IBM Websphere MQ, Swift MQ and JBOSS MQ.

What is the NHTTP transport?

This is the default HTTP transport used by WSO2 ESB. NHTTP stands for non-blocking HTTP. NHTTP transport uses the Java Non-blocking I/O API. This allows the NHTTP transport to scale into handling hundreds of connections without blocking the threads. The server worker threads used by the NHTTP transport do not get blocked on I/O until the ESB receives responses for the already forwarded requests. Therefore WSO2 ESB can accept more concurrent connections and requests than most HTTP server products.

What is the underlying HTTP library used by the NHTTP transport?

NHTTP transport uses the Apache Http Core NIO library (http://hc.apache.org/httpcomponents-core-ga/httpcore-nio) underneath. This library provides low-level I/O handling and HTTP-level detail handling.

How can I tune up the NHTTP transport?

There is a file called nhttp.properties in $ESB_HOME/repository/conf directory. User can change various configuration parameters like number of threads and maintain alive connections through this file. More information can be found in the ESB Administrator Guide.

Where is the general configuration of NHTTP transport?

The NHTTP transport configuration has two parts and they are transportReceiver and transportSender. Both configuration are located in $ESB_HOME\repository\conf\axis2\axis2.xml file.

How do I process files with the ESB?

Use the VFS transport for file processing. For an example, see Sample 271: File Processing.

How can I prevent an exception getting logged every 1-2 milliseconds in ESB when the JMS Broker (Active MQ) is down?

You can add failover: tcp://localhost:61616  to java.naming.provider.url of axis.xml JMSListener configuration as follows:

<transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener"> 
      <parameter name="myTopicConnectionFactory" locked="false"> 
        <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> 
        <parameter name="java.naming.provider.url" locked="false">failover:tcp://localhost:61616&lt;/parameter> 
        <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter> 
        <parameter name="transport.jms.ConnectionFactoryType" locked="false">topic</parameter> 
      </parameter> 
  
      <parameter name="myQueueConnectionFactory" locked="false"> 
         <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> 
         <parameter name="java.naming.provider.url" locked="false">failover:tcp://localhost:61616&lt;/parameter> 
         <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter> 
         <parameter name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter> 
       </parameter> 
  
      <parameter name="default" locked="false"> 
        <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> 
        <parameter name="java.naming.provider.url" locked="false">failover:tcp://localhost:61616&lt;/parameter> 
        <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter> 
        <parameter name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter> 
      </parameter> 
</transportReceiver>

When the configuration is done as shown above, the attempted reconnection to Active MQ will not be logged in the log file.

How can we add JMS correlation IDs to the messages in a request queue and how does it work?

 In order to make correlation IDs to the messages in the request queue:

  1. Add the following property within the in sequence  of the proxy service.

      <property name="JMS_COORELATION_ID" value="1234" scope="axis2"/>
  2.  Make a response with same corrlelation ID (message_properties.correlation := '1234').
Your request and response messages will be matched using this correlation ID.

Production-Related Questions

Where do I keep the WSDLs required by my proxy services?

You can keep them as local entries. But it is recommended to keep them in the registry instead, for easier and better management.

What is a graceful shut down?

When a graceful shut down is initiated, the ESB will continue to serve the accepted requests but stops processing new ones.

I already have a WSO2 Governance Registry instance that contains my organization's SOA metadata. Can I get WSO2 ESB to use that registry instance as the metadata store?

WSO2 ESB integrates with WSO2 Governance Registry out of the box. For steps involved in remote registry configuration, refer to Working with the Registry .

I need to setup a cluster of ESB instances. How can I share the same configuration among all the ESB nodes?

Put the configuration into the registry and point all ESB instances to that registry instance.

How can I get the <ESB_HOME>/tmp directory cleared?

Based on the HouseKeeping task for carbon.xml, if the <AutoStart> property is set to true, all files that are more than 30 minutes old will be cleared every 10 minutes.
If you are running the ESB on Linux, you can also write a cron job to handle the clearing of contents within the <ESB_HOME>/tmp directory. 

Deployment Questions

What are the Java versions that support running WSO2 ESB?

You can run WSO2 ESB on JDK 1.7.* and JDK 1.8.*. For more information, see Tested JDKs.

What are the minimum artifacts required to deploy WSO2 ESB?

Refer to Installation Prerequisites.

How can I disable the management console?

You can uninstall all the UI components using the feature manager, which will disable the management console.

Does WSO2 ESB support application server deployments?

Yes it has been tested on JBoss, Weblogic, Websphere and Tomcat.

How can I deploy a custom task?

Put your non-OSGi task jar into $ESB_HOME/repository/components/lib directory, which will be deployed automatically. For information on writing a custom task, refer to Writing Tasks.

How do I embed a third-party registry with WSO2 ESB?

You need to write a class implementing the org.apache.synapse.registry.Registry interface to integrate the third party registry to WSO2 ESB.

What is the database management system used in WSO2 ESB?

WSO2 ESB ships with an embedded H2 database. However any database management system can be plugged into the ESB via JDBC. The relevant database configurations are available in repository/conf/registry.xml and repository/cong/user-mgt.xml files. WSO2 ESB has been tested with MySQL, Oracle, MSSQL and PostgreSQL databases. For information, refer to Setting up the Physical Database.

How can I change the memory allocation for the WSO2 ESB?

The memory allocation setting are in the wso2server.sh. You can change the memory allocation settings by changing the following configuration.

-Xms256m -Xmx512m -XX:MaxPermSize=128m

Monitoring Questions

What are the best practices for monitoring WSO2 ESB?

For a variety of options to monitor and manage WSO2 ESB refer to Monitoring the ESB.

You can monitor mediation statistics in the ESB at proxy service level, sequence level, endpoint level, etc. by enabling mediation statistics in your server. For more information, refer to Mediation Statistics. Additionally, you can publish these mediation statistics to WSO2 Data Analytics Server (WSO2 DAS) for advanced analysis. For instructions on publishing mediation statistics to WSO2 DAS, refer to Configuring Mediation Data Publishing.

Does ESB supports JMX monitoring?

Yes it support JMX monitoring. Users can use the JConsole for simple monitoring and use JMX clients for custom monitoring. For more information, refer to Monitoring the ESB .

Does ESB allows custom statistics collection?

Users can write and plug their own statistics collection mechanisms to the ESB. This allows users to report statistics to their own statistics collection systems.

What is the logging framework used in WSO2 ESB?

WSO2 ESB uses Apache Log4/J over Apache Commons Logging as the logging framework. Logging configuration is loaded from the log4j.properties file in $ESB_HOME\repository\conf directory. The UI also allows configuring logging at runtime. For instructions, refer to Logging . The generated server logs can be found in the $ESB_HOME\repository\logs directory.

I have a sequence which does not behave the way I want it to. How can I find out what's wrong with it?

Login to the ESB management console and go to the 'sequence management' page. Enable tracing for the sequence you want to debug. Send a few messages to the sequence and go to the system logs viewer in the UI (or open the wso2-esb.log file in $ESB_HOME\repository\logs). Go through the generated trace logs and locate the problem.

My WSO2 ESB instance is receiving messages. But why don't I see any statistics on the mediation statistics page?

You need to enable statistics on sequences, endpoints, proxy services for the ESB to collect statistics on them. By default, WSO2 ESB does not collect statistics on anything to maintain minimum overhead. Simply enable statistics for required items using the management console UI and the mediation statistics page will start to get updated.

My ESB instance is behaving differently for certain input messages. What are the tools provided to debug the issue?

You can use the SOAP tracer in the UI to capture and monitor actual content of the incoming messages. Enable tracing on the appropriate sequences to trace the flow of messages through the ESB. ESB also comes with Apache TCPMon which is a simple but extremely useful tool for monitoring message flows.

What triggers the exception : com.ctc.wstx.exc.WstxIOException: Invalid UTF-8 start byte 0x89 (at char #1, byte #-1)"?

This exception occurs when the <ESB_HOME>/repository/conf/axis2/axis2.xml file does not define any builders and/or formatters that can read the content type of the request received by the ESB. Update the axis2.xml file with a message builder and formatter that can be used to read the content type of the relevant request in order to overcome this issue. See Configuring Message Relay for instructions on how to configure a message builder and a formatter as required. See Working with Message Builders and Formatters for further information on how to use builders and formatters.