WSO2 Enterprise Service Bus and WSO2 Governance Registry Integration

WSO2 Enterprise Service Bus and WSO2 Governance Registry Integration

This knowledge base article is aimed at WSO2 Enterprise Service Bus (WSO2 ESB) users who will be interested to use WSO2 Governance Registry (WSO2 G-Reg) for storing various WSO2 Enterprise Service Bus configurations.

Applies To

WSO2 Enterprise Service Bus version 2.1.1 or later and WSO2 Governance Registry version 3.0.1 or later

Introduction

WSO2 Enterprise Service Bus uses WSO2 Governance Registry for storing configuration elements, resources like WSDL’s, policies, service metadata etc. WSO2 Enterprise Service Bus can run a WSO2 Governance Registry instance embedded into it or it can connect to a remotely running WSO2 Governance Registry using JDBC. 

Prior to WSO2 Enterprise Service Bus version 2.1.1, we had a concept called remote registry which used Atom for WSO2 Enterprise Service Bus and WSO2 Governance Registry communication. It is still supported but due to some technical limitations like inability to support transactions we recommend using the Embedded Registry or JDBC Registry. 

Configuring WSO2 Governance Registry

To configure the registry integration user has to edit the registry.xml found in the <ESB_HOME>\conf directory.

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

<readOnly>false</readOnly> 

If readOnly set to true WSO2 Enterprise Service Bus 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 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>

WSO2 Governance Registry uses a database for storing it’s configuration. The databse can run within the WSO2 Enterprise Service Bus itself or it can be run remotely. The above url is for the database that ships with the WSO2 Enterprise Service Bus. Users can run WSO2 Governance Registry seperately and connect to it using the JDBC url.

WSO2 Enterprise Service Bus has a built in concept of registry. It uses it for two purposes. 

1. Storing the static configuration of WSO2 Enterprise Service Bus
2. Storing Dynamic configuration items

Static Configurations

Every WSO2 Enterprise Service Bus instance has a configuration. The configuration is in XML format and we call this Apache Synapse configuration language. WSO2 Enterprise Service Bus has various configuration elements.

1. Proxy services
2. Sequences
3. Local entries
4. Tasks 
5. Event sources

All these configurations are represented by XML. WSO2 Enterprise Service Bus can use a flat file called synapse.xml which can contain all these elements to load its configuration. 

Also WSO2 Enterprise Service Bus stores this synpase XML configuration in the registry. The registry configuration is not a single flat file like synapse.xml. It stores all the different types of configuration units sperately. All this is hidden from the end user and he/she should not care where the actual configuration is stored. 

I’ll explain how this file based configuration and registry based configuration is used.

• When WSO2 Enterprise Service Bus boots up for the first time it reads the configuration from the synapse.xml file in the <ESB_HOME>\conf directory
• Then it stores this configuration in the registry
• Subsequent start-ups of the WSO2 Enterprise Service Bus uses the registry configuration
• When a user made a change to the configuration via the UI, i.e. sequence editor, those changes are stored in the registry and they are not persisted to the synapse.xml unless specifically saved.
• If user wants to save the configuration to the syanpse.xml file, he/she needs to go to the Apache Synapse configuration in the management console and click the save button. If the user wants to start WSO2 Enterprise Service Bus from the configuration stored in the synapse.xml he/she can do so by giving the –DuseSynapseXML command line argument at the startup of the WSO2 Enterprise Service Bus

Best practices

It is recommended to save the configuration to the synapse.xml time to time. Synapse.xml can be hand edited. If an errornous configuration is saved in the registry, sometimes WSO2 Enterprise Service Bus refuses to  start. For example a WSDL file used for creating a proxy service may not be available or its file location may have changed. WSO2 Enterprise Service Bus will not start in such a case. But users can always edit the synapse.xml manually and recover from the error very easily. If the configuration is only saved to the registry user may not have a way to edit the configuaration stored there. 

Dynamic Configurations

WSO2 Enterprise Service Bus has a concept of registry built in to it. It exposes an API for plugging various registries. WSO2 Enterprise Service Bus is integrated to the WSO2 Enterprise Service Bus using this API. 

To use this registry user has to use the following configuration in Apache Synapse configuration.

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

WSO2 Enterprise Service Bus configuration allows to refer varios configuration elements using a registry key. This key is referring a resource in the Registry. For example user can store the XML of a sequence in the registry. Then refer it from the WSO2 Enterprise Service Bus using the registry key. For example 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 i.e. cachableDuration parameter. When the cache duration expires WSO2 Enterprise Service Bus fetches these resources again from the registry.

The advantage of this approach is 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.

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

1. Endpoints
2. Sequences
3. XSLT files
4. Rule Scripts
5. Scriptig language scripts used by script mediator

Best Practices

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. 

Summary

WSO2 Governance Registry is an integral part of the WSO2 Enterprise Service Bus. It should be used carefully for the specific user requirements to achieve the maximum usability.

Author

Supun Kamburugamuva, Senior Software Engineer, supun AT wso2 DOT com