SWI-Prolog -- Enriching the journals

Documentation
- Reference manual
- Packages
  - SWI-Prolog Semantic Web Library 3.0
    - Plugin modules for rdf_db
      - library(semweb/rdf_persistency): Providing persistent storage
        
        rdf_attach_db/2
        
        rdf_detach_db/0
        
        rdf_current_db/1
        
        rdf_persistency/2
        
        rdf_flush_journals/1
        
        Enriching the journals
        
        rdf_journal_file/2
        
        rdf_db_to_file/2

4.6.1 Enriching the journals

The above predicates suffice for most applications. The predicates in this section provide access to the journal files and the base state files and are intended to provide additional services, such as reasoning about the journals, loaded files, etc.^{3A
library library(rdf_history) is under development
exploiting these features supporting wiki style editing of RDF.}

Using rdf_transaction(Goal, log(Message)), we can add additional records to enrich the journal of affected databases with Term and some additional bookkeeping information. Such a transaction adds a term begin(Id, Nest, Time, Message) before the change operations on each affected database and end(Id, Nest, Affected) after the change operations. Here is an example call and content of the journal file mydb.jrn. A full explanation of the terms that appear in the journal is in the description of rdf_journal_file/2.

?- rdf_transaction(rdf_assert(s,p,o,mydb), log(by(jan))).

start([time(1183540570)]).
begin(1, 0, 1183540570.36, by(jan)).
assert(s, p, o).
end(1, 0, []).
end([time(1183540578)]).

Using rdf_transaction(Goal, log(Message, DB)), where DB is an atom denoting a (possibly empty) named graph, the system guarantees that a non-empty transaction will leave a possibly empty transaction record in DB. This feature assumes named graphs are named after the user making the changes. If a user action does not affect the user's graph, such as deleting a triple from another graph, we still find record of all actions performed by some user in the journal of that user.

rdf_journal_file(?DB, ?JournalFile)

True if File is the absolute file name of an existing named graph DB. A journal file contains a sequence of Prolog terms of the following format.^{4Future versions
of this library may use an XML based language neutral format.}

start(Attributes): Journal has been opened. Currently Attributes contains a term time(Stamp).
end(Attributes): Journal was closed. Currently Attributes contains a term time(Stamp).
assert(Subject, Predicate, Object): A triple {Subject, Predicate, Object} was added to the database.
assert(Subject, Predicate, Object, Line): A triple {Subject, Predicate, Object} was added to the database with given Line context.
retract(Subject, Predicate, Object): A triple {Subject, Predicate, Object} was deleted from the database. Note that an rdf_retractall/3 call can retract multiple triples. Each of them have a record in the journal. This allows for‘undo’.
retract(Subject, Predicate, Object, Line): Same as above, for a triple with associated line info.
update(Subject, Predicate, Object, Action): See rdf_update/4.
begin(Id, Nest, Time, Message): Added before the changes in each database affected by a transaction with transaction identifier log(Message). Id is an integer counting the logged transactions to this database. Numbers are increasing and designed for binary search within the journal file. Nest is the nesting level, where‘0’is a toplevel transaction. Time is a time-stamp, currently using float notation with two fractional digits. Message is the term provided by the user as argument of the log(Message) transaction.
end(Id, Nest, Others): Added after the changes in each database affected by a transaction with transaction identifier log(Message). Id and Nest match the begin-term. Others gives a list of other databases affected by this transaction and the Id of these records. The terms in this list have the format DB:Id.

rdf_db_to_file(?DB, ?FileBase)

Convert between DB (see rdf_source/1) and file base-file used for storing information on this database. The full file is located in the directory described by rdf_current_db/1 and has the extension .trp for the base state and .jrn for the journal.