This project has retired. For details please refer to its Attic page.
Apache Marmotta - KiWi Versioning

KiWi Versioning

The KiWi Versioning module allows logging of updates to the triple store as well as accessing snapshots of the triple store at any given time in history. In many ways, it is similar to the history functionality offered by Wiki systems. KiWi Versioning can be useful for many purposes:

Currently, the KiWi Versioning module allows tracking changes and creating snapshots. Reverting changes has not yet been implemented and will be added later (together with support for pruning old versions).

Versioning is tightly bound to the transaction support: a version is more or less the transaction data after commit time. This corresponds to the concept of “unit of work”: a unit of work is finished when the user explicitly commits the transaction (e.g. when the entity has been completely added with all its triples or the ontology has been completely imported).

Maven Artifact

The KiWi Versioning module can only be used in conjunction with the KiWi Triple Store, because it maintains most of its information in the relational database (e.g. the data structures for change tracking). To include it in a project that uses the KiWi Triple Store, add the following dependency to your Maven project:

 <dependency>
     <groupId>org.apache.marmotta</groupId>
     <artifactId>kiwi-versioning</artifactId>
     <version>3.3.0</version>
 </dependency>

Code Usage

You can use the KiWi Versioning module in your own code in a sail stack with a KiWi transactional sail and a KiWi Store at the root. The basic usage is as follows:

KiWiStore store = new KiWiStore("test",jdbcUrl,jdbcUser,jdbcPass,dialect, "http://localhost/context/default", "http://localhost/context/inferred");
KiWiTransactionalSail tsail = new KiWiTransactionalSail(store);
KiWiVersioningSail vsail = new KiWiVersioningSail(tsail);
repository = new SailRepository(vsail);
repository.initialize();

// do something with the repository (e.g. add data)
...

// list all versions (note that there are many methods with different parameters, including a subject resource,
// a date range, or both)
RepositoryResult<Version> versions = vsail.listVersions();
try {
    while(versions.hasNext()) {
        Version v = version.next();

        // do something with v
    }
} finally {
    versions.close();
}

// get a snapshot connection for a certain date
Date snapshotDate = new Date(...);
RepositoryConnection snapshotConnection = vsail.getSnapshot(snapshotDate);
try {
    // access the triples in the snapshot as they were at the time of the snapshot
    ...
} finally {
    snapshotConnection.close();
}

Note that for obvious reasons (you cannot change history!), a snapshot connection is read-only. Accessing any update functionality of the connection will throw a RepositoryException. However, you can of course even run SPARQL queries over a snapshot connection (SPARQLing the past…).

Performance Considerations

When versioning is enabled, bear in mind that nothing is ever really deleted in the triple store. Triples that are removed in one of the updates are simply marked as “deleted” and added to the version information for removed triples.

Otherwise there is no considerable performance impact. Accessing snapshots at any date is essentially as efficient as any ordinary triple access (but it does not do triple caching).