rdf 1.99.1 → 2.0.0.beta1

data/lib/rdf/query/solutions.rb

@@ -112,7 +112,7 @@ module RDF; class Query
     # @yield  [solution]
     # @yieldparam  [RDF::Query::Solution] solution
     # @yieldreturn [Boolean]
-    # @return [void] `self`
+    # @return [self]
     def filter(criteria = {})
       if block_given?
         self.reject! do |solution|
@@ -164,7 +164,7 @@ module RDF; class Query
     # @yieldparam  [RDF::Query::Solution] q
     # @yieldparam  [RDF::Query::Solution] b
     # @yieldreturn [Integer] -1, 0, or 1 depending on value of comparator
-    # @return [void] `self`
+    # @return [self]
     def order(*variables)
       if variables.empty? && !block_given?
         raise ArgumentError, "wrong number of arguments (0 for 1)"
@@ -191,7 +191,7 @@ module RDF; class Query
     # Restricts this solution sequence to the given `variables` only.
     #
     # @param  [Array<Symbol, #to_sym>] variables
-    # @return [void] `self`
+    # @return [self]
     def project(*variables)
       if variables.empty?
         raise ArgumentError, "wrong number of arguments (0 for 1)"
@@ -208,7 +208,7 @@ module RDF; class Query
     ##
     # Ensures that the solutions in this solution sequence are unique.
     #
-    # @return [void] `self`
+    # @return [self]
     def distinct
       self.uniq!
       self
@@ -223,7 +223,7 @@ module RDF; class Query
     #
     # @param  [Integer, #to_i] start
     #   zero or a positive or negative integer
-    # @return [void] `self`
+    # @return [self]
     def offset(start)
       case start = start.to_i
         when 0 then nil
@@ -239,7 +239,7 @@ module RDF; class Query
     #
     # @param  [Integer, #to_i] length
     #   zero or a positive integer
-    # @return [void] `self`
+    # @return [self]
     # @raise  [ArgumentError] if `length` is negative
     def limit(length)
       length = length.to_i

data/lib/rdf/reader.rb

@@ -39,6 +39,7 @@ module RDF
   class Reader
     extend  ::Enumerable
     extend  RDF::Util::Aliasing::LateBound
+    include RDF::Util::Logger
     include RDF::Readable
     include RDF::Enumerable # @since 0.3.0
 
@@ -108,6 +109,52 @@ module RDF
       end
     end
 
+    ##
+    # Options suitable for automatic Reader provisioning.
+    # @return [Array<RDF::CLI::Option>]
+    def self.options
+      [
+        RDF::CLI::Option.new(
+          symbol: :canonicalize,
+          datatype: TrueClass,
+          on: ["--canonicalize"],
+          description: "Canonicalize input/output.") {true},
+        RDF::CLI::Option.new(
+          symbol: :encoding,
+          datatype: Encoding,
+          on: ["--encoding ENCODING"],
+          description: "The encoding of the input stream.") {|arg| Encoding.find arg},
+        RDF::CLI::Option.new(
+          symbol: :intern,
+          datatype: TrueClass,
+          on: ["--intern"],
+          description: "Intern all parsed URIs.") {true},
+        RDF::CLI::Option.new(
+          symbol: :prefixes,
+          datatype: Hash,
+          multiple: true,
+          on: ["--prefixes PREFIX,PREFIX"],
+          description: "A comma-separated list of prefix:uri pairs.") do |arg|
+            arg.split(',').inject({}) do |memo, pfxuri|
+              pfx,uri = pfxuri.split(':', 2)
+              memo.merge(pfx.to_sym => RDF::URI(uri))
+            end
+        end,
+        RDF::CLI::Option.new(
+          symbol: :base_uri,
+          datatype: RDF::URI,
+          on: ["--uri URI"],
+          description: "Base URI of input file, defaults to the filename.") {|arg| RDF::URI(arg)},
+        RDF::CLI::Option.new(
+          symbol: :validate,
+          datatype: TrueClass,
+          on: ["--validate"],
+          description: "Validate input file.") {true},
+      ]
+    end
+
+    # Returns a hash of options appropriate for use with this reader
+    
     class << self
       alias_method :format_class, :format
     end
@@ -125,20 +172,21 @@ module RDF
     #   end
     #
     # @param  [String, #to_s] filename
+    # @param [Symbol] format
     # @param  [Hash{Symbol => Object}] options
     #   any additional options (see {RDF::Util::File.open_file}, {RDF::Reader#initialize} and {RDF::Format.for})
-    # @option options [Symbol] :format (:ntriples)
     # @yield  [reader]
     # @yieldparam  [RDF::Reader] reader
     # @yieldreturn [void] ignored
     # @raise  [RDF::FormatError] if no reader found for the specified format
-    def self.open(filename, options = {}, &block)
+    def self.open(filename, format: nil, **options, &block)
       Util::File.open_file(filename, options) do |file|
         format_options = options.dup
         format_options[:content_type] ||= file.content_type if file.respond_to?(:content_type)
         format_options[:file_name] ||= filename
         options[:encoding] ||= file.encoding if file.respond_to?(:encoding)
-        reader = self.for(format_options[:format] || format_options) do
+        options[:filename] ||= filename
+        reader = self.for(format || format_options) do
           # Return a sample from the input file
           sample = file.read(1000)
           file.rewind
@@ -350,7 +398,7 @@ module RDF
     #
     # @return [void]
     # @since  0.2.3
-    # @see    http://ruby-doc.org/core-1.9/classes/IO.html#M001692
+    # @see    http://ruby-doc.org/core-2.2.2/IO.html#method-i-rewind
     def rewind
       @input.rewind
     end
@@ -364,7 +412,7 @@ module RDF
     #
     # @return [void]
     # @since  0.2.2
-    # @see    http://ruby-doc.org/core-1.9/classes/IO.html#M001699
+    # @see    http://ruby-doc.org/core-2.2.2/IO.html#method-i-close
     def close
       @input.close unless @input.closed?
     end
@@ -380,16 +428,22 @@ module RDF
     ##
     # @return [Boolean]
     #
-    # @note this parses the full input. 
+    # @note this parses the full input and is valid only in the reader block.
     #   Use `Reader.new(input, validate: true)` if you intend to capture the 
     #   result.
     #
+    # @example Parsing RDF statements from a file
+    #   RDF::NTriples::Reader.new("!!invalid input??") do |reader|
+    #     reader.valid? # => false
+    #   end
+    #
     # @see RDF::Value#validate! for Literal & URI validation relevant to 
     #   error handling.
     # @see Enumerable#valid?
     def valid?
-      super 
-    rescue ArgumentError, RDF::ReaderError
+      super && !log_statistics[:error]
+    rescue ArgumentError, RDF::ReaderError => e
+      log_error(e.message)
       false
     end
 
@@ -421,8 +475,7 @@ module RDF
     # @return [void]
     # @raise  [RDF::ReaderError]
     def fail_subject
-      raise RDF::ReaderError.new("ERROR [line #{lineno}] Expected subject (found: #{current_line.inspect})",
-                                 lineno: lineno)
+      log_error("Expected subject (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)
     end
 
     ##
@@ -431,8 +484,7 @@ module RDF
     # @return [void]
     # @raise  [RDF::ReaderError]
     def fail_predicate
-      raise RDF::ReaderError.new("ERROR [line #{lineno}] Expected predicate (found: #{current_line.inspect})",
-                                 lineno: lineno)
+      log_error("Expected predicate (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)
     end
 
     ##
@@ -441,8 +493,7 @@ module RDF
     # @return [void]
     # @raise  [RDF::ReaderError]
     def fail_object
-      raise RDF::ReaderError.new("ERROR [line #{lineno}] Expected object (found: #{current_line.inspect})",
-                                 lineno: lineno)
+      log_error("Expected object (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)
     end
 
   public

data/lib/rdf/repository.rb

@@ -40,12 +40,55 @@ module RDF
   # @example Deleting all statements from a repository
   #   repository.clear!
   #
-  class Repository
-    include RDF::Countable
-    include RDF::Enumerable
-    include RDF::Queryable
+  # Repositories support transactions with a variety of ACID semantics:
+  # 
+  # Atomicity is indicated by `#supports?(:atomic_write)`. When atomicity is
+  # supported, writes through `#transaction`, `#apply_changeset` and 
+  # `#delete_insert` are applied atomically.
+  #
+  # Consistency should be guaranteed, in general. Repositories that don't 
+  # support consistency, or that have specialized definitions of consistency 
+  # above those declared by the RDF data model, should advertise this fact in
+  # their documentation.
+  #
+  # Isolation may be supported at various levels, indicated by 
+  # `#isolation_level`:
+  #   - `:read_uncommitted`: Inserts & deletes in an uncommitted transaction 
+  #      scope may be visible to other transactions (or via `#each`, etc...)
+  #   - `:read_committed`: Inserts & deletes may be visible to other 
+  #      transactions once committed
+  #   - `:repeatable_read`: Phantom reads may be possible
+  #   - `:snapshot`: A transaction reads a consistent snapshot of the data. 
+  #      Write skew anomalies may occur (for various definitions of consistency)
+  #   - `:serializable`: A transaction reads a consistent snapshot of the data.
+  #      When two or more transactions attempt conflicting writes, only one of
+  #      them may succeed.
+  #
+  # Durability is noted via `RDF::Durable` support and `#durable?`
+  # /`#nondurable?`.
+  #
+  # @example Transational read from a repository
+  #   repository.transaction do |tx|
+  #     tx.has_statement?(statement)
+  #     tx.query([:s, :p, :o])
+  #   end
+  #
+  # @example Transational read/write of a repository
+  #   repository.transaction(mutable: true) do |tx|
+  #     tx.insert(*statements)
+  #     tx.insert(statement)
+  #     tx.insert([subject, predicate, object])
+  #     tx.delete(*statements)
+  #     tx.delete(statement)
+  #     tx.delete([subject, predicate, object])
+  #   end
+  # 
+  class Repository < Dataset
     include RDF::Mutable
-    include RDF::Durable
+
+    include RDF::Transactable
+
+    DEFAULT_TX_CLASS = RDF::Transaction
 
     ##
     # Returns the options passed to this repository when it was constructed.
@@ -69,16 +112,16 @@ module RDF
     ##
     # Loads one or more RDF files into a new transient in-memory repository.
     #
-    # @param  [String, Array<String>] filenames
+    # @param  [String, Array<String>] urls
     # @param  [Hash{Symbol => Object}] options
     #   Options from {RDF::Repository#initialize} and {RDF::Mutable#load}
     # @yield  [repository]
     # @yieldparam [Repository]
     # @return [void]
-    def self.load(filenames, options = {}, &block)
+    def self.load(urls, options = {}, &block)
       self.new(options) do |repository|
-        Array(filenames).each do |filename|
-          repository.load(filename, options)
+        Array(urls).each do |url|
+          repository.load(url, options)
         end
 
         if block_given?
@@ -93,28 +136,28 @@ module RDF
     ##
     # Initializes this repository instance.
     #
-    # @param  [Hash{Symbol => Object}] options
-    # @option options [URI, #to_s]    :uri (nil)
-    # @option options [String, #to_s] :title (nil)
-    # @option options [Boolean] :with_graph_name (true)
+    # @param [URI, #to_s]    uri (nil)
+    # @param [String, #to_s] title (nil)
+    # @param [Hash{Symbol => Object}] options
+    # @option options [Boolean]   :with_graph_name (true)
     #   Indicates that the repository supports named graphs, otherwise,
     #   only the default graph is supported.
-    # @option options [Boolean] :with_context (true)
-    #   Alias for :with_graph_name. :with_context is deprecated in RDF.rb 2.0.
+    # @option options [Boolean]   :with_validity (true)
+    #   Indicates that the repository supports named validation.
+    # @option options [Boolean]   :transaction_class (DEFAULT_TX_CLASS)
+    #   Specifies the RDF::Transaction implementation to use in this Repository.
     # @yield  [repository]
     # @yieldparam [Repository] repository
-    def initialize(options = {}, &block)
-      if options[:with_context]
-        warn "[DEPRECATION] the :contexts option to Repository#initialize is deprecated in RDF.rb 2.0, use :graph_name instead. Called from #{Gem.location_of_caller.join(':')}"
-        options[:graph_name] ||= options.delete(:with_context)
-      end
-      @options = {with_graph_name: true}.merge(options)
-      @uri     = @options.delete(:uri)
-      @title   = @options.delete(:title)
+    def initialize(uri: nil, title: nil, **options, &block)
+      @options = {with_graph_name: true, with_validity: true}.merge(options)
+      @uri     = uri
+      @title   = title
 
       # Provide a default in-memory implementation:
       send(:extend, Implementation) if self.class.equal?(RDF::Repository)
 
+      @tx_class ||= @options.delete(:transaction_class) { DEFAULT_TX_CLASS }
+
       if block_given?
         case block.arity
           when 1 then block.call(self)
@@ -124,109 +167,90 @@ module RDF
     end
 
     ##
-    # Returns a developer-friendly representation of this object.
+    # Returns `true` if this respository supports the given `feature`.
     #
-    # @return [String]
-    def inspect
-      sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, uri.to_s)
+    # Supported features include those from {RDF::Enumerable#supports?} along 
+    #  with the following:
+    #   * `:atomic_write` supports atomic write in transaction scopes
+    #   * `:snapshots` supports creation of immutable snapshots of current 
+    #        contents via #snapshot.
+    # @see RDF::Enumerable#supports?
+    def supports?(feature)
+      case feature.to_sym
+      when :graph_name   then @options[:with_graph_name]
+      when :inference    then false  # forward-chaining inference
+      when :validity     then @options.fetch(:with_validity, true)
+      when :atomic_write then false
+      when :snapshots    then false
+      else false
+      end
     end
 
     ##
-    # Outputs a developer-friendly representation of this object to
-    # `stderr`.
+    # Performs a set of deletes and inserts as a combined operation within a 
+    # transaction. The Repository's transaction semantics apply to updates made
+    # through this method.
     #
-    # @return [void]
-    def inspect!
-      each_statement { |statement| statement.inspect! }
-      nil
-    end
+    # @see RDF::Mutable#delete_insert
+    def delete_insert(deletes, inserts)
+      return super unless supports?(:atomic_write)
 
-    ##
-    # Executes the given block in a transaction.
-    #
-    # @example
-    #   repository.transaction do |tx|
-    #     tx.insert [RDF::URI("http://rubygems.org/gems/rdf"), RDF::RDFS.label, "RDF.rb"]
-    #   end
-    #
-    # @param  [RDF::Resource] graph_name
-    #   Context on which to run the transaction, use `false` for the default
-    #   graph_name and `nil` the entire Repository
-    # @yield  [tx]
-    # @yieldparam  [RDF::Transaction] tx
-    # @yieldreturn [void] ignored
-    # @return [self]
-    # @see    RDF::Transaction
-    # @since  0.3.0
-    def transaction(graph_name = nil, &block)
-      tx = begin_transaction(graph_name)
-      begin
-        case block.arity
-          when 1 then block.call(tx)
-          else tx.instance_eval(&block)
-        end
-      rescue => error
-        rollback_transaction(tx)
-        raise error
+      transaction(mutable: true) do
+        deletes.respond_to?(:each_statement) ? delete(deletes) : delete(*deletes)
+        inserts.respond_to?(:each_statement) ? insert(inserts) : insert(*inserts)
       end
-      commit_transaction(tx)
-      self
     end
-    alias_method :transact, :transaction
-
-  protected
 
     ##
-    # Begins a new transaction.
-    #
-    # Subclasses implementing transaction-capable storage adapters may wish
-    # to override this method in order to begin a transaction against the
-    # underlying storage.
-    #
-    # @param  [RDF::Resource] graph_name
-    # @return [RDF::Transaction]
-    # @since  0.3.0
-    def begin_transaction(graph_name)
-      RDF::Transaction.new(graph: graph_name)
+    # @private
+    # @see RDF::Enumerable#project_graph
+    def project_graph(graph_name, &block)
+      RDF::Graph.new(graph_name: graph_name, data: self).
+        project_graph(graph_name, &block)
     end
 
     ##
-    # Rolls back the given transaction.
-    #
-    # Subclasses implementing transaction-capable storage adapters may wish
-    # to override this method in order to roll back the given transaction in
-    # the underlying storage.
-    #
-    # @param  [RDF::Transaction] tx
-    # @return [void] ignored
-    # @since  0.3.0
-    def rollback_transaction(tx)
-      # nothing to do
+    # @see RDF::Dataset#isolation_level
+    def isolation_level
+      supports?(:snapshot) ? :repeatable_read : super
     end
 
     ##
-    # Commits the given transaction.
-    #
-    # Subclasses implementing transaction-capable storage adapters may wish
-    # to override this method in order to commit the given transaction to
-    # the underlying storage.
-    #
-    # @param  [RDF::Transaction] tx
-    # @return [void] ignored
-    # @since  0.3.0
-    def commit_transaction(tx)
-      tx.execute(self)
+    # A queryable snapshot of the repository for isolated reads.
+    # 
+    # @return [Dataset] an immutable Dataset containing a current snapshot of
+    #   the Repository contents.
+    def snapshot
+      raise NotImplementedError.new("#{self.class}#snapshot")
     end
+    
+    protected
+
+      ##
+      # @private
+      # @see RDF::Transactable#begin_transaction
+      # @since  0.3.0
+      def begin_transaction(mutable: false, graph_name: nil)
+        @tx_class.new(self, mutable: mutable, graph_name: graph_name)
+      end
 
     ##
+    # A default Repository implementation supporting atomic writes and 
+    # serializable transactions.
+    #
     # @see RDF::Repository
     module Implementation
+      require 'hamster'
       DEFAULT_GRAPH = false
 
       ##
       # @private
       def self.extend_object(obj)
-        obj.instance_variable_set(:@data, obj.options.delete(:data) || {})
+        obj.instance_variable_set(:@data, obj.options.delete(:data) || 
+                                          Hamster::Hash.new)
+        obj.instance_variable_set(:@tx_class, 
+                                  obj.options.delete(:transaction_class) || 
+                                  SerializedTransaction)
         super
       end
 
@@ -235,49 +259,66 @@ module RDF
       # @see RDF::Enumerable#supports?
       def supports?(feature)
         case feature.to_sym
-          #statement named graphs
-          when :context
-            warn "[DEPRECATION] the :context feature is deprecated in RDF.rb 2.0; use :graph_name instead. Called from #{Gem.location_of_caller.join(':')}"
-            @options[:with_context] || @options[:with_graph_name]
-          when :graph_name   then @options[:with_graph_name]
-          when :inference then false  # forward-chaining inference
-          when :validity  then @options.fetch(:with_validity, true)
-          else false
+        when :graph_name   then @options[:with_graph_name]
+        when :inference    then false  # forward-chaining inference
+        when :validity     then @options.fetch(:with_validity, true)
+        when :atomic_write then true
+        when :snapshots    then true
+        else false
         end
       end
 
+      ##
+      # @private
+      # @see RDF::Countable#count
+      def count
+        count = 0
+        @data.each do |_, ss|
+          ss.each do |_, ps|
+            ps.each { |_, os| count += os.size }
+          end
+        end
+        count
+      end
+      
       ##
       # @private
       # @see RDF::Durable#durable?
       def durable?
         false
       end
+      
+      ##
+      # @private
+      # @see RDF::Enumerable#has_graph?      
+      def has_graph?(graph)
+        @data.has_key?(graph)
+      end
 
       ##
       # @private
-      # @see RDF::Countable#count
-      def count
-        count = 0
-        @data.each do |g, ss|
-          ss.each do |s, ps|
-            ps.each do |p, os|
-              count += os.size
-            end
+      # @see RDF::Enumerable#each_graph
+      def graph_names(options = nil, &block)        
+        @data.keys.reject { |g| g == DEFAULT_GRAPH }.to_a
+      end
+
+      ##
+      # @private
+      # @see RDF::Enumerable#each_graph
+      def each_graph(&block)
+        if block_given?
+          @data.each_key do |gn|
+            yield RDF::Graph.new(graph_name: (gn == DEFAULT_GRAPH ? nil : gn), data: self)
           end
         end
-        count
+        enum_graph
       end
 
       ##
       # @private
       # @see RDF::Enumerable#has_statement?
       def has_statement?(statement)
-        s, p, o, g = statement.to_quad
-        g ||= DEFAULT_GRAPH
-        @data.has_key?(g) &&
-          @data[g].has_key?(s) &&
-          @data[g][s].has_key?(p) &&
-          @data[g][s][p].include?(o)
+        has_statement_in?(@data, statement)
       end
 
       ##
@@ -285,16 +326,11 @@ module RDF
       # @see RDF::Enumerable#each_statement
       def each_statement(&block)
         if block_given?
-          # Note that to iterate in a more consistent fashion despite
-          # possible concurrent mutations to `@data`, we use `#dup` to make
-          # shallow copies of the nested hashes before beginning the
-          # iteration over their keys and values.
-          @data.dup.each do |g, ss|
-            ss.dup.each do |s, ps|
-              ps.dup.each do |p, os|
-                os.dup.each do |o|
-                  # FIXME: yield has better performance, but broken in MRI 2.2: See https://bugs.ruby-lang.org/issues/11451.
-                  block.call(RDF::Statement.new(s, p, o, graph_name: g.equal?(DEFAULT_GRAPH) ? nil : g))
+          @data.each do |g, ss|
+            ss.each do |s, ps|
+              ps.each do |p, os|
+                os.each do |o|
+                  yield RDF::Statement.new(s, p, o, graph_name: g.equal?(DEFAULT_GRAPH) ? nil : g)
                 end
               end
             end
@@ -305,92 +341,81 @@ module RDF
       alias_method :each, :each_statement
 
       ##
-      # @private
-      # @see RDF::Enumerable#has_context?
-      # @deprecated Use {#has_graph?} instead.
-      def has_context?(value)
-       warn "[DEPRECATION] Repository#has_context? is deprecated in RDF.rb 2.0, use Repository#has_graph? instead. Called from #{Gem.location_of_caller.join(':')}"
-       has_graph?(value)
+      # @see Mutable#apply_changeset
+      def apply_changeset(changeset)
+        data = @data
+        changeset.deletes.each { |del| data = delete_from(data, del) }
+        changeset.inserts.each { |ins| data = insert_to(data, ins) }
+        @data = data
       end
 
       ##
-      # @private
-      # @see RDF::Enumerable#has_graph?
-      def has_graph?(value)
-        @data.keys.include?(value)
-      end
-      ##
-      # @private
-      # @see RDF::Enumerable#each_graph
-      def graph_names(options = nil, &block)
-        @data.keys.reject {|g| g == DEFAULT_GRAPH}
+      # @see RDF::Dataset#isolation_level
+      def isolation_level
+        :serializable
       end
 
       ##
-      # @private
-      # @see RDF::Enumerable#each_context
-      # @deprecated Use {#each_graph} instead.
-      def each_context(&block)
-        warn "[DEPRECATION] Repository#each_context is deprecated in RDF.rb 2.0, use Repository#each_graph instead. Called from #{Gem.location_of_caller.join(':')}"
-        if block_given?
-          contexts = @data.keys
-          contexts.delete(DEFAULT_GRAPH)
-          contexts.each(&block)
-        end
-        enum_context
+      # A readable & queryable snapshot of the repository for isolated reads. 
+      # 
+      # @return [Dataset] an immutable Dataset containing a current snapshot of
+      #   the Repository contents.
+      #
+      # @see Mutable#snapshot
+      def snapshot
+        self.class.new(data: @data).freeze
       end
 
-      ##
-      # @private
-      # @see RDF::Enumerable#each_graph
-      def each_graph(&block)
-        if block_given?
-          @data.each_key do |gn|
-            yield RDF::Graph.new(gn == DEFAULT_GRAPH ? nil : gn, data: self)
-          end
-        end
-        enum_graph
-      end
-
-    protected
+      protected
 
       ##
-      # Match elements with eql?, not ==
-      # Context of `false` matches default graph. Unbound variable matches non-false graph name
+      # Match elements with `eql?`, not `==`
+      #
+      # `graph_name` of `false` matches default graph. Unbound variable matches
+      # non-false graph name
+      #
       # @private
-      # @see RDF::Queryable#query
-      def query_pattern(pattern, &block)
-        graph_name  = pattern.graph_name
-        subject   = pattern.subject
-        predicate = pattern.predicate
-        object    = pattern.object
-
-        cs = @data.has_key?(graph_name) ? {graph_name => @data[graph_name]} : @data.dup
-        cs.each do |c, ss|
-          next unless graph_name.nil? || graph_name == false && !c || graph_name.eql?(c)
-          ss = if ss.has_key?(subject)
-                 { subject => ss[subject] }
-               elsif subject.nil? || subject.is_a?(RDF::Query::Variable)
-                 ss.dup
-               else
-                 []
-               end
-          ss.each do |s, ps|
-            ps = if ps.has_key?(predicate)
-                   { predicate => ps[predicate] }
-                 elsif predicate.nil? || predicate.is_a?(RDF::Query::Variable)
-                   ps.dup
+      # @see RDF::Queryable#query_pattern
+      def query_pattern(pattern, options = {}, &block)
+        snapshot = @data
+        if block_given?
+          graph_name  = pattern.graph_name
+          subject     = pattern.subject
+          predicate   = pattern.predicate
+          object      = pattern.object
+
+          cs = snapshot.has_key?(graph_name) ? { graph_name => snapshot[graph_name] } : snapshot
+
+          cs.each do |c, ss|
+            next unless graph_name.nil? ||
+                        graph_name == false && !c ||
+                        graph_name.eql?(c)
+
+            ss = if subject.nil? || subject.is_a?(RDF::Query::Variable)
+                   ss
+                 elsif ss.has_key?(subject)
+                   { subject => ss[subject] }
                  else
                    []
                  end
-            ps.each do |p, os|
-              os = os.dup # TODO: is this really needed?
-              os.each do |o|
-                next unless object.nil? || object.eql?(o)
-                block.call(RDF::Statement.new(s, p, o, graph_name: c.equal?(DEFAULT_GRAPH) ? nil : c))
+            ss.each do |s, ps|
+              ps = if predicate.nil? || predicate.is_a?(RDF::Query::Variable)
+                     ps
+                   elsif ps.has_key?(predicate)
+                     { predicate => ps[predicate] }
+                   else
+                     []
+                   end
+              ps.each do |p, os|
+                os.each do |o|
+                  next unless object.nil? || object.eql?(o)
+                  yield RDF::Statement.new(s, p, o, graph_name: c.equal?(DEFAULT_GRAPH) ? nil : c)
+                end
               end
             end
           end
+        else
+          enum_for(:query_pattern, pattern, options)
         end
       end
 
@@ -398,47 +423,158 @@ module RDF
       # @private
       # @see RDF::Mutable#insert
       def insert_statement(statement)
-        raise ArgumentError, "Statement #{statement.inspect} is incomplete" if statement.incomplete?
-        unless has_statement?(statement)
-          s, p, o, c = statement.to_quad
-          c = DEFAULT_GRAPH unless supports?(:graph_name)
-          c ||= DEFAULT_GRAPH
-          @data[c] ||= {}
-          @data[c][s] ||= {}
-          @data[c][s][p] ||= []
-          @data[c][s][p] << o
-        end
+        @data = insert_to(@data, statement)
       end
 
       ##
       # @private
       # @see RDF::Mutable#delete
       def delete_statement(statement)
-        if has_statement?(statement)
-          s, p, o, c = statement.to_quad
-          c = DEFAULT_GRAPH unless supports?(:graph_name)
-          c ||= DEFAULT_GRAPH
-          @data[c][s][p].delete(o)
-          @data[c][s].delete(p) if @data[c][s][p].empty?
-          @data[c].delete(s) if @data[c][s].empty?
-          @data.delete(c) if @data[c].empty?
-        end
+        @data = delete_from(@data, statement)
       end
 
       ##
       # @private
       # @see RDF::Mutable#clear
       def clear_statements
-        @data.clear
+        @data = @data.clear
+      end
+
+      ##
+      # @private
+      # @return [Hamster::Hash]
+      def data
+        @data
+      end
+
+      ##
+      # @private
+      # @return [Hamster::Hash]
+      def data=(hash)
+        @data = hash
+      end
+
+      private
+
+      ##
+      # @private
+      # @see #has_statement
+      def has_statement_in?(data, statement)
+        s, p, o, g = statement.to_quad
+        g ||= DEFAULT_GRAPH
+
+        data.has_key?(g) &&
+          data[g].has_key?(s) &&
+          data[g][s].has_key?(p) &&
+          data[g][s][p].include?(o)
       end
 
-      protected :query_pattern
-      protected :insert_statement
-      protected :delete_statement
-      protected :clear_statements
+      ##
+      # @private
+      # @return [Hamster::Hash] a new, updated hamster hash 
+      def insert_to(data, statement)
+        raise ArgumentError, "Statement #{statement.inspect} is incomplete" if statement.incomplete?
+
+        unless has_statement_in?(data, statement)
+          s, p, o, c = statement.to_quad
+          c ||= DEFAULT_GRAPH
+          
+          return data.put(c) do |subs|
+            subs = (subs || Hamster::Hash.new).put(s) do |preds|
+              preds = (preds || Hamster::Hash.new).put(p) do |objs|
+                (objs || Hamster::Set.new).add(o)
+              end
+            end
+          end
+        end
+        data
+      end
+      
+      ##
+      # @private
+      # @return [Hamster::Hash] a new, updated hamster hash 
+      def delete_from(data, statement)
+        if has_statement_in?(data, statement)
+          s, p, o, g = statement.to_quad
+          g = DEFAULT_GRAPH unless supports?(:graph_name)
+          g ||= DEFAULT_GRAPH
+
+          os   = data[g][s][p].delete(o)
+          ps   = os.empty? ? data[g][s].delete(p) : data[g][s].put(p, os)
+          ss   = ps.empty? ? data[g].delete(s)    : data[g].put(s, ps)
+          return ss.empty? ? data.delete(g) : data.put(g, ss)
+        end
+        data
+      end
+
+      ##
+      # A transaction for the Hamster-based `RDF::Repository::Implementation` 
+      # with full serializability.
+      # 
+      # @todo refactor me!
+      # @see RDF::Transaction
+      class SerializedTransaction < Transaction
+        ##
+        # @see Transaction#initialize
+        def initialize(*)
+          super
+          @base_snapshot = @snapshot
+        end
+        
+        ##
+        # Inserts the statement to the transaction's working snapshot.
+        #
+        # @see Transaction#insert_statement
+        def insert_statement(statement)
+          @snapshot = @snapshot.class
+            .new(data: @snapshot.send(:insert_to, 
+                                      @snapshot.send(:data), 
+                                      process_statement(statement)))
+        end
+
+        ##
+        # Deletes the statement from the transaction's working snapshot.
+        #
+        # @see Transaction#insert_statement
+        def delete_statement(statement)
+          @snapshot = @snapshot.class
+            .new(data: @snapshot.send(:delete_from, 
+                                      @snapshot.send(:data), 
+                                      process_statement(statement)))
+        end
+
+        ##
+        # @see RDF::Dataset#isolation_level
+        def isolation_level
+          :serializable
+        end
+        
+        ##
+        # Replaces repository data with the transaction's snapshot in a safely 
+        # serializable fashion.
+        # 
+        # @note this transaction uses a pessimistic merge strategy which 
+        #   fails the transaction if any data has changed in the repository
+        #   since transaction start time. However, the specific guarantee is 
+        #   softer: multiple concurrent conflicting transactions will not 
+        #   succeed. We may choose to implement a less pessimistic merge 
+        #   strategy as a non-breaking change.
+        # 
+        # @raise [TransactionError] when the transaction can't be merged.
+        # @see Transaction#execute
+        def execute
+          raise TransactionError, 'Cannot execute a rolled back transaction. ' \
+                                  'Open a new one instead.' if @rolledback
+
+          # `Hamster::Hash#==` will use a cheap `#equal?` check first, but fall 
+          # back on a full Ruby Hash comparison if required.
+          raise TransactionError, 'Error merging transaction. Repository' \
+                                  'has changed during transaction time.' unless 
+            repository.send(:data) == @base_snapshot.send(:data)
+
+          repository.send(:data=, @snapshot.send(:data))
+        end
+      end
     end # Implementation
   end # Repository
-
-  # RDF::Dataset is a synonym for RDF::Repository
-  Dataset = Repository
 end # RDF