WSO2 WSAS URL-based Repository

Introduction

A typical question that is raised by many a user regarding URL repositories is, How do I configure my production instance of WSO2 WSAS to use a URL-based repository? All the Axis2 services & modules will reside in this central URL-based repository. In this article we answer some of the frequently asked questions related to enabling & configuring URL repositories.

Applies To

Table of Content

What are the different types of repositories supported by WSAS & what are the differences between them?

WSAS supports 2 types of repositories. They are the file system based repository & URL repository. In the case of file system based repositories, the repository directory has to reside on the file system which is running the WSO2 WSAS instance. e.g. /home/wsas/repository. This repository directory can be on a partition on the local disk or even a mount from a remote file system such as NFS, Andrew or Coda. A URL repository is a remote repository which is accessible via a URL. e.g. https://wso2.com/repository. As far as WSAS is concerned there is no difference between services & modules residing in a file system based repository or URL repository.

How do I enable and configure a URL repository in WSAS?

Locate the server.xml file under the WSO2WSAS_HOME/conf directory, and locate the following entry in this file:

<!--
    Location of the Axis2 Services & Modules repository
    This can be a directory in the local file system, or a URL.
    e.g.
    1. /home/wso2wsas/repository/ - An absolute path
    2. repository - In this case, the path is relative to WSO2WSAS_HOME
    3. file:///home/wso2wsas/repository/
    4. https://wso2wsas/repository/
    -->
    <RepositoryLocation>${wso2wsas.home}/repository/</RepositoryLocation>

Let's say that the URL repository is located at https://localhost/repository. In that case, change the "RepositoryLocation" entry to "https://localhost/repository". A restart of WSAS is required for this change to take effect.

In what scenarios will a URL-based repository be useful?

There can be several production scenarios in which a URL-based repository is more appropriate than the file system based repository.

The WSAS instance in production may run on a powerful machine, while all the modules and services will reside in another machine which has a very high disk capacity, possibly using RAID technology.

WSAS may be deployed in a clustered configuration in production. In such a case, all WSAS nodes need to have identical services & modules deployed. In such a scenario, the most practical way of deploying services & modules will be in a URL-based repository. In this setup, all WSAS nodes will be configured to point to the same URL-based repository. For example, new services can be dropped into this repository, and all nodes can be notified of the addition of the new services.

How do I setup a URL-based repository?

The simplest way is to install Apache HTTPD (https://httpd.apache.org) & to create a directory named repository under the Apache HTTPD htdocs directory. On a Unix machine, execute:
mkdir -p $APACHE2_HOME/htdocs/repository/

Unzip the WSAS binary distribution to a directory, say /home/wsas and execute:
cp -r /home/wsas/repository/* $APACHE2_HOME/htdocs/repository/

Note that the wsas user will need read-write permissions to the $APACHE2_HOME/htdocs/repository/ directory in the above case.

Another way of achieving the same is by creating a symbolic link from the $APACHE2_HOME/htdocs directory to the /home/wsas/repository/ as follows:
ln -s /home/wsas/repository/

Please note that creating the symlink will work only if Apache HTTPD has been configured to follow symlinks. This can be done by editing the apache2.conf file, if it has not been already configured to do so.

Note that $APACHE2_HOME signifies the home directory of your Apache HTTPD installation.

How do I add a new service to the URL-based repository?

Let's say you want to add a service archive, foo.aar, to the repository. In this case, you need to copy foo.aar to the services repository.
e.g. cp foo.aar $APACHE2_HOME/htdocs/repository/services/

Next edit the $APACHE2_HOME/htdocs/repository/services/services.list file and add the following entry on a new line of this file:
foo.aar

Finally you need to restart all WSAS instances pointing to this repository, so that the newly added service can be deployed on each of those instances. In case you have enabled clustering configuration management, you could send a reload configuration command to the cluster of nodes, which will prompt all nodes to reload the new service group, foo.

How do I add a new module to the URL-based repository?

Let's say you want to add a module archive, bar.mar to the repository. In this case, you need to copy bar.mar to the modules repository.
e.g. cp bar.mar $APACHE2_HOME/htdocs/repository/modules/

Next edit the $APACHE2_HOME/htdocs/repository/modules/modules.list file and add the following entry on a new line of this file:
bar.mar

Finally you need to restart all WSAS instances pointing to this repository, so that the newly added module can be deployed on each of those instances.

What is the purpose of the services.list file included in the services repository?

See Glossary for the meaning of services repository.

This file lists all of the service archives included in the services repository. Only the service archives listed in this file can be deployed. The entries in a typical services.list file shipped with WSAS looks like the following:

wso2wsas-administration.aar
version.aar
echo.aar
xkms.aar
wso2codegen.aar
wsdlconverter.aar
wso2wsas-sts.aar
wsdlview.aar
archive-validator.aar

Say a new service archive, foo.aar, was added to the system, but a corresponding entry was not added to the services.list file. In such a case, even if the WSAS instance which points to this repository is restarted, the new service archive, foo.aar, will not be deployed since there is no way for WSAS to figure out that a new service archive is available in the services repository since the services.list has no corresponding entry.

What is the purpose of the modules.list file included in the modules repository?

See Glossary for the meaning of modules repository.

This file lists all of the module archives included in the module repository. Only the module archives listed in this file can be deployed. The entries in a typical modules.list file shipped with WSAS looks like the following:

wso2tracer-2.1.mar
wso2sandesha2-persistence-2.1.mar
addressing-1.3.mar
rahas-1.3.mar
wso2xfer-2.1.mar
wso2throttle-2.1.mar
rampart-1.3.mar
wso2mex-2.1.mar
wso2statistics-2.1.mar
wso2wsas-admin-2.1.mar

Say a new module, bar.mar, was added to the system, but a corresponding entry was not added to the modules.list file. In such a case, even if the WSAS instance which points to this repository is restarted, the new module archive, bar.mar, will not be deployed since there is no way for WSAS to figure out that a new module archive is available in the modules repository since the modules.list has no corresponding entry.

What are the limitations of using a URL repo?

Many of the features available when WSAS is deployed using a file system based repository are not available when a URL repository is used. The reasons for these limitations include some of the inherent limitations imposed by URLs itself, as well as limitations in the implementations of some of the features included in WSAS. The following limitations exist when a URL repo is used with WSAS:

1. Only AAR files can be deployed using URL-based repositories. Other artifact formats supported by WSAS & Axis2 such as Data services, Axis1 services artifacts, annotated POJOs etc. cannot be deployed due to the limitations in the implementations of these features.
2. Service and module archive deletion using the WSAS console will not work. This is because it is not possible to delete a resource referred to by a URL. In order to remove a service or a module, first it needs to be removed from the services.list or modules.list file respectively, and then, deleted from the physical location hosting the service archive or module archive.
3. File uploads to a URL-based repository are not allowed. WSAS allows a user to upload Axis2 service archives (AAR files), annotated & non-annotated JAR files, EJB interfaces, module archives (MAR files), Spring framework artifacts & Axis1 legacy service artifacts using the WSAS console. However, since URLs cannot be written to, these uploads are not allowed when URL-based repositories are in use.
4. Hot deployment is unavailable. In the axis2.xml included in WSAS, when the hotdeployment parameter is set to true, any service archive dropped into the services repository will be automatically detected and deployed by WSAS. However, the URL repository implementation does not support this feature. Only file system based repositories support this feature. WSAS will have to be explicitly notified of the availability of new service archives for deployment. When clustering configuration management is enabled, this can be done by sending a LoadServiceGroups command along with the name of the service group(s) to be loaded. Please note that the service group name corresponds to the name of the service archive.
5. Hot update is unavailable. In the axis2.xml included in WSAS, when the hotupdate parameter is set to true, any changes or updates to a service archive in the services repository will be automatically detected and the service will be redeployed by WSAS. However, the URL -based repository implementation does not support this feature. Only file system based repositories support this feature . WSAS will have to be explicitly notified of changes to existing service archives. When clustering configuration management is enabled, this can be done by sending an UnloadServiceGroups command followed by a LoadServiceGroups command. Unloading & reloading is equivalent to the hotupdate functionality. In each case, the name of the service group(s) to be reloaded have to be sent along with the relevant commands. Please note that the service group name corresponds to the name of the service archive.
6. Create Service Archive feature does not support URL-based repositories. This feature facilitates the serialization of the changes done using the WSAS console or WSAS Eclipse IDE plugin, to a service group and all services associated with that service group. For services deployed in a URL-based repository, due to some limitations, this feature is not available. However, this feature will not be required in general, when WSAS is deployed in production. This feature is mostly useful during development & staging periods.

Glossary

WSAS Repository - A location where WSAS services & modules are deployed, the default is $WSO2WSAS_HOME/repository/

WSAS Services Repository - The location where WSAS services are deployed, the default is $WSO2WSAS_HOME/repository/services

WSAS Modules Repository - The location where WSAS modules are deployed, the default is $WSO2WSAS_HOME/repository/modules

Hot deployment - When a new service archive is dropped into a services repository, the WSAS deployment mechanism gets notified, and the service group is deployed

Hot update - When a service archive which resides in the services repository gets updated, or undergoes any changes, the WSAS deployment mechanism gets notified, and the service group is redeployed

symlink - Unix symbolic link

References

WSO2 WSAS How To Series

Author

Afkham Azeez, Architect & Product Manager of WSO2 WSAS, WSO2 Inc. azeez at wso2 dot com