Component registry REST interface

In an effort to disclose the Component Registry by means of web services an REST interface has been developed.

The REST interface is online. The Rest API which is on the server allows a client (e.g the Flex GUI) to browse and retrieve all existing components and profiles. Example:

• get all components: ​http://catalog.clarin.eu/ds/ComponentRegistry/rest/registry/components
• get all profiles: ​http://catalog.clarin.eu/ds/ComponentRegistry/rest/registry/profiles

If properly authenticated, users can register new ones to their workspace and eventually publish them to the ​public registry.

Interactive documentation of the REST service can be accessed at ​https://catalog.clarin.eu/ds/ComponentRegistry/api-docs/index.html.

---

Contents

1. Component registry REST interface
   1. Contents
   2. Getting code
   3. Building and Deploying
      1. Building
      2. Deployment
      3. Dependencies
   4. Design
      1. Class diagrams
      2. Data and service layer coupling
      3. Authentication
   5. Usage
      1. Testing environment

---

Getting code

• You can browse the code here (trunk).

---

Building and Deploying

Building

The REST is part of the modular Maven project ComponentRegistry. This module can be built separately (pom) but depends on the BrowserGui (Flex UI) so it needs to be installed in the local repository.

Executing the package phase of the project will generate a WAR file that can be deployed on Tomcat (or potentially another servlet container).

The build process includes a call to the ​maven-jaxb2 plugin, which generates model classes from the general component schema. The entire code base depends on these classes, so any code checker will detect errors until at least one build has been executed.

Build profiles

The pom has profiles for three deployment scenarios: default (local), lux16 (testing) and clarin (production). They only differ with respect to the authentication pre-configuration (non-Shibboleth/Shibboleth? with specific settings). For build commands, see this text file.

Deployment

First, build the application with the profile according to the targeted environment (see above).

To deploy the REST service including the Flex UI and its HTML wrapper, deploy the build output (WAR file) of the REST service to a Tomcat instance.

The application needs a Postgres database connection configured for it to actually work. If a database does not exist yet, it can be created using the create.sql script. By default, the application assumes a named (JNDI) datasource jdbc/ComponentRegistry that provides access to the Component Registry database. An example is provided in spring-config/datasource-jdbc.xml. This should ideally be configured in the server's global context.xml but can also be done in the servlet context.

More configuration options are available in spring-config/component-registry.xml; generally these will not need much adaptation; you'll have to restart the application after changing any of these.

For deployment for testing on lux16 see Usage -> Testing Environment in this document, i.e. https://trac.clarin.eu/wiki/ComponentRegistryRest#Usage

Dependencies

Internal dependency: BrowserGui (Flex UI)

External dependencies:

• Spring framework (2.5.6 is currently used)
• Jersey
• PostgreSQL
• HSQLDB (for testing)

The REST service also depends on the metadata toolkit, specifically the general component schema, which is used for validating component and profile specifications, and the comp2schema XSLT, which is used to generate XSD's from profile specifications.

---

Design

This project is mainly build in Java. However, it also contains some other code that implements a simple administration interface and a page embedding the graphical client application. The below diagrams show the hierarchical structure of the Component Registry Rest service and provide a better overview of the project.

Class diagrams

Figure 1. rest package diagram

Figure 2. registry package diagram

The rest interface is implemented using Jersey on top of the server, most importantly an implementation of the ComponentRegistry interface.

Figure 3. front end package diagram

Figure 4. implementation database package diagram

Data and service layer coupling

The implementation of this service layer is using a PostgreSQL database to store the components and profiles. The project uses the Spring framework. First of all, it uses its DAO support to interact with the database (*Dao classes in Figure 4)

Spring provides Dependency Injections methods used in the "wiring" of the application. This can be found in the configuration classes.

Authentication

The REST service is designed to use Shibboleth for authentication. although other kinds of authentication should also work. For testing, simple Tomcat authentication can be used, see web.xml for a configuration without shibboleth (cf. web-shib.xml).

Since a Shibboleth session can only be initiated through user interaction within the browser, all clients will need to share this browser session. For the Flex UI this is trivial because it lives inside the browser and all requests go through the browser.

---

Figure 5. model package diagram

---

Usage

For an overview of all calls, see the ​WADL or the REST documentation.

Testing environment

An environment for testing purposes has been deployed locally at the mpi at ​http://lux16.mpi.nl/ds/ComponentRegistry/rest/

• get all components: ​http://lux16.mpi.nl/ds/ComponentRegistry/rest/registry/components
• get all profiles: ​http://lux16.mpi.nl/ds/ComponentRegistry/rest/registry/profiles

Obviously, one should not rely on any data in this testing environment

Here are the step-by-step instruction "How to transfer your ComponentRegistry project to lux16" for testing. In this instruction, the example local branch directory is called "yourbranch" and the example version, on which your work on, is called "yourversion".

1) Prepare the archive of the project in yourbranch/ComponentRegistry/:

mvn clean install -Plux16

(This also stated in README in yourbranch/ComponentRegistry/.) The archive should appear in yourbranch/ComponentRegistry/target/

2) go to ​http://lux16.mpi.nl:8080/manager/html and stop "componentRegistrty". Stop the old version before you start your one.

3) Now, if the archive is ready, copy it to "lux16:/tmp/" . You should copy the whole archive "ComponentRegistry-version-SNAPSHOT-mpi-deploy.tar.gz" . Make sure that you have access to lux16.

4) Move "ComponentRegistry-yourversion-SNAPSHOT-mpi-deploy.tar.gz" to /lat/webapps/componentRegistry

5) Go to /lat/webapps/componentRegistry/. Untar the archive there: tar -zxf /tmp/ComponentRegistry-yourversion-SNAPSHOT-mpi-deploy.tar.gz

6) Go to /lat/webapps/componentRegistry/ComponentRegistry-yourversion-SNAPSHOT/war/ . Unzip the war-file there: unzip ComponentRegistry.war

7) Go to /lat/webapps/componentRegistry/. Symbolic link "current" still points to the old version of the project. Remove it by: rm current

8) Make a new symbolic link: ln -s ComponentRegistry-yourversion-SNAPSHOT/war ./current

9) Go to /lat/tomcat-webuser/conf/Catalina/localhost/ . Now, the xml database can be removed by TomCat?, but you need it. Use its backup: cp backup/ds#ComponentRegistry.xml .

10) run log to faciliate testing: tail -f /lat/tomcat-webuser/logs/componentRegistry.log