Update RDF::Transaction

[gkellogg]

• A new class RDF::Changeset has been added. This is meant to replace any
  previous use of RDF::Transaction, which in fact used to in RDF.rb 1.x
  represent more of a buffered changeset than a genuine transaction scope.

  • Instead of RDF::Transaction.execute, use RDF::Changeset.apply.
  • Instead of RDF::Transaction#execute, use RDF::Changeset#apply.

• The RDF::Transaction class has been substantially revamped, including
  some minor backwards-incompatible changes. These changes will mostly
  affect repository implementors, not so much general RDF.rb users.

  The changes reflect the expanded purpose of the class: instead of being a
  mere buffered changeset (for which, see RDF::Changeset), transactions
  are now intended to provide a proper ACID scope for repository queries and
  mutations.

  We always now also carefully distinguish between read-only and read/write
  transactions, in order to enable repository implementations to take out the
  appropriate locks for concurrency control. Note as well that transactions
  are now read-only by default; mutability must be explicitly requested on
  construction in order to obtain a read/write transaction.

  In case repository implementations should be unable to provide actual ACID
  guarantees for transactions, that must be clearly indicated in their
  documentation. Similarly, implementations should throw an exception when
  appropriate in case they don't provide write transaction support.

  • RDF::Transaction#initialize now takes the target repository as its
    first argument. Transactions are now always tied to a specific
    repository instance, instead of being free-floating objects as they used
    to be (for that, see RDF::Changeset).
  • RDF::Transaction now mixes in RDF::Queryable and RDF::Enumerable,
    enabling quad-pattern matches and BGP queries to execute in a proper
    transaction scope.
  • The RDF::Transaction#context accessor, and its aliases, have been
    removed. Transactions aren't necessarily scoped to a single graph only.
  • There is a new RDF::Transaction#repository accessor for retrieving the
    target repository object that the transaction operates upon.
  • There is a new RDF::Transaction#buffered? predicate for testing
    whether the changeset that constitutes a transaction is available for
    introspection. Particular repository implementations may support both
    options and permit the user the choice on transaction construction.
  • The RDF::Transaction#inserts and #deletes methods are deprecated.
    Instead, there is a new RDF::Transaction#changes accessor to retrieve
    an RDF::Changeset instance, which contains corresponding methods.
    For unbuffered transactions, #changes returns nil.

[gkellogg]

Also see https://github.com/ruby-rdf/rdf/blob/feature/release-2_0/CHANGES.md

[gkellogg]

@gkellogg said:

Regarding the Transaction support for non-ACID backends; do you imagine that Changeset/Transaction can gracefully recover if such a repo raises an exception?

@bendiken replied:

Depends on whether the transaction is buffered or not (which can be a
user choice on construction); and this, of course, will also tie into
whether the backend can actually support readable intra-transaction
state or not. We'll probably need some 'flags' feature indication to
users on the capabilities provided by a particular backend. And then
have to make a choice for whether the SPARQL engine, when it would
need intra-transaction state, will explicitly bail out or instead just
silently use whatever (incorrect) state is available for reading.

[artob]

I have these changes in the works, will push to the 2.0 branch soon.

[no-reply]

The relevant changes via @bendiken are:

9c1b86e

rdf/lib/rdf/transaction.rb

Line 21 in 9c1b86e

# @example Executing a read-only transaction against a repository

[no-reply]

We merged initial transaction scopes & transactional repositories in #250.

Transactional reads are currently isolated as repeatable-read; we agreed to expand this to get fully (view-?)serializable transactions on the Hamster Repository.

Further, we agreed to drop Transaction#buffered?, replacing it with flags for isolation semantics. Perhaps something like #isolation_level, outputting one of :read_uncommittted :read_committed, :repeatable_read, :snapshot, or :serializable.

[no-reply]

We also agreed to complete the Dataset transition described at #188 (comment) as part of the transaction work.

[no-reply]

https://github.com/ruby-rdf/rdf/tree/feature/transaction-serializable & https://github.com/ruby-rdf/rdf-spec/tree/feature/serializable-transactions are the latest on this.

Known remaining TODOs are:

• Refactor the serializable transaction implementation to avoid #send calls.
• Consider whether #isolation_level properly belongs to Dataset (should it be in Repository? ...elsewhere?)
• Add documentation for isolation levels.
• Add tests for isolation levels; most importantly: add test coverage for the specific behavior of RDF::Repository::Implementation::SerializableTransaction
• Create examples for transactions.

There may be a handful of minor interface changes left to make.

[no-reply]

I went ahead and merged the above. Feedback would be useful at this point.

Particularly: Is Dataset scoped correctly? What should we assert about isolation levels in shared examples? Where is documentation lax?

I'm working on specs to cover gaps introduced by the addition of #267. This seems like the highest priority. At this point, we have tests to ensure that transactions are used, and that they are atomic, but the other features of the Hamster repository's transactions are untested.

[gkellogg]

Note the problem I pointed out on SPARQL::Client::Repository. Similar issues may exist for others, such as RDF::Mongo.