Storing Various WSO2 Enterprise Service Bus Configurations

WSO2 Enterprise Service Bus uses a registry for storing configuration elements, resources like WSDLs, policies, service metadata, etc. This data can be stored in the registry that is embedded in the ESB or an external instance of WSO2 Governance Registry. 

Configuring the Registry

To configure the registry integration, edit the registry.xml found in the <ESB_HOME>\repository\conf directory.

Here are some of the important parts of the registry configuration.

• <readOnly>false</readOnly>
  If readOnly is set to true, the ESB will not write anything to the registry. In a clustered environment, we set up only one registry as read/write and others as read only.

• <registryRoot>/</registryRoot>
  The root of the registry. All the values will be written and read relative to this path.

• <dbConfig/>
  The registry database configuration. The following configuration is for the default embedded database (H2). If you want to use an external registry, specify a JDBC connection to the registry's RDBMS or, if the database is behind a firewall, you can specify a WS-API connection.

<dbConfig name="wso2registry">
	<url>jdbc:h2:database/WSO2CARBON_DB</url>
	<username>wso2carbon</username>
	<password>wso2carbon</password>
	<driverName>org.h2.Driver</driverName>
	<maxActive>50</maxActive>
	<maxWait>60000</maxWait>
	<minIdle>5</minIdle>
</dbConfig>

Bootstrapping the Server with Static Configurations

• synapse.xml
• sequences\fault.xml
• sequences\main.xml

You can also create configurations in synapse.xml or the subdirectories for the following types of objects:

• Proxy services
• Sequences
• Local entries
• Tasks

After the ESB starts for the first time using these files, the configurations are stored in the registry, and the bootstrap files are no longer used. All subsequent server starts use the configurations in the registry, and any modifications users make to the configurations through the user interface are saved in the registry. However, it is a best practice to save the configurations to synapse.xml from time to time so that you can bootstrap the server if a registry error occurs that prevents the server from starting up. For example, if a WSDL file used for creating a proxy service moves to a new location, the ESB will not start. In this case, you can edit synapse.xml to configure the proxy service with the WSDL's new location, and then start the server using the --DuseSynapseXML command line argument to bootstrap it with the configurations in this file.

To save the configurations from the registry to the bootstrap file, navigate to the source view in the Management Console, copy the configurations, and paste them into synapse.xml.

Storing Dynamic Configurations

WSO2 Enterprise Service Bus configuration allows you to refer to various configuration elements using a registry key that uniquely identifies a resource in the registry. For example, you can store a sequence in the registry and then refer to it from the ESB using the registry key. If your registry resource path is /test/sequence_1, your key should be /test/sequence_1.

<syn:sequence key="/test/sequence_1">

These resources are loaded only when they are requested by the message processing (when a request comes). After the resource is loaded it will be cached locally into the memory by the WSO2 Enterprise Service Bus. Subsequent requests will use this cached resource. Users can specify a caching duration for these resources using the cachableDuration parameter:

<registry provider="org.wso2.carbon.mediation.registry.WSO2Registry">
      <parameter name="cachableDuration">15000</parameter>
</registry>

When the cache duration expires, WSO2 Enterprise Service Bus fetches these resources again from the registry.

The advantage of this approach is that users can change the sequences without restarting the WSO2 Enterprise Service Bus. If the WSO2 Enterprise Service Bus is clustered using a single registry, the user has to update only at one place.

For examples of adding dynamic sequences and endpoints, see Sample 9: Introduction to Dynamic Sequences with the Registry and Sample 10: Introduction to Dynamic Endpoints with the Registry.

Some of the configurations that can be stored in the registry are:

• Endpoints
• Sequences
• XSLT files
• Rule Scripts
• Scripting language scripts used by the Script Mediator

Storing XSLT files in a registry is needed if the user requires to cluster the WSO2 Enterprise Service Bus. Usually an ESB cluster is created by pointing several ESBs to use the configurations stored in a single registry. Also it is easier to manage the resources like XSLT if they are stored in the registry.

Also keeping the frequently changing items in the registry is a good practice. But there is a small performance overhead in loading the resources when the cache expires.

Storing Configurations for Different Users

You can create collections in the registry to maintain different sets of sequences and endpoints for different users in addition to creating shared configurations. For example, you could create three collections: one for your eastern region, one for your western region, and one for shared configurations. You can set permissions on each of the collections to control access to their configurations. When you create sequences and endpoints, you can save them in the eastern or western collection to restrict them to that region, or you can save them in the shared collection to make them available to everyone. To reference a configuration in a collection, simply add it to the path. For example, if you want your proxy service to reference a sequence named Seq shared in the Western collection in the conf registry space, it might look like this:

<proxy name="Main_Service" 
           transports="https http" 
           startOnLoad="true" 
           trace="disable"> 
       <target> 
          <inSequence> 
             <sequence key="conf:/Western/Seq"/> 
          </inSequence> 
       </target> 
</proxy>