org.eaglei.repository.model
Class Provenance

java.lang.Object
  org.eaglei.repository.model.Provenance

public class Provenance
extends java.lang.Object

Utility class to manage provenance metadata, whcih is a constellation of statements about a resource instance or Named Graph URI. A Provenance object models this metadata and provides convenient methods to read and set it. It supports the repo's underlying RDF ontology for provenance, mostly borrowed from Dublin Core. Other repo code accesses the provenance statements directly through SPARQL queries, so DO NOT CHANGE it. Note that one difficulty is how some objects of provenance statements are blank nodes (e.g. dcterms:source) and so the RDF has to be transformed into a flat model here with "virtual" predicates. This class also enforces the informal rule that the value of dcterms:modified MUST be a datatyped literal of the "dateTime" (or other comparable timestamp) type, so date comparisons can be done efficiently. This also applies to the date value of dcterms:created, although nothing yet depends on it as harvest does on modified. Another limitation is that only the latest value is recorded for each predicate, there is no history -- that decision was made to save space and processing time since we haven't got a complete use case for provenance yet anyway, really just the *latest* date for dcterms:modified. Provenance methods that change the "last modified" date of anything also update the global last-modified timestamp, maintained by the Lifecycle singleton.

Author:

Larry Stone

Field Summary

static org.openrdf.model.URI

PROVENANCE_GRAPH Graph where ALL provenance metadata is stored.

Constructor Summary

Provenance(org.openrdf.model.URI uri)
Constructor

Method Summary

java.lang.String	getField(javax.servlet.http.HttpServletRequest request, org.openrdf.model.URI field) getField - get the value of a provenance predicate.
static boolean	isProvenancePredicate(org.openrdf.model.URI pp) Predicate method, true if URI is a provenance predicate URI.
static org.openrdf.model.Literal	makeDateTime(java.util.Date when) Utility translation method, returns typed literal of specified moment
void	setCreated(javax.servlet.http.HttpServletRequest request, java.util.Date when) Convenience method to set Created provenance values, upon creation.
void	setMediated(javax.servlet.http.HttpServletRequest request, java.util.Date when) Convenience method to set provenance values for "mediated" creation, i.e.
void	setModified(javax.servlet.http.HttpServletRequest request, java.util.Date when) Convenience method to set provenance values upon last modification.
void	setProvenanceStatement(org.openrdf.repository.RepositoryConnection rc, org.openrdf.model.URI term, org.openrdf.model.Value value) Set provenance values directly, bypass e.g.
void	setSource(javax.servlet.http.HttpServletRequest request, java.lang.String source, java.util.Date sourceModified) Add/replace the Source provenance fields: dcterms:source -> bnode dcterms:identifier -> filename or URI it came from dcterms:modified -> last-mod date of source
void	setSourceStatements(org.openrdf.repository.RepositoryConnection rc, org.openrdf.model.Value source, org.openrdf.model.Value sourceModified) Convenience method to set source provenance identifier and last-mod time of resource ingested into a graph.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROVENANCE_GRAPH

public static final org.openrdf.model.URI PROVENANCE_GRAPH

Graph where ALL provenance metadata is stored.

Constructor Detail

Provenance

public Provenance(org.openrdf.model.URI uri)

Constructor

Parameters:

uri - the subject uri

Method Detail

isProvenancePredicate

public static boolean isProvenancePredicate(org.openrdf.model.URI pp)

Predicate method, true if URI is a provenance predicate URI.

Parameters:

pp - a URI object.

Returns:

true if pp names a provenance predicate.

setCreated

public void setCreated(javax.servlet.http.HttpServletRequest request,
                       java.util.Date when)

Convenience method to set Created provenance values, upon creation. Also sets Modified provenance metadata automatically, since the last-modified date is used to judge when a resource needs to be re-indexed.

Parameters:

request - a HttpServletRequest object.

when - time at which it was created

setMediated

public void setMediated(javax.servlet.http.HttpServletRequest request,
                        java.util.Date when)

Convenience method to set provenance values for "mediated" creation, i.e. when instance already contains a dcterms:creator that has to be preserved. Record the creating user as dcterms:mediator instead.

Parameters:

request - a HttpServletRequest object.

when - time at which it was created

setModified

public void setModified(javax.servlet.http.HttpServletRequest request,
                        java.util.Date when)

Convenience method to set provenance values upon last modification.

Parameters:

request - a HttpServletRequest object.

when - time at which it was last modified

setProvenanceStatement

public void setProvenanceStatement(org.openrdf.repository.RepositoryConnection rc,
                                   org.openrdf.model.URI term,
                                   org.openrdf.model.Value value)

Set provenance values directly, bypass e.g. the automatic use of current authenticated user. Needed on rare occasions such as bootstrap graph setup where the actor is the system itself. THIS IS DANGEROUS, since it does NOT type-check that the value of a time property (e.g. dcterms:modified) is a calendar literal.

Parameters:

rc - a RepositoryConnection object.

term - a provenance predicate, a URI object.

value - a Value object.

setSource

public void setSource(javax.servlet.http.HttpServletRequest request,
                      java.lang.String source,
                      java.util.Date sourceModified)

Add/replace the Source provenance fields: dcterms:source -> bnode dcterms:identifier -> filename or URI it came from dcterms:modified -> last-mod date of source

Parameters:

request - a HttpServletRequest object.

source - value of identifier, a String object.

sourceModified - mod time for source or null if unknown.

setSourceStatements

public void setSourceStatements(org.openrdf.repository.RepositoryConnection rc,
                                org.openrdf.model.Value source,
                                org.openrdf.model.Value sourceModified)

Convenience method to set source provenance identifier and last-mod time of resource ingested into a graph. This is worth the trouble since it is useful to test for graphs that need updating. THIS IS DANGEROUS, since it does NOT type-check that the value of a time property (e.g. dcterms:modified) is a calendar literal.

Parameters:

rc - a RepositoryConnection object.

source - value of identifier, a String object.

sourceModified - mod time for source or null if unknown.

makeDateTime

public static org.openrdf.model.Literal makeDateTime(java.util.Date when)

Utility translation method, returns typed literal of specified moment

Parameters:

when - a Date object.

Returns:

specified 'when' as a Literal object.

getField

public java.lang.String getField(javax.servlet.http.HttpServletRequest request,
                                 org.openrdf.model.URI field)

getField - get the value of a provenance predicate.

Parameters:

request - a HttpServletRequest object.

field - the URI of the metadata field

Returns:

value of the field or null if not set

Throws:

javax.servlet.ServletException - if any.