Skip to content


Providing convenient helper classes for the piveau context

Build & Install#


  • Git
  • Maven 3
  • Java 11
$ git clone
$ cd piveau-utils
$ mvn install


Add repository to your project pom file:


Add dependency to your project pom file:




General RDF helper and extensions


This API provides an implementation of the PagedCollection defined in the Hydra Core Vocabulary, a vocabulary for hypermedia-driven Web APIs.

val paging = findHydraPaging(model)
val total = ?: -1
val next =
HydraPaging paging = HydraPaging.findPaging(model);
int total = paging.getTotal() != null ? paging.getTotal() : -1;
String next = paging.getNext();

In some cases the provider uses the paging incorrectly. In these cases you can provide a base URI, and the class will try to fix the misbehaviour.

val paging = findHydraPaging(model, baseUri)
HydraPaging paging = HydraPaging.findPaging(model, baseUri);

The implementation currently only supports total items and next page.

Geo parsing#

Simple Method to convert an RDF Literal into a geo json object. The literal may be one of the following formats:

  • application/vnd.geo+json

In all other cases and on any parsing problems the method returns an empty json object.

val jsonObject = parseGeoLiteral(geoLiteral)
JsonObject jsonObject = GeoParsingKt.parseGeoLiteral(geoLiteral);


Apache Jena extensions#

Triple Hash#

RDF Vocabularies#

Common RDF vocabularies and concept schemes

DCAT-AP model builder#

POJOs for building DCAT-AP dataset graphs

DCAT-AP model parser#

Parsing rdf graphs for DCAT-AP classes and properties

DCAT-AP SPARQL triple store#

Connecting your app to a triple store following a DCAT-AP naming scheme

Using a DCAT-AP namespace schema#

DCATAPUriSchema.config = json {
    obj {
        "baseUri" to ""
        "catalogueContext" to "id/catalogues/"
        "datasetContext" to "set/data/"
        "distributionContext" to "set/distribution/"
        "recordContext" to "set/record/"
        "metricsContext" to "id/metrics/"
DCATAPUriSchema.setConfig(new JsonObject()
        .put("baseUri", "")
        .put("catalogueContext", "id/catalogues/")
        .put("datasetContext", "set/data/")
        .put("distributionContext", "set/distribution/")
        .put("recordContext", "set/record/")
        .put("metricsContext", "id/metrics/"));

These are the default values. You can just override some or all of them if required.

The two main methods of this singleton is to parse a given uriRef and tells you what it is, and to generate a uriRef from a given external identifier

// check uri ref type
when {
    DCATAPUriSchema.isCatalogueUriRef(uriRef) -> {}
    DCATAPUriSchema.isDatasetUriRef(uriRef) -> {}
    DCATAPUriSchema.isDistributionUriRef(uriRef) -> {}
    DCATAPUriSchema.isRecordUriRef(uriRef) -> {}
    DCATAPUriSchema.isMetricsUriRef(uriRef) -> {}
    else -> {}

// parse given URIRef and provide a DCATAPUriRef
val dcatapUriRef = DCATAPUriSchema.parse(uriRef)

// context & id
val context = dcatapUriRef.context
val id =

// generate from external id.
val uriRef = DCATAPUriSchema.applyFor(externalId) 
// check uri ref type
if (DCATAPUriSchema.isCatalogueUriRef(uriRef)) {
} else if (DCATAPUriSchema.isDatasetUriRef(uriRef) {
} else if (DCATAPUriSchema.isDistributionUriRef(uriRef)) {
} else if (DCATAPUriSchema.isRecordUriRef(uriRef)) {
} else if (DCATAPUriSchema.isMetricsUriRef(uriRef)) {
} else {

// parse given URIRef and provide a DCATAPUriRef
DCATAPUriRef dcatapUriRef = DCATAPUriSchema.parse(uriRef);

// context & id
String context = dcatapUriRef.getContext();
String id = dcatapUriRef.getId();

// generate from external id.
DCATAPUriRef uriRef = DCATAPUriSchema.applyFor(externalId); 

Creating and configuring the triple store:#

val config = json {
    obj ("address" to "http://piveau-virtuoso:8890")   

val tripleStore = TripleStore(vertx, config)
JsonObject config = new JsonObject().put("address", "http://piveau-virtuoso:8890");
TripleStore tripleStore = new TripleStore(vertx, config);

with explicit WebClient

val client = WebClient.create(vertx)
val tripleStore = TripleStore(vertx, config, client)
WebClient client = WebClient.create(vertx);
TripleStore tripleStore = new TripleStore(vertx, config, client);

Using DCAT-AP specific managers#

The triple store comes with a set of DCAT-AP specific managers:

val catalogueManager = tripleStore.catalaogueManager
val datasetManager = tripleStore.datasetManager
val metricsManager = tripleStore.metricsManager
CatalogueManager catalogueManager = tripleStore.getCatalaogueManager();
DatasetManager datasetManager = tripleStore.getDatasetManager();
MetricsManager metricsManager = tripleStore.getMetricsManager();

Each manager provides a convenient API to deal with the corresponding DCAT-AP range. E.g.:

datasetManager.identify("datasetId", "catalogueId") {
    when {
        it.succeeded() -> {
            val (datasetResource, recordResource) = it.result()
        else -> {}
datasetManager.identify("datasetId", "catalogueId", ar -> {
    if (ar.succeeded()) {
        Resource datasetResource = ar.result().getFirst();
        Resource recordResource = ar.result().getSecond();

    } else {

The managers rely heavenly on the DCATAPUriSchema, so make sure it is properly configured for your needs.

DQV extensions#

Building and managing DQV graphs

piveau Logging#

Convenient logging classes to log to a centralized ElasticStack instance

You need to create a PiveauContext in order to get access to the piveau logger.

val piveauContext = createPiveauContext("serviceName", "moduleName")
piveauContext.log.debug("I am here.")
PiveauContext piveauContext = PiveauContext.create("serviceName", "moduleName");
piveauContext.log().debug("I am here.");

The logger supports a slf4j style api.

You can extend the context for a specific resource:

val resourceContext = piveauContext.extend("resourceId")
resourceContext.log.debug("I am an extended resource.")
PiveauContext resourceContext = piveauContext.extend("resourceId");
resourceContext.log().debug("I am an extended resource.");

Triple store mock up server for testing#

A simple mock triple store for testing purposes

What else...#

All the rest

Normalize date time#

val dateTime = normalizeDateTime("2019-07-01T12:00:20.00+02")
String dateTime = DateTimeKt.normalizeDateTime("2019-07-01T12:00:20.00+02");

It returns the date or datetime as ISO-8601 instant standard string ("2019-07-01T14:00:20Z").

CORS helper#

To help you with the Vert.x CorsHandler.


// it is also possible to get assign the handler to a specific route yourself:

new CorsHelper(corsDomains).addRootHandler(routerBuilder);

// it is also possible to get assign the handler to a specific route yourself:

routerBuilder.route("/cors").handler(new CorsHelper(corsDomains).handler)

If you want more customization options regarding the allowed Headers or Methods, you can overwrite the internal standard lists

val allowedHeaders = setOf<String>(

val allowedMethods = setOf<HttpMethod>(HttpMethod.GET, HttpMethod.POST);

CorsHelper(corsDomains, allowedHeaders, allowedMethods).addRootHandler(routerBuilder)
Set<String> allowedHeaders = setOf<String>(

Set<HttpMethod> allowedMethods = Set.of(HttpMethod.GET, HttpMethod.POST);

CorsHelper ch = new CorsHelper(corsDomains, allowedHeaders, allowedMethods);

Vert.x JsonObject and JsonArray extensions#

Although these extensions are most useful in Kotlin, you can use them also in Java.

val jsonObj = JsonObject()

// Put only if value is not null
jsonObj.putIfNotNull("key", value)
// Put only if json object is not empty
jsonObj.putIfNotEmpty("key", obj)

// Return json object of key or create a new one if not already exist. 
val obj = jsonObj.withJsonObject("key")
// Return json array of key or create a new one if not already exist. 
val array = jsonObj.withJsonArray("key")

// Forces key as `JsonObject`, even if it is a string   
val obj = jsonObj.asJsonObject("key")
// Forces key as `JsonArray`, even if it is a string   
val array = jsonObj.asJsonArray("key")

val jsonArray = JsonArray()
// Add only if value is not null
// Add only if json object is not empty
JsonObject jsonObj = new JsonObject();

// Put only if value is not null
JsonExtensions.putIfNotNull(jsonObj, "key", value);
// Put only if json object is not empty
JsonExtensions.putIfNotEmpty(jsonObj, "key", obj);

// Return json object of key or create a new one if not already exist. 
JsonObject obj = JsonExtensions.withJsonObject(jsonObj, "key");
// Return json array of key or create a new one if not already exist. 
JsonArray array = JsonExtensions.withJsonArray(jsonObj, "key");

// Forces key as `JsonObject`, even if it is a string   
JsonObject obj = JsonExtensions.asJsonObject(jsonObj, "key");
// Forces key as `JsonArray`, even if it is a string   
JsonArray array = JsonExtensions.asJsonArray(jsonObj, "key");

JsonArray jsonArray = new JsonArray();
// Add only if value is not null
JsonExtensions.addIfNotNull(jsonArray, value);
// Add only if json object is not empty
JsonExtensions.addIfNotEmpty(jsonArray, obj);

Config helper#


Please use general Vert.x Json extension functions!

val jsonObject = config.asJsonObject("key")
val jsonArray = config.asJsonArray("key")
// Old way
JsonObject jsonObject = ConfigHelper.forConfig(config).forceJsonObject("key");
JsonObject jsonArray = ConfigHelper.forConfig(config).forceJsonArray("key");

// New way
JsonObject jsonObject = JsonExtensions.asJsonObject(config, "key");
JsonObject jsonArray = JsonExtensions.asJsonArray(config, "key");