Learning registry.xml

Introduction

The product not only allows you to store service descriptions, policies and other service-specific meta information, but also images, text files and office documents. The WSO2 Governance Registry also provides a simple RESTful remote interface which uses the Atom Publishing Protocol (powered by Apache Abdera). More information on the WSO2 Governance Registry can be found in here.

WSO2 Governance Registry includes the following key configuration files:

1. Configuration for the WSO2 Carbon Server (carbon.xml)
2. Configuration for Embedded Apache Axis2 Client and Server (axis2.xml and axis2_client.xml)
3. Configuration for Media Types of Resources stored on the Repository (mime.types)
4. Configuration for the WSO2 Governance Registry (registry.xml)
5. Configuration for Embedded Tomcat Servlet Transports (transports.xml)
6. Configuration for Managing Users on the WSO2 Carbon Server (user-mgt.xml)
7. Configuration for running the Daemon script (wrapper.conf)

This tutorial explains the configuration of the WSO2 Governance Registry, through the registry.xml file. You will be learning about the various parameters appearing in the registry.xml and their usages. By following this brief tutorial you will be learning how to take control of your WSO2 Governance Registry configuration and also how you can customize your own parameters and other configuration details. The registry.xml file contains several types of configuration details.

1. Registry configuration details
2. Database configuration details
3. Handler configuration details
4. Remote Instance configuration details

Applies To

Contents

1. Registry Configuration Details
2. Database Configuration Details
3. Handler Configuration Details
4. Remote Instance Configuration Details
5. Changing Configuration Details
6. Summary

Registry Configuration Details

The WSO2 Governance Registry, is designed, having in mind the ability to tailor it according to various business requirements. As an implementation framework for Governance within an organization, its people, processes and services, the WSO2 Governance Registry gives an administrator the ability to choose from a wide variety of design-time (static) configuration options.

    <staticConfiguration>
        <versioningProperties>true</versioningProperties>
        <versioningComments>true</versioningComments>
        <versioningTags>true</versioningTags>
        <versioningRatings>true</versioningRatings>
        <!-- Location you want to add service and default 
            location will be /governance/services/ -->
        <servicePath>/governance/services</servicePath>
    </staticConfiguration>

The ability to track changes done to organizational resource, and optionally review and revert back to an older version, puts one of the most important pieces to the puzzle that most organizations are facing. The WSO2 Governance Registry takes you a step further by giving you the option to decide on what operations on a resource are versioned and what are not. This allows you to optimize data storage and also gain better performance while securing your business goals. Versioning is enabled for all operations on a resource by default, and, you can disable versioning of properties, comments, tags and ratings by changing the value of the corresponding parameter to false.

In addition to versioning the WSO2 Governance Registry also allows you to configure how you store various resources (mainly for services). You can change the default service path /governance/services to any valid path on the registry. If this location already exists, it will be re-used, or if not, it will be created for you.

    <versionResourcesOnChange>true</versionResourcesOnChange>

Versioning resource per each change made can be an extremely expensive operation at runtime (especially if there are many resources that change). By setting the versionResourcesOnChange parameter to false, you can disable versioning resources on change.

The WSO2 Governance Registry can be used in two modes of operation, READ-ONLY and READ-WRITE. The WSO2 Carbon Server has been designed with the provision of multiple instances of similar servers to make use of a single configuration base. An ideal example is a cluster of WSO2 Enterprise Service Buses (ESBs). Here, we can define one node as the master of the cluster which has the ability to read and write configuration data, while the others can only read. The single-reader multiple-writer deployment scenario solves concurrency problems. The registry.xml file can be used to define whether the embedded (or remote) instance of the Registry in-use is writeable or not. This is controlled by the readOnly parameter.

    <readOnly>false</readOnly>

The WSO2 Governance Registry also supports the notion of using a single repository shared among multiple servers based on the WSO2 Carbon Server platform. This is analogous to different users sharing the same file system. Each server (like each user) will be given a chroot'ed environment to work upon, with its apparent root being a child of the root of the shared repository.

    <registryRoot>/</registryRoot>

The registryRoot parameter can be used to define whether the apparent root of the running instance of the server. In the event of multiple servers running against a single repository, the WSO2 Carbon Server can be configured in three different ways. Without loss of generality, lets take two servers A and B, sharing the same repository. Then the three configuration options are as follows:

1. A is B's sibling - A and B have the same registry root ('/', or '/myroot').
2. A is B's parent - A has registry root '/' or '/myroot' while B has registry root '/child' or '/myroot/child'.
3. A and B are isolated - A has registry root '/a' and B has registry root '/b'.

The three different configuration options facilitate a number of grid and clustered deployments.

Database Configuration Details

The WSO2 Governance Registry has been tested to work with various relational database management systems including,

1. H2 (Embedded and Server)
2. Apache Derby (Embedded and Server)
3. MS SQL Server
4. MySQL
5. Oracle

The server administrator can define the type of database to be used, along with the JDBC connection URL to connect to the database and a compatible driver via the database configuration parameters.

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

Each database configuration will have a name, a JDBC connection URL, and a compatible driver to be used. Depending on the type of database used, you can define several other parameters such as,

1. The username used to connect to the database server
2. The password of the database user
3. The maximum number of active connections that can be allocated from the connection pool at the same time, or a negative value to allow unlimited connections
4. The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or non-positive value to wait indefinitely
5. The minimum number of active connections that can remain idle in the pool, without extra ones being created, or 0 to create none

There can be more than one database configuration specified within the registry.xml file. For instance, you can have something similar to the configuration below.

    <dbConfig name="derby-embedded-db">
        <url>jdbc:derby:databasetest/CARBON_TEST;create=true</url>
        <!--userName>su</userName>
        <password>su</password-->
        <driverName>org.apache.derby.jdbc.EmbeddedDriver</driverName>
        <maxActive>80</maxActive>
        <maxWait>60000</maxWait>
        <minIdle>5</minIdle>
    </dbConfig>

    <dbConfig name="derby-db-server-local">
        <url>jdbc:derby://localhost:1527/derbyDB;create=true</url>
        <userName>userName</userName>
        <password>password</password>
        <driverName>org.apache.derby.jdbc.ClientDriver</driverName>
        <maxActive>80</maxActive>
        <maxWait>60000</maxWait>
        <minIdle>5</minIdle>
    </dbConfig>

    <dbConfig name="derby-db-server-remote">
        <url>jdbc:derby://10.20.30.40:1527/derbyDBRemote;create=true</url>
        <userName>userName</userName>
        <password>password</password>
        <driverName>org.apache.derby.jdbc.ClientDriver</driverName>
        <maxActive>80</maxActive>
        <maxWait>60000</maxWait>
        <minIdle>5</minIdle>
    </dbConfig>

However, the server can only handle one active configuration at a time. The currentDBConfig parameter is used to specify the database configuration that is active at present.

    <currentDBConfig>wso2registry</currentDBConfig>

The value of the currentDBConfig parameter should be a valid name of a database configuration defined on the registry.xml file. An administrator can gain a number of benefits by being able to switch between database configurations.

1. The ability to create back-up databases that can be activated by a simple configuration change resulting in minimal downtime.
2. Ease of development with the ability of testing on multiple database systems.

Handler Configuration Details

The WSO2 Governance Registry can be extended in several ways. Handlers are pluggable components, that contain custom processing logic for handling resources. All handlers extend an abstract class named Handler, which provides default implementations for resource handling methods as well as a few utilities useful for concrete handler implementations. Each handler is associated with a filter. Filters provide criteria for engaging handlers. Registry always evaluates the associated filter before invoking a handler. If the filter evaluates to true, it will invoke its associated handler.

Handlers can be engaged to the WSO2 Governance Registry either programmatically, or by defining them in the registry.xml. Most built-in handlers are engaged by default, whereas optional and user-defined handlers should be configured by defining them in the registry.xml file. The registry.xml file includes several optional handlers that can be enabled or disabled according to your requirement.

Repository Handlers

There are four repository handlers in use, which can create the directory structure required by Apache Axis2, Apache Synapse, WSO2 Enterprise Service Bus and WSO2 Web Service Application Server on the WSO2 Governance Registry. Each repository handler will create a collection with a defined media type, so that future repository-wide operations and additional validations can easily be done. This media type is also useful in locating one of many repositories, using search queries.

    <handler class="org.wso2.carbon.registry.extensions.handlers.Axis2RepositoryHandler">
        <filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
            <property name="mediaType">application/vnd.apache.axis2</property>
        </filter>
    </handler>

Indexing Handlers

Although not fully implemented for the current released version, the WSO2 Governance Registry includes a framework of handlers that can be used to index resources of various types. There are handlers which can be extended to index XML files, PDF files, Microsoft Word documents, spreadsheets and presentations.

    <handler class="org.wso2.carbon.registry.extensions.handlers.XMLIndexingHandler">
        <filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
            <property name="mediaType">application/xml</property>
        </filter>
    </handler>

Service Metadata Handlers

The WSO2 Governance Registry is optimized to support Design-time and Run-time governance for Web Services. There exists handlers that can process WSDL files, schemas and policies. These handlers are even capable of managing related resources such as imported WSDLs and schemas. The service metadata handlers accept several configuration options which allows you to define the associated media type and storage location.

    <handler class="org.wso2.carbon.registry.extensions.handlers.ZipWSDLMediaTypeHandler">
        <property name="wsdlMediaType">application/wsdl+xml</property>
        <!--property name="wsdlExtension">.wsdl</property>
        <property name="archiveExtension">.gar</property>
        <property name="tempFilePrefix">wsdl</property-->
        <property name="schemaLocationConfiguration" type="xml">
            <locationType>absolute</locationType>
            <location>/governance/schemas/</location>
        </property>
        <property name="wsdlLocationConfiguration" type="xml">
            <locationType>absolute</locationType> <!-- absolute or relative -->
            <location>/governance/wsdls/</location>
        </property>
        <filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
            <property name="mediaType">application/vnd.wso2.wsdl-archive</property>
        </filter>
    </handler>

External Link Handler

The WSO2 Governance Registry allows you to store external links as a part of the repository tree structure. Clicking on such a resource would take you to the external link. This makes it easy for an organization to manage physically separated resources as a part of a single hierarchical tree structure.

    <handler class="org.wso2.carbon.registry.extensions.handlers.ExternalLinkHandler">
        <filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
            <property name="mediaType">application/vnd.external</property>
        </filter>
    </handler>

You can similarly include your own handlers on the registry.xml. The handler sample included with the WSO2 Governance Registry distribution explains to how you could create your own handler and include it in the registry.xml file.

Remote Instance Configuration Details

The WSO2 Governance Registry supports the concept of federating the directory structure of the repository across multiple servers. Thus, the structure of collections need not necessarily be existent on a single instance of the server. Each remote instance can be mounted and un-mounted by the simple addition of a configuration describing how to connect to it. The WSO2 Governance Registry's Remote Registry API is used to communicate between such remote instances.

    <remoteInstance url="https://host1:port1/CONTEXT/registry">
        <id>instance1</id>
        <username>username1</username>
        <password>password1</password>
    </remoteInstance>

    <remoteInstance url="https://host2:port2/CONTEXT/registry">
        <id>instance2</id>
        <username>username2</username>
        <password>password2</password>
    </remoteInstance>

More than one remote instance can be attached to a given WSO2 Governance Registry by adding the relevant configuration details as seen above. Each remote instance must be given an identifier along with valid credentials that have sufficient privileges to perform the desired registry operations (requires at least read-privileges to the registry along with permission to log-in to the server). The URL of the remote instance can be deduced as follows:

Let the URL of the destination server be https://localhost:9443/services. Then the URL of the remote instance will be https://localhost:9443/registry. Let the URL of the destination server be https://10.20.30.40:9445/webcontext/services. Then the URL of the remote instance will be https://10.20.30.40:9445/webcontext/registry. Please also note that you can't mount the same server as a remote instance to itself.

Changing Configuration Details

The WSO2 Governance Registry configuration will be loaded when the org.wso2.carbon.registry.core bundle (the registry kernel) is activated. Thus, if any change done to the registry configuration, the server needs to be restarted if it is already running. While most configuration options can be changed after the first run of the WSO2 Governance Registry, changing the Static Configuration (configuration details under the staticConfiguration parameter), will not be fully effective. If you need to change any Static Configuration and expect it to take effect, you will have to erase the contents of the database, and restart the server passing the -Dsetup system property which will re-generate the database.

Summary

Now we know that there are several types of configuration details defined in the registry.xml file. We also learned how to change configuration details and how they would become effective. While some configuration details are strictly for the use of the WSO2 Governance Registry, there are others that can be used to control the operation and initialization of handlers that you write to extend the registry. The registry.xml file is therefore the central location that configures how the registry is used, the extensions are added on top of it, and the siblings that it should interact with.

References

Author

Senaka Fernando, Software Engineer, WSO2 Inc., senaka at wso2 dot com