Custom Services

Introduction

Custom Services provide a means to extend VocBench at the service-layer by enabling the definition of new services in a rather high-level manner. It is sufficient to have a general understanding of the conceptual model of the services (i.e. how they are composed), and the ability to express the desired behavior in some implementation language, currently, only SPARQL queries and updates. Custom services relieve the user from the need to know the underlying architecture of VocBench, the use of OSGi to support extendability, or the underlying programming model used to write services. Furthermore, there is no longer any need to set up a separate development environment, since all development is done within VocBench itself.

Conceptual Model

A Custom Service groups a number of related operations under a unique service name. Operations define the actual behavior of the service. Each operation is identified by a name (which shall be unique within a custom service), zero or more (formal) parameters, a return type and an authorization string. The actual behavior associated with the operation is defined by means of additional information specified by the chosen CustomServiceBackend: currently, there is only backend supporting the specification of an operation through a SPARQL query (for read services) or a SPARQL update (for mutation services).

The operations defined by a custom service can be invoked by issuing a GET (for read services) or a POST (for mutation services) to addresses matching the following pattern:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-custom-services/service-name/operation-name?ctx_project=current-project&...parameter_i=argument_i

Editing Custom Services

The following figure depicts the main user interface for editing custom services.

The panel on the left lists the available custom services, providing buttons to create a new service, delete an existing one, and refresh the list. The dropdown menu associated with the refresh button offers the option to force reload the services the file system. This option is only useful if custom services are edited outside of VocBench, by editing the underlying representation on the file system. The items of the list are the service identifiers of the custom services. Under the hood, these identifiers identify configurations used to persist the definition of custom services in the configuration manager it.uniroma2.art.semanticturkey.config.customservice.CustomServiceDefinitionStore.

The panel on the right shows the specification of any custom service that has been selected in the list on the left. The specification consists of a service name, description and a list of operations. The button labeled with a pencil near the first two fields can be used to edit the corresponding values. The list of operations is associated with buttons to create a new operation and delete an existing operation. The combined refresh button in the header of the right panel behaves like the already mentioned button, but limited to the currently selected service.

After selecting an operation, the user interface is extended with a further panel showing its details, as depicted by the figure below.

Defining the operation authorization

The authorization string associated with an operation is used to determine whether an invocation of the operation should be allowed or forbidden (based on the user doing the invocation).

The authorization string consists of three parts:

• a capability that must be owned by the user who invokes the operation. The subject of the capability may be restricted to a given role (e.g. concept) or to the role of one of actual parameters of the operation
• optionally, a language that must be assigned to the user who invokes the operation. The language can be a constant (e.g. en) or be determined at runtime from one of the actual parameters of the operation
• one or more operations among the ones defined by our extended CRUDV model

If no authorization is provided, the following defaults apply:

• rdf, R for read operations
• rdf, CUD for mutation operations

The screenshot below depicts the wizard for the definition of an authorization string.

Defining Custom Services Operations in SPARQL

The parameters are mapped to variables with the same name in the SPARQL query. Actual parameters passed to a service upon invocation are pre-bound to the corresponding variable in the SPARQL query. A reserved variable is workingGraph, which is bound by default to the working graph of the project.

The allowed parameter types are:

• boolean
• integer
• short
• long
• float
• double
• java.lang.String
• BNode
• IRI
• Literal
• Resource
• RDFValue

The allowed return type depends on the actual SPARQL operation:

• Update => void
• ASK => boolean
• SELECT =>
  • List<T>, where T
    • might be any of the above accepted parameter types (in this case the SELECT must return one variable)
    • be AnnotatedValue<S> where S might be:
      • BNode
      • IRI
      • Resource (in this case the SELECT must return one variable plus additional variables ?attr_... for additional attributes)
  • any of the above accepted parameter types (in this case the SELECT must return one variable and produce one result)
  • TupleQueryResult (corresponding to the raw result set produced by the query)

Copyright © ART Group - Università degli Studi di Roma 'Tor Vergata'