active-triples 0.7.6 → 0.8.0

data/lib/active_triples/persistence_strategies/parent_strategy.rb

@@ -0,0 +1,89 @@
+module ActiveTriples
+  ##
+  # Persistence strategy for projecting `RDFSource`s onto the graph of an owning
+  # parent source. This allows individual resources to be treated as within the
+  # scope of another `RDFSource`.
+  class ParentStrategy
+    include PersistenceStrategy
+
+    # @!attribute [r] obj
+    #   the source to persist with this strategy
+    # @!attribute [r] parent
+    #   the target parent source for persistence
+    attr_reader :obj, :parent
+
+    ##
+    # @param obj [RDFSource, RDF::Enumerable] the `RDFSource` (or other
+    #   `RDF::Enumerable` to persist with the strategy.
+    def initialize(obj)
+      @obj = obj
+    end
+
+    def destroy
+      super { parent.destroy_child(obj) }
+    end
+
+    # Clear out any old assertions in the repository about this node or statement
+    # thus preparing to receive the updated assertions.
+    def erase_old_resource
+      if obj.rdf_subject.node?
+        final_parent.statements.each do |statement|
+          final_parent.send(:delete_statement, statement) if
+            statement.subject == obj.rdf_subject
+        end
+      else
+        final_parent.delete [obj.rdf_subject, nil, nil]
+      end
+    end
+
+    ##
+    # @return [#persist!] the last parent in a chain from `parent` (e.g.
+    #   the parent's parent's parent). This is the RDF::Mutable that the
+    #   object will project itself on when persisting.
+    def final_parent
+      raise NilParentError if parent.nil?
+      @final_parent ||= begin
+        current = self.parent
+        while current && current.respond_to?(:parent) && current.parent
+          break if current.parent == current
+          current = current.parent
+        end
+        current
+      end
+    end
+
+    ##
+    # Sets the target "parent" source for persistence operations.
+    #
+    # @param parent [RDFSource] source with a persistence strategy,
+    #   must be mutable.
+    def parent=(parent)
+      raise UnmutableParentError unless parent.is_a? RDF::Mutable
+      raise UnmutableParentError unless parent.mutable?
+      @parent = parent
+    end
+
+    ##
+    # Persists the object to the final parent.
+    #
+    # @return [true] true if the save did not error
+    def persist!
+      erase_old_resource
+      final_parent << obj
+      @persisted = true
+    end
+
+    ##
+    # Repopulates the graph from parent.
+    #
+    # @return [Boolean]
+    def reload
+      obj << final_parent.query(subject: obj.rdf_subject)
+      @persisted = true unless obj.empty?
+      true
+    end
+
+    class NilParentError < RuntimeError; end
+    class UnmutableParentError < ArgumentError; end
+  end
+end

data/lib/active_triples/persistence_strategies/persistence_strategy.rb

@@ -0,0 +1,77 @@
+module ActiveTriples
+  ##
+  # @abstract defines the basic interface for persistence of {RDFSource}'s.
+  #
+  # A `PersistenceStrategy` has an underlying object (`obj`) which should 
+  # be an `RDFSource` or equivalent. Strategies can be injected into `RDFSource`
+  # instances at runtime to change the target datastore, repository, or object 
+  # the instance syncs its graph with on save and reload operations.
+  #
+  # @example Changing a PersistenceStrategy at runtime
+  #    source = ActiveTriples::Resource.new
+  #    source.persistence_strategy # => #<ActiveTriples::RepositoryStrategy:...>
+  #   
+  #    source.set_persistence_strategy(MyStrategy)
+  #    source.persistence_strategy # => #<ActiveTriples::MyStrategy:...>
+  #
+  module PersistenceStrategy
+    ##
+    # Deletes the resource from the repository.
+    #
+    # @yield prior to persisting, yields to allow a block that performs
+    #   deletions in the persisted graph(s).
+    # @return [Boolean] true if the resource was sucessfully destroyed
+    def destroy(&block)
+      obj.clear
+      yield if block_given?
+      persist!
+      @destroyed = true
+    end
+    alias_method :destroy!, :destroy
+
+    ##
+    # Indicates if the Resource has been destroyed.
+    #
+    # @return [true, false]
+    def destroyed?
+      @destroyed ||= false
+    end
+
+    ##
+    # Indicates if the resource is persisted to the repository
+    #
+    # @return [Boolean] true if persisted; else false.
+    def persisted?
+      @persisted ||= false
+    end
+
+    ##
+    # @abstract save the object according to the strategy and set the 
+    #   @persisted flag to `true`
+    #
+    # @see #persisted?
+    #
+    # @return [true] true if the save did not error
+    def persist!
+      raise NotImplementedError, 'Abstract method #persist! is unimplemented'
+    end
+
+    ##
+    # @abstract Clear out any old assertions in the repository about this node 
+    # or statement thus preparing to receive the updated assertions.
+    #
+    # @return [Boolean]
+    def erase_old_resource
+      raise NotImplementedError, 
+            'Abstract method #erase_old_resource is unimplemented'
+    end
+
+    ##
+    # @abstract Repopulate the in-memory graph from the persisted graph
+    #
+    # @return [Boolean]
+    def reload
+      raise NotImplementedError, 'Abstract method #reload is unimplemented'
+    end
+  end
+end

data/lib/active_triples/persistence_strategies/repository_strategy.rb

@@ -0,0 +1,78 @@
+module ActiveTriples
+  ##
+  # Persistence strategy for projecting `RDFSource` to `RDF::Repositories`.
+  class RepositoryStrategy
+    include PersistenceStrategy
+
+    # @!attribute [r] obj
+    #   the source to persist with this strategy
+    attr_reader :obj
+
+    ##
+    # @param obj [RDFSource, RDF::Enumerable] the `RDFSource` (or other
+    #   `RDF::Enumerable` to persist with the strategy.
+    def initialize(obj)
+      @obj = obj
+    end
+
+    ##
+    # Clear out any old assertions in the repository about this node or statement
+    # thus preparing to receive the updated assertions.
+    def erase_old_resource
+      if obj.node?
+        repository.statements.each do |statement|
+          repository.send(:delete_statement, statement) if
+            statement.subject == obj
+        end
+      else
+        repository.delete [obj.to_term, nil, nil]
+      end
+    end
+
+    ##
+    # Persists the object to the repository
+    #
+    # @return [true] returns true if the save did not error
+    def persist!
+      erase_old_resource
+      repository << obj
+      @persisted = true
+    end
+
+    ##
+    # Repopulates the graph from the repository.
+    #
+    # @return [Boolean]
+    def reload
+      obj << repository.query(subject: obj)
+      @persisted = true unless obj.empty?
+      true
+    end
+
+    ##
+    # @return [RDF::Repository] The RDF::Repository that the object will project
+    #   itself on when persisting.
+    def repository
+      @repository ||= set_repository
+    end
+
+    private
+
+      ##
+      # Finds an appropriate repository from the calling object's configuration.
+      # If no repository is configured, builds an ephemeral in-memory
+      # repository and 'persists' there.
+      #
+      # @todo find a way to move this logic out (PersistenceStrategyBuilder?).
+      #   so the dependency on Repositories is externalized.
+      def set_repository
+        repo_sym = obj.class.repository || obj.singleton_class.repository
+        if repo_sym.nil?
+          RDF::Repository.new
+        else
+          repo = Repositories.repositories[repo_sym]
+          repo || raise(RepositoryNotFoundError, "The class #{obj.class} expects a repository called #{repo_sym}, but none was declared")
+        end
+      end
+  end
+end

data/lib/active_triples/properties.rb

@@ -60,7 +60,8 @@ module ActiveTriples
       #
       # @return [ActiveTriples::NodeConfig]
       def config_for_term_or_uri(term)
-        return properties[term.to_s] unless term.kind_of? RDF::Resource
+        return properties[term.to_s] unless
+          term.is_a?(RDF::Resource) && !term.is_a?(RDFSource)
         properties.each_value { |v| return v if v.predicate == term.to_uri }
       end
 

data/lib/active_triples/rdf_source.rb

@@ -1,4 +1,3 @@
-require 'deprecation'
 require 'active_model'
 require 'active_support/core_ext/hash'
 
@@ -32,6 +31,11 @@ module ActiveTriples
   # @see http://www.w3.org/TR/ldp/#dfn-linked-data-platform-rdf-source an
   #   example of the RDF source concept as defined in the LDP specification
   #
+  # An `RDFSource` is an {RDF::Term}---it can be used as a subject, predicate,
+  # object, or context in an {RDF::Statement}.
+  #
+  # @todo complete RDF::Value/RDF::Term/RDF::Resource interfaces 
+  #
   # @see ActiveModel
   # @see RDF::Resource
   # @see RDF::Queryable
@@ -39,20 +43,15 @@ module ActiveTriples
     extend ActiveSupport::Concern
 
     include NestedAttributes
+    include Persistable
     include Properties
     include Reflection
     include RDF::Value
-    include RDF::Countable
-    include RDF::Durable
-    include RDF::Enumerable
     include RDF::Queryable
-    include RDF::Mutable
+    include ActiveModel::Validations
     include ActiveModel::Conversion
     include ActiveModel::Serialization
     include ActiveModel::Serializers::JSON
-    include ActiveModel::Validations
-
-    attr_accessor :parent
 
     def type_registry
       @@type_registry ||= {}
@@ -61,7 +60,6 @@ module ActiveTriples
 
     included do
       extend Configurable
-      extend Deprecation
       extend ActiveModel::Naming
       extend ActiveModel::Translation
       extend ActiveModel::Callbacks
@@ -73,28 +71,11 @@ module ActiveTriples
           graph.valid?
       end
 
-      delegate :query, :each, :load!, :count, :has_statement?, :to => :@graph
-
       define_model_callbacks :persist
-
-      protected
-
-      def insert_statement(*args)
-        @graph.send(:insert_statement, *args)
-      end
-
-      def delete_statement(*args)
-        @graph.send(:delete_statement, *args)
-      end
     end
 
-    ##
-    # Specifies whether the object is currently writable.
-    #
-    # @return [true, false]
-    def writable?
-      !frozen?
-    end
+    delegate :each, :load!, :count, :has_statement?, :to => :graph
+    delegate :to_base, :term?, :escape, :to => :to_term
 
     ##
     # Initialize an instance of this resource class. Defaults to a
@@ -109,11 +90,17 @@ module ActiveTriples
     # @todo move this logic out to a Builder?
     def initialize(*args, &block)
       resource_uri = args.shift unless args.first.is_a?(Hash)
-      self.parent = args.shift unless args.first.is_a?(Hash)
+      unless args.first.is_a?(Hash) || args.empty?
+        set_persistence_strategy(ParentStrategy)
+        persistence_strategy.parent = args.shift
+      else
+        set_persistence_strategy(RepositoryStrategy)
+      end
       @graph = RDF::Graph.new(*args, &block)
       set_subject!(resource_uri) if resource_uri
 
       reload
+
       # Append type to graph if necessary.
       Array(self.class.type).each do |type|
         unless self.get_values(:type).include?(type)
@@ -122,14 +109,34 @@ module ActiveTriples
       end
     end
 
-    def final_parent
-      @final_parent ||= begin
-        parent = self.parent
-        while parent && parent.parent && parent.parent != parent
-          parent = parent.parent
-        end
-        parent
-      end
+    ##
+    # Compares self to other for {RDF::Term} equality.
+    #
+    # Delegates the check to `other#==` passing it the term version of `self`.
+    #
+    # @param other [Object]
+    #
+    # @see RDF::Term#==
+    # @see RDF::Node#==
+    # @see RDF::URI#==
+    def ==(other)
+      other == to_term
+    end
+
+    ##
+    # Delegate parent to the persistence strategy if possible
+    #
+    # @todo establish a better pattern for this. `#parent` has been a public method
+    #   in the past, but it's probably time to deprecate it.
+    def parent
+      persistence_strategy.respond_to?(:parent) ? persistence_strategy.parent : nil
+    end
+
+    ##
+    # @todo deprecate/remove
+    # @see #parent
+    def parent=(parent)
+      persistence_strategy.respond_to?(:parent=) ? (persistence_strategy.parent = parent) : nil
     end
 
     def attributes
@@ -147,6 +154,8 @@ module ActiveTriples
       hash
     end
 
+    ##
+    # @return [Class] gives `self#class`
     def reflections
       self.class
     end
@@ -186,26 +195,54 @@ module ActiveTriples
     end
 
     ##
-    # @return [RDF::URI, RDF::Node] a URI or Node which the resource's
-    #   properties are about.
+    # Gives the representation of this
+    #
+    # @return [RDF::URI, RDF::Node] the URI that identifies this `RDFSource`;
+    #   or a bnode identifier
+    #
+    # @see RDF::Term#to_term
     def rdf_subject
       @rdf_subject ||= RDF::Node.new
     end
     alias_method :to_term, :rdf_subject
 
     ##
-    # A string identifier for the resource
+    # @return [String] A string identifier for the resource; '' if the
+    #   resource is a node
+    def humanize
+      node? ? '' : rdf_subject.to_s
+    end
+
+    ##
+    # @return [RDF::URI] the uri
+    def to_uri
+      uri? ? rdf_subject : NullURI.new
+    end
+
+    ##
+    # @return [String]
+    #
+    # @see RDF::Node#id
     def id
-      node? ? nil : rdf_subject.to_s
+      node? ? rdf_subject.id : rdf_subject.to_s
     end
 
     ##
-    # @return [Boolean]
+    # @return [Boolean] true if the Term is a node
+    #
     # @see RDF::Term#node?
     def node?
       rdf_subject.node?
     end
 
+    ##
+    # @return [Boolean] true if the Term is a uri
+    #
+    # @see RDF::Term#uri?
+    def uri?
+      rdf_subject.uri?
+    end
+
     ##
     # @return [String, nil] the base URI the resource will use when
     #   setting its subject. `nil` if none is used.
@@ -235,14 +272,6 @@ module ActiveTriples
       node? ? [] : [rdf_subject.to_s]
     end
 
-    ##
-    # Lists fields registered as properties on the object.
-    #
-    # @return [Array<Symbol>] the list of registered properties.
-    def fields
-      properties.keys.map(&:to_sym).reject{|x| x == :type}
-    end
-
     ##
     # Load data from the #rdf_subject URI. Retrieved data will be
     # parsed into the Resource's graph from available RDF::Readers
@@ -255,50 +284,11 @@ module ActiveTriples
     #    # => "Oregon State University"
     #
     # @return [ActiveTriples::Entity] self
-    def fetch(*args)
-      load(rdf_subject, *args)
+    def fetch
+      load(rdf_subject)
       self
     end
 
-    def persist!(opts={})
-      return if @persisting
-      return false if opts[:validate] && !valid?
-      @persisting = true
-      run_callbacks :persist do
-        raise "failed when trying to persist to non-existant repository or parent resource" unless repository
-        erase_old_resource
-        repository << self
-        @persisted = true
-      end
-      @persisting = false
-      true
-    end
-
-    ##
-    # Indicates if the resource is persisted.
-    #
-    # @see #persist
-    # @return [true, false]
-    def persisted?
-      @persisted ||= false
-      return (@persisted and parent.persisted?) if parent
-      @persisted
-    end
-
-    ##
-    # Repopulates the graph from the repository or parent resource.
-    #
-    # @return [true, false]
-    def reload
-      @relation_cache ||= {}
-      return false if (node? && self.class.repository != :parent) || !repository
-      self << repository.query(subject: rdf_subject)
-      unless empty?
-        @persisted = true
-      end
-      true
-    end
-
     ##
     # Adds or updates a property with supplied values.
     #
@@ -350,7 +340,6 @@ module ActiveTriples
       get_relation([uri_or_term_property])
     end
 
-
     def get_relation(args)
       @relation_cache ||= {}
       rel = Relation.new(self, args)
@@ -389,22 +378,6 @@ module ActiveTriples
       end
     end
 
-    def destroy
-      clear
-      persist! if repository
-      parent.destroy_child(self) if parent
-      @destroyed = true
-    end
-    alias_method :destroy!, :destroy
-
-    ##
-    # Indicates if the Resource has been destroyed.
-    #
-    # @return [true, false]
-    def destroyed?
-      @destroyed ||= false
-    end
-
     def destroy_child(child)
       statements.each do |statement|
         delete_statement(statement) if statement.subject == child.rdf_subject || statement.object == child.rdf_subject
@@ -414,7 +387,7 @@ module ActiveTriples
     ##
     # Indicates if the record is 'new' (has not yet been persisted).
     #
-    # @return [true, false]
+    # @return [Boolean]
     def new_record?
       not persisted?
     end
@@ -427,26 +400,20 @@ module ActiveTriples
       @marked_for_destruction
     end
 
-    protected
-
-      #Clear out any old assertions in the repository about this node or statement
-      # thus preparing to receive the updated assertions.
-      def erase_old_resource
-        if node?
-          repository.statements.each do |statement|
-            repository.send(:delete_statement, statement) if statement.subject == rdf_subject
-          end
-        else
-          repository.delete [rdf_subject, nil, nil]
-        end
-      end
-
     private
 
       def graph
         @graph
       end
 
+      ##
+      # Lists fields registered as properties on the object.
+      #
+      # @return [Array<Symbol>] the list of registered properties.
+      def fields
+        properties.keys.map(&:to_sym).reject{ |x| x == :type }
+      end
+
       ##
       # Returns the properties registered and their configurations.
       #
@@ -474,21 +441,6 @@ module ActiveTriples
         predicates.select { |p| !preds.include? p }
       end
 
-      ##
-      # Given a predicate which has been registered to a property,
-      # returns the name of the matching property.
-      #
-      # @param predicate [RDF::URI]
-      #
-      # @return [String, nil] the name of the property mapped to the
-      #   predicate provided
-      def property_for_predicate(predicate)
-        properties.each do |property, values|
-          return property if values[:predicate] == predicate
-        end
-        return nil
-      end
-
       def default_labels
         [RDF::SKOS.prefLabel,
          RDF::DC.title,
@@ -497,23 +449,6 @@ module ActiveTriples
          RDF::SKOS.hiddenLabel]
       end
 
-      ##
-      # Return the repository (or parent) that this resource should
-      # write to when persisting.
-      #
-      # @return [RDF::Repository, ActiveTriples::Entity] the target
-      #   repository
-      def repository
-        @repository ||=
-          if self.class.repository == :parent
-            final_parent
-          else
-            repo = Repositories.repositories[self.class.repository]
-            raise RepositoryNotFoundError, "The class #{self.class} expects a repository called #{self.class.repository}, but none was declared" unless repo
-            repo
-          end
-      end
-
       ##
       # Takes a URI or String and aggressively tries to convert it into
       # an RDF term. If a String is given, first tries to interpret it
@@ -532,7 +467,7 @@ module ActiveTriples
       # @return [RDF::Resource] A term
       # @raise [RuntimeError] no valid RDF term could be built
       def get_uri(uri_or_str)
-        return uri_or_str.to_uri if uri_or_str.respond_to? :to_uri
+        return uri_or_str.to_term if uri_or_str.respond_to? :to_term
         return uri_or_str if uri_or_str.is_a? RDF::Node
         uri_or_node = RDF::Resource.new(uri_or_str)
         return uri_or_node if uri_or_node.valid?
@@ -550,11 +485,11 @@ module ActiveTriples
       # which can become a Resource.
       #
       # @param uri [#to_uri, String]
-      # @param vals values to pass as arguments to ::new
+      # @param args values to pass as arguments to ::new
       #
       # @return [ActiveTriples::Entity] a Resource with the given uri
-      def from_uri(uri, vals = nil)
-        new(uri, vals)
+      def from_uri(uri, *args)
+        new(uri, *args)
       end
 
       ##