VocBench Developers Manual

This section provides detailed information for people interested in developing extensions for VocBench or even in modifying the core system. Currently, it contains generic information about the architecture of the system. We will add more details soon.

Building VocBench

Everything related to building the platform is written in the README of the VocBench3 and Semantic Turkey projects.

architecture

VocBench Architecture

The architecture  of VocBench has been designed by following a three-tier approach.

Presentation

The presentation layer of VocBench 3 is represented by the VB3 web application, built on Angular

Middle Layer: Business Logic

Requests from the VB3 web application are sent to Semantic Turkey, the RDF Data Management platform powering VocBench. Semantic Turkey offers services for RDF Manipulation (with abstractions for OWL ontologies and SKOS thesauri), User Management and Authentication, Project Management etc... platform powering VocBench. More details about its architecture can be found in the development page of that project.

Data Access

Semantic Turkey bases its RDF services on the Eclipse RDF4J framework. The Data Manager component of Semantic Turkey provides high level facilities for management of imports, metadata, etc.. on top of the RDF4J framework. Access to different triple stores is possible, providing that they are capable of supporting RDF4J remote connections and, in case history/validation support is necessary, they implement RDF4J's Sail Stack mechanism

Logging

VB3 logs information both server and client side

For ST server logs, please refer to the documentation of Semantic Turkey.

The logs of the VocBench web application can instead be inspected through the client browser, by activating the console (e.g. CTRL+SHIFT+J on Chrome)

Settings and Preference Management

VB3 distinguishes the following properties:

Settings and Preferences have also defaults that can be set at various levels. For instance, a user can set the default value for a given preference for all projects, so that if that preference is not set for a given project, the default will be applied. Project Managers can also set default project preferences for their managed projects, so that if no preference is set by the user, the project default preference applies

Currently, VocBench 3 offers a preferences page from the user menu (activated from the user icon, topmost-right part of the screen). The settings are instead sparse across the application or through the Project Management pages.

In the future, pages for setting defaults for both system/project settings and preferences will be made available to users. However, it is now possible to set these defaults by editing the Semantic Turkey property files, as specified in the properties section of the ST manual

Exceptions Management

In Semantic Turkey, exceptions thrown by java code are managed by an handler that creates a dedicated response to the client. Semantic Turkey always returns a HTTP 200 code in that any exception that is generated "in app" is considered to be part of the normal behavior of the system (e.g. if a service invocation requests to delete a class and the request cannot be satisfied because the class has instances, this is dealt within the semantics of the application that are embedded within the content level of the message, while the response's code is 200 because the request has been received and properly managed). At the content level of the response, messages referring to exceptions produced by ST are explicitly represented as exceptions.

In the VocBench client, exceptions returned by the server raise exceptions in the client code. The HttpManager service has a general handler for exceptions that produce a red dialog window in VocBench, reporting the error, the message of the exception and a "details" section with the stacktrace of the exception in the server. A dedicated handler allows the requester to specify, through a parameter of the request, a list of exceptions that should not be intercepted by the general handler. These exception will thus "bubble up" in the client code, which can thus catch it and create a dedicated alert (e.g. in the previous example, the rejection of the action does not need any scaring "red window" nor to show the stacktrace in java: it's a normal even that occurs as users might request to delete a class without knowing that it has instances: a reassuring message can thus be shown to the user, asking if they want to force the deletion of the class or cancel the action).

The following examples and code snippets should allow for a more in-detail understanding of how VB handle exceptions.

SkosServices.ts contains the code responsible for the invocation of SemanticTurkey's SKOS services class. Some of the exceptions that might be thrown from createConcept are:

In all these three cases it would be preferrable to handle such exceptions and allow further operations (e.g. allow user to force the creation of the concept) instead of simply show a error red alert. So, in preparing the options for invoking the createConcept service through the HTTP Manager, we add to exceptionsToSkip the class names of the exceptions we want to handle separately. Such exceptions will be ignored by the default handler in HttpManager. 

    
      createConcept(label: ARTLiteral, conceptSchemes: ARTURIResource[], ...) {
        let params: any = {
          label: label,
          conceptSchemes: conceptSchemes,
          //...other params
        };
        let options: VBRequestOptions = new VBRequestOptions({
          errorAlertOpt: { 
            show: true, 
            exceptionsToSkip: [
              'it.uniroma2.art.semanticturkey.exceptions.PrefAltLabelClashException',
              'it.uniroma2.art.semanticturkey.exceptions.PrefPrefLabelClashException',
              'it.uniroma2.art.semanticturkey.exceptions.BlacklistForbiddendException'
            ] 
          } 
        });
        return this.httpMgr.doPost(this.serviceName, "createConcept", params, options)
      }

The following code is from VBActions.ts, where the createConcept service is invoked. As you can see, in case of failure, the returned error can be properly handled. 

    
      this.skosService.createConcept(data.label, data.schemes, ...).subscribe(
        () => { 
          //concept created succesfully
        },
        (err: Error) => {
          if (err.name.endsWith('PrefAltLabelClashException')) {
            //handler of PrefAltLabelClashException
          } else if (err.name.endsWith('PrefPrefLabelClashException')) {
            //handler of PrefPrefLabelClashException
          } else if (err.name.endsWith('BlacklistForbiddendException')) {
            //handler of BlacklistForbiddendException
          }
        }
      );

Extension Development

VocBench UI cannot (currently) be extended "per se", but it features several functionalities that can be based on different implementations, provided in the forms of extensions. VocBench's backend service platform, Semantic Turkey, has several "extension points", that is, well-defined interfaces in the code for functionalities that can be implemented in different ways and deployed in the platform in the form of plugins.

A dedicated Extension Point development page on Semantic Turkey's site describes the set of extensions points available for the platform, their interfaces and the ways these can be implemented