Home

Introduction

Usage

Versioning

---

Introduction

TraceProv is a Java library to model provenance of data from DCAT catalogs, which are represented using DCAT W3C vocabulary. At present also allows to reference data in sources having table-like formats such as CSV. TraceProv is versioned according to semantic versioning. If you wish to contribute to TraceProv development, see Contributing page. For other references, see Useful links page.

Usage

Maven

TODO

The API

Most objects in TraceProv are immutable, and make heavy use of Guava immutable collections . In TraceProv, wherever you see a class called 'AbstractSomething', there will always be an immutable class 'Something' implementing it.

Building objects

Immutable classes don't have public constructors, they only have factory methods called of(). So for example, to create a CellRef referring to a cell at row 1 and column 2 you would call:

CellRef cellRef = CellRef.of(1,2);

If the class has many fields, it will also provide a mutable Builder to create instances. So for example to build a DcatDataset object setting a fields title and landingPage you would call:

DcatDataset dataset = DcatDataset
                      .builder()
                      .putTitle(Locale.ITALIAN, "Impianti di risalita, ViviFiemme 2013")
                      .setLandingPage("http://dati.trentino.it/dataset/impianti-di-risalita-vivifiemme-2013")
                      .build();

Builder is mutable, while dataset object created after build is perfectly immutable. Notice string names are usually represented as Map<Locale,String> hence the putTitle above.

Logging

TraceProv uses native Java logging system (JUL). If you have an application which uses SLF4J logging system and want to see TraceProv logs, you can route logging with JUL to SLF4J bridge, just remember to programmatically install it first.

Versioning

1. For 0.MINOR.PATCH series, we will increase the MINOR at each change to the api, no matter how small it is. If we only change the javadoc without changing the api we increase the PATCH.

2. When we reach 1.0.0 we will follow semver.org rules:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.