Maven

TraceProv is available on Maven Central. To use it, put this in the dependencies section of your pom.xml:

<dependency>
    <groupId>eu.trentorise.opendata</groupId>
    <artifactId>traceprov</artifactId>
    <version>0.3.0</version>
</dependency>

In case updates are available, version numbers follow semantic versioning rules.

Building objects

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

Immutable classes don't have public constructors, they only have factory methods called of() or builder(). 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()                
                .setTitle(Dict.of(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.

DCAT

Dcat vocabulary implementation in TraceProv tries to follow DCAT AP 1.1 specs, adapting it to possibly dirty data. For spatial data we use GeoJson and for temporal data see TOD Commons guidelines.

Serialization

Serialization to/from Json is done with Jackson. In order to succesfully ser/deserialize TraceProv objects, you first need to register TraceProvModule and other needed modules in your own Jackson ObjectMapper:

	ObjectMapper om = new ObjectMapper();
	om.registerModule(new GuavaModule());
	om.registerModule(new TodCommonsModule());
	om.registerModule(new TraceProvModule()); 
        
	String json = om.writeValueAsString(
    					DcatDataset.builder()
                		.setTitle(Dict.of("hello"))
                .		build());
	System.out.println(json);
	DcatDataset reconstructedDataset = om.readValue(json, DcatDataset.class);

Notice we have also registered the necessary Guava (for immutable collections) and Tod Commons modules (for Dict and LocalizedString).
To register everything in one command just write:

	ObjectMapper om = new ObjectMapper();
	TraceProvModule.registerModulesInto(om);       
  

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.