active-triples 0.8.1 → 0.8.2

data/lib/active_triples/persistence_strategies/persistence_strategy.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
 module ActiveTriples
   ##
   # @abstract defines the basic interface for persistence of {RDFSource}'s.
   #
-  # A `PersistenceStrategy` has an underlying object (`obj`) which should 
+  # A `PersistenceStrategy` has an underlying resource 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.
@@ -16,14 +17,20 @@ module ActiveTriples
   #
   module PersistenceStrategy
     ##
-    # Deletes the resource from the repository.
+    # Deletes the resource from the datastore / 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?
+      
+      # Provide a warning for strategies relying on #destroy to clear the resource
+      if defined? obj
+        warn "DEPRECATION WARNING: #destroy implementations must now explicitly call 'source.clear'"
+        obj.clear
+      end
+      
       persist!
       @destroyed = true
     end
@@ -38,7 +45,7 @@ module ActiveTriples
     end
 
     ##
-    # Indicates if the resource is persisted to the repository
+    # Indicates if the resource is persisted to the datastore / repository
     #
     # @return [Boolean] true if persisted; else false.
     def persisted?
@@ -46,7 +53,7 @@ module ActiveTriples
     end
 
     ##
-    # @abstract save the object according to the strategy and set the 
+    # @abstract save the resource according to the strategy and set the 
     #   @persisted flag to `true`
     #
     # @see #persisted?
@@ -57,8 +64,9 @@ module ActiveTriples
     end
 
     ##
-    # @abstract Clear out any old assertions in the repository about this node 
-    # or statement thus preparing to receive the updated assertions.
+    # @abstract Clear out any old assertions in the datastore / repository 
+    # about this node  or statement thus preparing to receive the updated 
+    # assertions.
     #
     # @return [Boolean]
     def erase_old_resource

data/lib/active_triples/persistence_strategies/repository_strategy.rb

@@ -1,41 +1,49 @@
+# frozen_string_literal: true
 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
+    # @!attribute [r] source
+    #   the resource to persist with this strategy
+    attr_reader :source
 
     ##
-    # @param obj [RDFSource, RDF::Enumerable] the `RDFSource` (or other
+    # @param source [RDFSource, RDF::Enumerable] the `RDFSource` (or other
     #   `RDF::Enumerable` to persist with the strategy.
-    def initialize(obj)
-      @obj = obj
+    def initialize(source)
+      @source = source
+    end
+
+    ##
+    # Deletes the resource from the repository.
+    #
+    def destroy
+      super { source.clear }
     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?
+      if source.node?
         repository.statements.each do |statement|
           repository.send(:delete_statement, statement) if
-            statement.subject == obj
+            statement.subject == source
         end
       else
-        repository.delete [obj.to_term, nil, nil]
+        repository.delete [source.to_term, nil, nil]
       end
     end
 
     ##
-    # Persists the object to the repository
+    # Persists the resource to the repository
     #
     # @return [true] returns true if the save did not error
     def persist!
       erase_old_resource
-      repository << obj
+      repository << source
       @persisted = true
     end
 
@@ -44,13 +52,13 @@ module ActiveTriples
     #
     # @return [Boolean]
     def reload
-      obj << repository.query(subject: obj)
-      @persisted = true unless obj.empty?
+      source << repository.query(subject: source)
+      @persisted = true unless source.empty?
       true
     end
 
     ##
-    # @return [RDF::Repository] The RDF::Repository that the object will project
+    # @return [RDF::Repository] The RDF::Repository that the resource will project
     #   itself on when persisting.
     def repository
       @repository ||= set_repository
@@ -59,20 +67,16 @@ module ActiveTriples
     private
 
       ##
-      # Finds an appropriate repository from the calling object's configuration.
+      # Finds an appropriate repository from the calling resource'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
+        return RDF::Repository.new if source.class.repository.nil?
+        repo = Repositories.repositories[source.class.repository]
+        repo || raise(RepositoryNotFoundError, "The class #{source.class} expects a repository called #{source.class.repository}, but none was declared")
       end
   end
 end

data/lib/active_triples/properties.rb

@@ -1,32 +1,98 @@
+# frozen_string_literal: true
 require 'active_support/core_ext/hash'
 
 module ActiveTriples
   ##
-  # Implements property configuration common to Rdf::Resource,
-  # RDFDatastream, and others.  It does its work at the class level,
-  # and is meant to be extended.
+  # Implements property configuration in the style of RDFSource. It does its 
+  # work at the class level, and is meant to be extended.
+  # 
+  # Collaborates closely with ActiveTriples::Reflection
   #
   # Define properties at the class level with:
   #
   #    property :title, predicate: RDF::DC.title, class_name: ResourceClass
   #
+  # @see {ActiveTriples::Reflection}
+  # @see {ActiveTriples::PropertyBuilder}
   module Properties
     extend ActiveSupport::Concern
 
     included do
+      include Reflection
       initialize_generated_modules
     end
 
+    private
+
+      ##
+      # Returns the properties registered and their configurations.
+      #
+      # @return [ActiveSupport::HashWithIndifferentAccess{String => ActiveTriples::NodeConfig}]
+      def properties
+        _active_triples_config
+      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
+
+      ##
+      # List of RDF predicates registered as properties on the object.
+      #
+      # @return [Array<RDF::URI>]
+      def registered_predicates
+        properties.values.map { |config| config.predicate }
+      end
+
+      ##
+      # List of RDF predicates used in the Resource's triples, but not
+      # mapped to any property or accessor methods.
+      #
+      # @return [Array<RDF::URI>]
+      def unregistered_predicates
+        preds = registered_predicates
+        preds << RDF.type
+        predicates.select { |p| !preds.include? p }
+      end
+
+    public
+    
+    ##
+    # Class methods for classes with `Properties`
     module ClassMethods
       def inherited(child_class) #:nodoc:
         child_class.initialize_generated_modules
         super
       end
 
-      def initialize_generated_modules # :nodoc:
+      ##
+      # If the property methods are not yet present, generates them.
+      #
+      # @return [Module] a module self::GeneratedPropertyMethods which is 
+      #   included in self and defines the property methods
+      #
+      # @note this is an alias to #generated_property_methods. Use it when you 
+      #   intend to initialize, rather than retrieve, the methods for code
+      #   readability
+      # @see #generated_property_methods
+      def initialize_generated_modules
         generated_property_methods
       end
 
+      ##
+      # Gives existing generated property methods. If the property methods are 
+      # not yet present, generates them as a new Module and includes it.
+      #
+      # @return [Module] a module self::GeneratedPropertyMethods which is 
+      #   included in self and defines the property methods
+      #
+      # @note use the alias #initialize_generated_modules for clarity of intent
+      #   where appropriate
+      # @see #initialize_generated_modules
       def generated_property_methods
         @generated_property_methods ||= begin
           mod = const_set(:GeneratedPropertyMethods, Module.new)
@@ -37,15 +103,27 @@ module ActiveTriples
 
       ##
       # Registers properties for Resource-like classes
+      #
       # @param [Symbol]  name of the property (and its accessor methods)
       # @param [Hash]  opts for this property, must include a :predicate
       # @yield [index] index sets solr behaviors for the property
+      #
+      # @return [Hash{String=>ActiveTriples::NodeConfig}] the full current 
+      #   property configuration for the class
       def property(name, opts={}, &block)
         raise ArgumentError, "#{name} is a keyword and not an acceptable property name." if protected_property_name? name
         reflection = PropertyBuilder.build(self, name, opts, &block)
         Reflection.add_reflection self, name, reflection
       end
 
+      ##
+      # Checks potential property names for conflicts with existing class 
+      # instance methods. We avoid setting properties with these names to 
+      # prevent catastrophic method overwriting.
+      #
+      # @param [Symblol] name  A potential property name.
+      # @return [Boolean] true if the given name matches an existing instance 
+      #   method which is not an ActiveTriples property.
       def protected_property_name?(name)
         reject = self.instance_methods.map! { |s| s.to_s.gsub(/=$/, '').to_sym }
         reject -= properties.keys.map { |k| k.to_sym }
@@ -56,9 +134,9 @@ module ActiveTriples
       # Given a property name or a predicate, return the configuration
       # for the matching property.
       #
-      # @param term [#to_sym, RDF::Resource] a property name to predicate
+      # @param [#to_sym, RDF::Resource] term  property name or predicate
       #
-      # @return [ActiveTriples::NodeConfig]
+      # @return [ActiveTriples::NodeConfig] the configuration for the property
       def config_for_term_or_uri(term)
         return properties[term.to_s] unless
           term.is_a?(RDF::Resource) && !term.is_a?(RDFSource)

data/lib/active_triples/property.rb

@@ -1,13 +1,44 @@
+# frozen_string_literal: true
 module ActiveTriples
   ##
   # A value object to encapsulate what a Property is. Instantiate with a hash of
   # options.
-  class Property < OpenStruct
+  #
+  # @todo Should we enforce the interface on the various attributes that are set?
+  class Property
+    def initialize(options = {})
+      self.name = options.fetch(:name)
+      self.attributes = options.except(:name)
+    end
+
+    # @return Symbol
+    attr_reader :name
+
+    # @return Boolean
+    def cast
+      attributes.fetch(:cast, false)
+    end
+
+    # @return Class
+    def class_name
+      attributes[:class_name]
+    end
+
+    # @return RDF::Vocabulary::Term
+    def predicate
+      attributes[:predicate]
+    end
+
+    private
+
+    attr_writer :name
+    attr_accessor :attributes
+
+    alias_method :to_h, :attributes
+
     # Returns the property's configuration values. Will not return #name, which is
     # meant to only be accessible via the accessor.
     # @return [Hash] Configuration values for this property.
-    def to_h
-      super.except(:name)
-    end
+    public :to_h
   end
 end

data/lib/active_triples/property_builder.rb

@@ -1,22 +1,51 @@
+# frozen_string_literal: true
 module ActiveTriples
+  ##
+  # A builder for property `NodeConfig`s
+  #
+  # @example 
+  #   PropertyBuilder.build(:creator, predicate: RDF::Vocab::DC.creator)
+  # 
+  # @see NodeConfig
   class PropertyBuilder
 
+    # @!attribute [r] name
+    #   @return
+    # @!attribute [r] options
+    #   @return
     attr_reader :name, :options
 
+    ##
+    # @param name []
+    # @param options []
     def initialize(name, options, &block)
       @name = name
       @options = options
     end
 
+    ##
+    # @param  name [Symbol]
+    # @param  options [Hash<Symbol>]
+    # @option options [RDF::URI] :predicate  
+    # @option options [String, Class] :class_name
+    # @option options [Boolean] :cast
+    #
+    # @yield yields to block configuring index behaviors
+    # @yieldparam index_object [NodeConfig::IndexObject]
+    #
+    # @return [PropertyBuilder]
+    # @raise [ArgumentError] if name is not a symbol and/or :predicate can't be
+    #   coerced into a URI
+    #
+    # @see #build
     def self.create_builder(name, options, &block)
       raise ArgumentError, "property names must be a Symbol" unless
         name.kind_of?(Symbol)
 
-      options[:predicate] = RDF::Resource.new(options[:predicate])
-      raise ArgumentError, "must provide an RDF::Resource to :predicate" unless
+      options[:predicate] = RDF::URI.new(options[:predicate])
+      raise ArgumentError, "must provide an RDF::URI to :predicate" unless
         options[:predicate].valid?
 
-
       new(name, options, &block)
     end
 
@@ -58,7 +87,12 @@ module ActiveTriples
         end
       CODE
     end
-
+    
+    ##
+    # @yield yields to block configuring index behaviors
+    # @yieldparam index_object [NodeConfig::IndexObject]
+    #
+    # @return [NodeConfig] a new property node config
     def build(&block)
       NodeConfig.new(name,
                      options[:predicate],

data/lib/active_triples/rdf_source.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
 require 'active_model'
 require 'active_support/core_ext/hash'
+require 'active_support/core_ext/array/wrap'
 
 module ActiveTriples
   ##
@@ -34,7 +36,7 @@ module ActiveTriples
   # 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 
+  # @todo complete RDF::Value/RDF::Term/RDF::Resource interfaces
   #
   # @see ActiveModel
   # @see RDF::Resource
@@ -45,7 +47,6 @@ module ActiveTriples
     include NestedAttributes
     include Persistable
     include Properties
-    include Reflection
     include RDF::Value
     include RDF::Queryable
     include ActiveModel::Validations
@@ -74,7 +75,7 @@ module ActiveTriples
       define_model_callbacks :persist
     end
 
-    delegate :each, :load!, :count, :has_statement?, :to => :graph
+    delegate :query, :each, :load!, :count, :has_statement?, :to => :graph
     delegate :to_base, :term?, :escape, :to => :to_term
 
     ##
@@ -102,7 +103,7 @@ module ActiveTriples
       reload
 
       # Append type to graph if necessary.
-      Array(self.class.type).each do |type|
+      Array.wrap(self.class.type).each do |type|
         unless self.get_values(:type).include?(type)
           self.get_values(:type) << type
         end
@@ -124,49 +125,57 @@ module ActiveTriples
     end
 
     ##
-    # Delegate parent to the persistence strategy if possible
+    # Gives a hash containing both the registered and unregistered attributes of
+    # the resource. Unregistered attributes are given with full URIs.
+    # 
+    # @example 
+    #   class WithProperties
+    #     include ActiveTriples::RDFSource
+    #     property :title,   predicate:  RDF::Vocab::DC.title
+    #     property :creator, predicate:  RDF::Vocab::DC.creator, 
+    #                        class_name: 'Agent'
+    #   end
     #
-    # @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
+    #   class Agent; include ActiveTriples::RDFSource; end
+    #
+    #   resource = WithProperties.new
+    #
+    #   resource.attributes
+    #   # => {"id"=>"g47123700054720", "title"=>[], "creator"=>[]}
+    #
+    #   resource.creator.build
+    #   resource.title << ['Comet in Moominland', 'Christmas in Moominvalley']
 
+    #   resource.attributes
+    #   # => {"id"=>"g47123700054720",
+    #   #     "title"=>["Comet in Moominland", "Christmas in Moominvalley"],
+    #   #     "creator"=>[#<Agent:0x2adbd76f1a5c(#<Agent:0x0055b7aede34b8>)>]}
+    #
+    #   resource << [resource, RDF::Vocab::DC.relation, 'Helsinki']
+    #   # => {"id"=>"g47123700054720",
+    #   #     "title"=>["Comet in Moominland", "Christmas in Moominvalley"],
+    #   #     "creator"=>[#<Agent:0x2adbd76f1a5c(#<Agent:0x0055b7aede34b8>)>],
+    #   #     "http://purl.org/dc/terms/relation"=>["Helsinki"]}]}
+    #
+    # @return [Hash<String, Array<Object>>]
+    #
+    # @todo: should this, `#attributes=`, and `#serializable_hash` be moved out
+    #   into a dedicated `Serializer` object?
     def attributes
       attrs = {}
-      attrs['id'] = id if id
+      attrs['id'] = id
       fields.map { |f| attrs[f.to_s] = get_values(f) }
       unregistered_predicates.map { |uri| attrs[uri.to_s] = get_values(uri) }
       attrs
     end
 
-    def serializable_hash(options = nil)
-      attrs = (fields.map { |f| f.to_s }) << 'id'
-      hash = super(:only => attrs)
-      unregistered_predicates.map { |uri| hash[uri.to_s] = get_values(uri) }
-      hash
-    end
-
-    ##
-    # @return [Class] gives `self#class`
-    def reflections
-      self.class
-    end
-
     def attributes=(values)
       raise ArgumentError, "values must be a Hash, you provided #{values.class}" unless values.kind_of? Hash
       values = values.with_indifferent_access
       id = values.delete(:id)
-      set_subject!(id) if id && node?
+      set_subject!(id) if node?
       values.each do |key, value|
-        if reflections.reflect_on_property(key)
+        if reflections.has_property?(key)
           set_value(rdf_subject, key, value)
         elsif nested_attributes_options.keys.map { |k| "#{k}_attributes" }.include?(key)
           send("#{key}=".to_sym, value)
@@ -176,6 +185,13 @@ module ActiveTriples
       end
     end
 
+    def serializable_hash(options = nil)
+      attrs = (fields.map { |f| f.to_s }) << 'id'
+      hash = super(:only => attrs)
+      unregistered_predicates.map { |uri| hash[uri.to_s] = get_values(uri) }
+      hash
+    end
+
     ##
     # Returns a serialized string representation of self.
     # Extends the base implementation builds a JSON-LD context if the
@@ -195,7 +211,23 @@ module ActiveTriples
     end
 
     ##
-    # Gives the representation of this
+    # 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
+
+    ##
+    # Gives the representation of this RDFSource as an RDF::Term
     #
     # @return [RDF::URI, RDF::Node] the URI that identifies this `RDFSource`;
     #   or a bnode identifier
@@ -206,6 +238,21 @@ module ActiveTriples
     end
     alias_method :to_term, :rdf_subject
 
+    ##
+    # Returns `nil` as the `graph_name`. This behavior mimics an `RDF::Graph`
+    # with no graph name, or one without named graph support.
+    #
+    # @note: it's possible to think of an `RDFSource` as "supporting named 
+    #   graphs" in the sense that the `#rdf_subject` is an implied graph name.
+    #   For RDF.rb's purposes, however, it has a nil graph name: when 
+    #   enumerating statements, we treat them as triples.
+    #
+    # @return [nil]
+    # @sse RDF::Graph.graph_name
+    def graph_name
+      nil
+    end
+    
     ##
     # @return [String] A string identifier for the resource; '' if the
     #   resource is a node
@@ -216,7 +263,7 @@ module ActiveTriples
     ##
     # @return [RDF::URI] the uri
     def to_uri
-      uri? ? rdf_subject : NullURI.new
+      rdf_subject if uri?
     end
 
     ##
@@ -251,7 +298,7 @@ module ActiveTriples
     end
 
     def type
-      self.get_values(:type).to_a
+      self.get_values(:type)
     end
 
     def type=(type)
@@ -262,8 +309,10 @@ module ActiveTriples
     ##
     # Looks for labels in various default fields, prioritizing
     # configured label fields.
+    #
+    # @see #default_labels
     def rdf_label
-      labels = Array(self.class.rdf_label)
+      labels = Array.wrap(self.class.rdf_label)
       labels += default_labels
       labels.each do |label|
         values = get_values(label)
@@ -272,34 +321,108 @@ module ActiveTriples
       node? ? [] : [rdf_subject.to_s]
     end
 
+    ##
+    # @return [Array<RDF::URI>] a group of properties to use for default labels.
+    def default_labels
+      [RDF::SKOS.prefLabel,
+       RDF::DC.title,
+       RDF::RDFS.label,
+       RDF::SKOS.altLabel,
+       RDF::SKOS.hiddenLabel]
+    end
+
     ##
     # Load data from the #rdf_subject URI. Retrieved data will be
     # parsed into the Resource's graph from available RDF::Readers
     # and available from property accessors if if predicates are
     # registered.
     #
+    # @example
     #    osu = new('http://dbpedia.org/resource/Oregon_State_University')
     #    osu.fetch
     #    osu.rdf_label.first
     #    # => "Oregon State University"
     #
-    # @return [ActiveTriples::Entity] self
-    def fetch
-      load(rdf_subject)
+    # @example with default action block
+    #    my_source = new('http://example.org/dead_url')
+    #    my_source.fetch { |obj| obj.status = 'dead link' }
+    #
+    # @yield gives self to block if this is a node, or an error is raised during
+    #   load
+    # @yieldparam [ActiveTriples::RDFSource] resource  self
+    #
+    # @return [ActiveTriples::RDFSource] self
+    def fetch(*args, &block)
+      begin
+        load(rdf_subject, *args)
+      rescue => e
+        if block_given?
+          yield(self)
+        else
+          raise "#{self} is a blank node; Cannot fetch a resource without a URI" if
+            node?
+          raise e
+        end
+      end
       self
     end
 
     ##
-    # Adds or updates a property with supplied values.
+    # Adds or updates a property by creating triples for each of the supplied
+    # values.
     #
-    # Handles two argument patterns. The recommended pattern is:
-    #    set_value(property, values)
+    # The `property` argument may be either a symbol representing a registered
+    # property name, or an RDF::Term to use as the predicate.
     #
-    # For backwards compatibility, there is support for explicitly
-    # passing the rdf_subject to be used in the statement:
-    #    set_value(uri, property, values)
+    # @example setting with a property name
+    #   class Thing
+    #     include ActiveTriples::RDFSource
+    #     property :creator, predicate: RDF::DC.creator
+    #   end
     #
-    # @note This method will delete existing statements with the correct subject and predicate from the graph
+    #   t = Thing.new
+    #   t.set_value(:creator, 'Tove Jansson')  # => ['Tove Jansson']
+    #
+    #
+    # @example setting with a predicate
+    #   t = Thing.new
+    #   t.set_value(RDF::DC.creator, 'Tove Jansson')  # => ['Tove Jansson']
+    #
+    #
+    # The recommended pattern, which sets properties directly on this
+    # RDFSource, is: `set_value(property, values)`
+    #
+    # @overload set_value(property, values)
+    #   Updates the values for the property, using this RDFSource as the subject
+    #
+    #   @param [RDF::Term, #to_sym] property  a symbol with the property name
+    #     or an RDF::Term to use as a predicate.
+    #   @param [Array<RDF::Resource>, RDF::Resource] values  an array of values
+    #     or a single value. If not an {RDF::Resource}, the values will be
+    #     coerced to an {RDF::Literal} or {RDF::Node} by {RDF::Statement}
+    #
+    # @overload set_value(subject, property, values)
+    #   Updates the values for the property, using the given term as the subject
+    # 
+    #   @param [RDF::Term] subject  the term representing the 
+    #   @param [RDF::Term, #to_sym] property  a symbol with the property name
+    #     or an RDF::Term to use as a predicate.
+    #   @param [Array<RDF::Resource>, RDF::Resource] values  an array of values
+    #     or a single value. If not an {RDF::Resource}, the values will be 
+    #     coerced to an {RDF::Literal} or {RDF::Node} by {RDF::Statement}
+    #
+    # @return [ActiveTriples::Relation] an array {Relation} containing the
+    #   values of the property
+    #
+    # @raise [ActiveTriples::Relation::ValueError] when the given value can't be
+    #   coerced into an acceptable `RDF::Term`.
+    #
+    # @note This method will delete existing statements with the given
+    #   subject and predicate from the graph
+    #
+    # @see http://www.rubydoc.info/github/ruby-rdf/rdf/RDF/Statement For 
+    #   documentation on {RDF::Statement} and the handling of 
+    #   non-{RDF::Resource} values.
     def set_value(*args)
       # Add support for legacy 3-parameter syntax
       if args.length > 3 || args.length < 2
@@ -309,38 +432,61 @@ module ActiveTriples
       get_relation(args).set(values)
     end
 
-    ##
-    # Adds or updates a property with supplied values.
-    #
-    # @note This method will delete existing statements with the correct subject and predicate from the graph
-    def []=(uri_or_term_property, value)
-      self[uri_or_term_property].set(value)
-    end
-
     ##
     # Returns an array of values belonging to the property
     # requested. Elements in the array may RdfResource objects or a
     # valid datatype.
     #
-    # Handles two argument patterns. The recommended pattern is:
+    # Handles two argument patterns. The recommended pattern, which accesses
+    # properties directly on this RDFSource, is:
     #    get_values(property)
     #
-    # For backwards compatibility, there is support for explicitly
-    # passing the rdf_subject to be used in th statement:
-    #    get_values(uri, property)
+    # @overload get_values(property) 
+    #   Gets values on the RDFSource for the given property
+    #   @param [String, #to_term] property  the property for the values
+    #
+    # @overload get_values(uri, property)
+    #   For backwards compatibility, explicitly passing the term used as the
+    #   subject {ActiveTriples::Relation#rdf_subject} of the returned relation.
+    #   @param [RDF::Term] uri  the term to use as the subject
+    #   @param [String, #to_term] property  the property for the values
+    #
+    # @return [ActiveTriples::Relation] an array {Relation} containing the 
+    #   values of the property
+    #
+    # @todo should this raise an error when the property argument is not an 
+    #   {RDF::Term} or a registered property key?
     def get_values(*args)
       get_relation(args)
     end
 
     ##
-    # Returns an array of values belonging to the property
-    # requested. Elements in the array may RdfResource objects or a
-    # valid datatype.
-    def [](uri_or_term_property)
-      get_relation([uri_or_term_property])
+    # Returns an array of values belonging to the property requested. Elements
+    # in the array may RdfResource objects or a valid datatype.
+    # 
+    # @param [RDF::Term, :to_s] term_or_property
+    def [](term_or_property)
+      get_relation([term_or_property])
+    end
+
+    ##
+    # Adds or updates a property with supplied values.
+    #
+    # @param [RDF::Term, :to_s] term_or_property
+    # @param [Array<RDF::Resource>, RDF::Resource] values  an array of values
+    #   or a single value to set the property to.   
+    #
+    # @note This method will delete existing statements with the correct 
+    #   subject and predicate from the graph
+    def []=(term_or_property, value)
+      self[term_or_property].set(value)
     end
 
+    ##
+    # @see #get_values
+    # @todo deprecate and remove? this is an alias to `#get_values`
     def get_relation(args)
+      reload if (persistence_strategy.respond_to? :loaded?) && !persistence_strategy.loaded?
       @relation_cache ||= {}
       rel = Relation.new(self, args)
       @relation_cache["#{rel.send(:rdf_subject)}/#{rel.property}/#{rel.rel_args}"] ||= rel
@@ -378,12 +524,6 @@ module ActiveTriples
       end
     end
 
-    def destroy_child(child)
-      statements.each do |statement|
-        delete_statement(statement) if statement.subject == child.rdf_subject || statement.object == child.rdf_subject
-      end
-    end
-
     ##
     # Indicates if the record is 'new' (has not yet been persisted).
     #
@@ -402,11 +542,21 @@ module ActiveTriples
 
     private
 
+      ##
+      # This gives the {RDF::Graph} which represents the current state of this
+      # resource.
+      #  
+      # @return [RDF::Graph] the underlying graph representation of the
+      #   `RDFSource`.
+      #
+      # @see http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#change-over-time
+      #   RDF Concepts and Abstract Syntax comment on "RDF source"
       def graph
         @graph
       end
 
       ##
+
       # Lists fields registered as properties on the object.
       #
       # @return [Array<Symbol>] the list of registered properties.
@@ -442,11 +592,11 @@ module ActiveTriples
       end
 
       def default_labels
-        [RDF::SKOS.prefLabel,
-         RDF::DC.title,
+        [RDF::Vocab::SKOS.prefLabel,
+         RDF::Vocab::DC.title,
          RDF::RDFS.label,
-         RDF::SKOS.altLabel,
-         RDF::SKOS.hiddenLabel]
+         RDF::Vocab::SKOS.altLabel,
+         RDF::Vocab::SKOS.hiddenLabel]
       end
 
       ##
@@ -494,7 +644,7 @@ module ActiveTriples
 
       ##
       # Apply a predicate mapping using a given strategy.
-      # 
+      #
       # @param [ActiveTriples::Schema, #properties] schema A schema to apply.
       # @param [#apply!] strategy A strategy for applying. Defaults
       #   to ActiveTriples::ExtensionStrategy