valkyrie 1.2.0.rc1 → 1.2.0.rc2

data/lib/valkyrie/persistence/fedora/persister/resource_factory.rb

@@ -7,14 +7,20 @@ module Valkyrie::Persistence::Fedora
       require 'valkyrie/persistence/fedora/persister/model_converter'
       require 'valkyrie/persistence/fedora/persister/orm_converter'
       attr_reader :adapter
+
+      # @param [Valkyrie::Persistence::Fedora::MetadataAdapter] adapter
       def initialize(adapter:)
         @adapter = adapter
       end
 
+      # Construct a LDP::Container::Basic object for a Valkyrie Resource
+      # @return [Valkyrie::Resource] resource
       def from_resource(resource:)
         ModelConverter.new(resource: resource, adapter: adapter).convert
       end
 
+      # Construct a Valkyrie::Resource object for a Valkyrie Resource
+      # @return [LDP::Container::Basic] object
       def to_resource(object:)
         OrmConverter.new(object: object, adapter: adapter).convert
       end

data/lib/valkyrie/persistence/fedora/query_service.rb

@@ -47,6 +47,9 @@ module Valkyrie::Persistence::Fedora
       end
     end
 
+    # Specify the URIs used in triples directly related to the requested resource
+    # @see https://wiki.duraspace.org/display/FEDORA4x/RESTful+HTTP+API#RESTfulHTTPAPI-GETRetrievethecontentoftheresource
+    # @return [Array<RDF::URI>]
     def include_uris
       [
         ::RDF::Vocab::Fcrepo4.InboundReferences
@@ -64,8 +67,6 @@ module Valkyrie::Persistence::Fedora
     end
 
     # (see Valkyrie::Persistence::Memory::QueryService#find_all)
-    #
-    # @note This requires iterating over every resource in Fedora.
     def find_all
       resource = Ldp::Resource.for(connection, adapter.base_path, connection.get(adapter.base_path))
       ids = resource.graph.query([nil, RDF::Vocab::LDP.contains, nil]).map(&:object).map { |x| adapter.uri_to_id(x) }
@@ -77,8 +78,6 @@ module Valkyrie::Persistence::Fedora
     end
 
     # (see Valkyrie::Persistence::Memory::QueryService#find_all_of_model)
-    #
-    # @note This requires iterating over every resource in Fedora.
     def find_all_of_model(model:)
       find_all.select do |m|
         m.is_a?(model)
@@ -92,6 +91,11 @@ module Valkyrie::Persistence::Fedora
       end
     end
 
+    # Retrieves the RDF graph for the LDP container for a resource
+    # This includes inbound links
+    # @see https://wiki.duraspace.org/display/FEDORA4x/RESTful+HTTP+API#RESTfulHTTPAPI-GETRetrievethecontentoftheresource
+    # @param id [Valkyrie::ID]
+    # @return [Faraday::Response]
     def content_with_inbound(id:)
       uri = adapter.id_to_uri(id)
       connection.get(uri) do |req|
@@ -102,6 +106,9 @@ module Valkyrie::Persistence::Fedora
     end
 
     # (see Valkyrie::Persistence::Memory::QueryService#find_inverse_references_by)
+    # Find all resources referencing a given resource (e. g. parents)
+    # *This is done by iterating through the ID of each resource referencing the resource in the query, and requesting each resource over the HTTP*
+    # *Also, an initial request is made to find the URIs of the resources referencing the resource in the query*
     def find_inverse_references_by(resource:, property:)
       ensure_persisted(resource)
       content = content_with_inbound(id: resource.id)
@@ -112,17 +119,25 @@ module Valkyrie::Persistence::Fedora
       end
     end
 
+    # (see Valkyrie::Persistence::Memory::QueryService#custom_queries)
     def custom_queries
       @custom_queries ||= ::Valkyrie::Persistence::CustomQueryContainer.new(query_service: self)
     end
 
     private
 
+      # Ensures that an object is (or can be cast into a) Valkyrie::ID
+      # @return [Valkyrie::ID]
+      # @raise [ArgumentError]
       def validate_id(id)
         id = Valkyrie::ID.new(id.to_s) if id.is_a?(String)
         raise ArgumentError, 'id must be a Valkyrie::ID' unless id.is_a? Valkyrie::ID
       end
 
+      # Resolve a URI for an LDP resource in Fedora and construct a Valkyrie::Resource
+      # @param uri [RDF::URI]
+      # @return [Valkyrie::Resource]
+      # @raise [Valkyrie::Persistence::ObjectNotFoundError]
       def resource_from_uri(uri)
         resource = Ldp::Resource.for(connection, uri, connection.get(uri))
         resource_factory.to_resource(object: resource)
@@ -130,6 +145,9 @@ module Valkyrie::Persistence::Fedora
         raise ::Valkyrie::Persistence::ObjectNotFoundError
       end
 
+      # Ensures that a Valkyrie::Resource has been persisted
+      # @param resource [Valkyrie::Resource]
+      # @raise [ArgumentError]
       def ensure_persisted(resource)
         raise ArgumentError, 'resource is not saved' unless resource.persisted?
       end

data/lib/valkyrie/persistence/memory/metadata_adapter.rb

@@ -20,10 +20,12 @@ module Valkyrie::Persistence::Memory
       @query_service ||= Valkyrie::Persistence::Memory::QueryService.new(adapter: self)
     end
 
+    # @return [Hash] The in-memory data cache.
     def cache
       @cache ||= {}
     end
 
+    # @return [Valkyrie::ID] Identifier for this metadata adapter.
     def id
       @id ||= Valkyrie::ID.new(Digest::MD5.hexdigest(self.class.to_s))
     end

data/lib/valkyrie/persistence/memory/persister.rb

@@ -14,11 +14,13 @@ module Valkyrie::Persistence::Memory
       @adapter = adapter
     end
 
+    # Save a single resource.
     # @param resource [Valkyrie::Resource] The resource to save.
     # @return [Valkyrie::Resource] The resource with an `#id` value generated by the
     #   persistence backend.
+    # @raise [Valkyrie::Persistence::StaleObjectError]
     def save(resource:)
-      raise Valkyrie::Persistence::StaleObjectError, resource.id unless valid_lock?(resource)
+      raise Valkyrie::Persistence::StaleObjectError, "The object #{resource.id} has been updated by another process." unless valid_lock?(resource)
 
       # duplicate the resource so we are not creating side effects on the caller's resource
       internal_resource = resource.dup
@@ -32,25 +34,28 @@ module Valkyrie::Persistence::Memory
       cache[internal_resource.id] = internal_resource
     end
 
+    # Save a batch of resources.
     # @param resources [Array<Valkyrie::Resource>] List of resources to save.
     # @return [Array<Valkyrie::Resource>] List of resources with an `#id` value
     #   generated by the persistence backend.
+    # @raise [Valkyrie::Persistence::StaleObjectError]
     def save_all(resources:)
       resources.map do |resource|
         save(resource: resource)
       end
     rescue Valkyrie::Persistence::StaleObjectError
       # Re-raising with no error message to prevent confusion
-      raise Valkyrie::Persistence::StaleObjectError
+      raise Valkyrie::Persistence::StaleObjectError, "One or more resources have been updated by another process."
     end
 
+    # Delete a resource.
     # @param resource [Valkyrie::Resource] The resource to delete from the persistence
     #   backend.
     def delete(resource:)
       cache.delete(resource.id)
     end
 
-    # Wipes all data in the persistence backend.
+    # Removes all data from the persistence backend.
     def wipe!
       cache.clear
     end
@@ -61,6 +66,7 @@ module Valkyrie::Persistence::Memory
         resource.new(id: SecureRandom.uuid)
       end
 
+      # Convert all dates to DateTime in the UTC time zone for consistency.
       def normalize_dates!(resource)
         resource.attributes.each { |k, v| resource.send("#{k}=", normalize_date_values(v)) }
       end
@@ -76,12 +82,14 @@ module Valkyrie::Persistence::Memory
         value
       end
 
+      # Create a new lock token based on the current timestamp.
       def generate_lock_token(resource)
         return unless resource.optimistic_locking_enabled?
         token = Valkyrie::Persistence::OptimisticLockToken.new(adapter_id: adapter.id, token: Time.now.to_r)
         resource.send("#{Valkyrie::Persistence::Attributes::OPTIMISTIC_LOCK}=", token)
       end
 
+      # Check whether a resource is current.
       def valid_lock?(resource)
         return true unless resource.optimistic_locking_enabled?
 

data/lib/valkyrie/persistence/memory/query_service.rb

@@ -15,6 +15,7 @@ module Valkyrie::Persistence::Memory
       @query_handlers = []
     end
 
+    # Get a single resource by ID.
     # @param id [Valkyrie::ID] The ID to query for.
     # @raise [Valkyrie::Persistence::ObjectNotFoundError] Raised when the ID
     #   isn't in the persistence backend.
@@ -26,6 +27,7 @@ module Valkyrie::Persistence::Memory
       cache[id] || raise(::Valkyrie::Persistence::ObjectNotFoundError)
     end
 
+    # Get a single resource by `alternate_identifier`.
     # @param alternate_identifier [Valkyrie::ID] The alternate identifier to query for.
     # @raise [Valkyrie::Persistence::ObjectNotFoundError] Raised when the alternate identifier
     #   isn't in the persistence backend.
@@ -37,6 +39,7 @@ module Valkyrie::Persistence::Memory
       cache.select { |_key, resource| resource['alternate_ids'].include?(alternate_identifier) }.values.first || raise(::Valkyrie::Persistence::ObjectNotFoundError)
     end
 
+    # Get a batch of resources by ID.
     # @param ids [Array<Valkyrie::ID, String>] The IDs to query for.
     # @raise [ArgumentError] Raised when any ID is not a String or a Valkyrie::ID
     # @return [Array<Valkyrie::Resource>] All requested objects that were found
@@ -50,11 +53,13 @@ module Valkyrie::Persistence::Memory
       end.reject(&:nil?)
     end
 
+    # Get all objects.
     # @return [Array<Valkyrie::Resource>] All objects in the persistence backend.
     def find_all
       cache.values
     end
 
+    # Get all objects of a given model.
     # @param model [Class] Class to query for.
     # @return [Array<Valkyrie::Resource>] All objects in the persistence backend
     #   with the given class.
@@ -64,6 +69,7 @@ module Valkyrie::Persistence::Memory
       end
     end
 
+    # Get all members of a given resource.
     # @param resource [Valkyrie::Resource] Model whose members are being searched for.
     # @param model [Class] Class to query for. (optional)
     # @return [Array<Valkyrie::Resource>] child objects of type `model` referenced by
@@ -76,6 +82,7 @@ module Valkyrie::Persistence::Memory
       result.select { |obj| obj.is_a?(model) }
     end
 
+    # Get all resources referenced from a resource with a given property.
     # @param resource [Valkyrie::Resource] Model whose property is being searched.
     # @param property [Symbol] Property which, on the `resource`, contains {Valkyrie::ID}s which are
     #   to be de-referenced.
@@ -87,6 +94,7 @@ module Valkyrie::Persistence::Memory
       end
     end
 
+    # Get all resources which link to a resource with a given property.
     # @param resource [Valkyrie::Resource] The resource which is being referenced by
     #   other resources.
     # @param property [Symbol] The property which, on other resources, is
@@ -106,6 +114,7 @@ module Valkyrie::Persistence::Memory
       end
     end
 
+    # Find all parents of a given resource.
     # @param resource [Valkyrie::Resource] The resource whose parents are being searched
     #   for.
     # @return [Array<Valkyrie::Resource>] All resources which are parents of the given
@@ -117,6 +126,8 @@ module Valkyrie::Persistence::Memory
       end
     end
 
+    # Get the set of custom queries configured for this query service.
+    # @return [Valkyrie::Persistence::CustomQueryContainer] Container of custom queries
     def custom_queries
       @custom_queries ||= ::Valkyrie::Persistence::CustomQueryContainer.new(query_service: self)
     end

data/lib/valkyrie/persistence/postgres/metadata_adapter.rb

@@ -26,6 +26,8 @@ module Valkyrie::Persistence::Postgres
       @resource_factory ||= Valkyrie::Persistence::Postgres::ResourceFactory.new(adapter: self)
     end
 
+    # Construct a Valkyrie ID object using an MD5 hash generated from the database URL
+    # @return [Valkyrie::ID]
     def id
       @id ||= begin
         to_hash = "#{resource_factory.orm_class.connection_config['host']}:#{resource_factory.orm_class.connection_config['database']}"

data/lib/valkyrie/persistence/postgres/orm.rb

@@ -3,6 +3,10 @@ require 'valkyrie/persistence/postgres/orm/resource'
 module Valkyrie::Persistence::Postgres
   # Namespace for ActiveRecord access in Postgres adapter.
   module ORM
+    # Provides the name prefix for the ActiveRecord database table name
+    # (Maps to the data model for persistence)
+    # @see https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema.html#method-c-table_name_prefix
+    # @return [String]
     def self.table_name_prefix
       'orm_'
     end

data/lib/valkyrie/persistence/postgres/orm_converter.rb

@@ -4,6 +4,9 @@ module Valkyrie::Persistence::Postgres
   # {Valkyrie::Persistence::Postgres::ORM::Resource} to a {Valkyrie::Resource}
   class ORMConverter
     attr_reader :orm_object, :resource_factory
+
+    # @param [ORM::Resource] orm_object
+    # @param [ResourceFactory] resource_factory
     def initialize(orm_object, resource_factory:)
       @orm_object = orm_object
       @resource_factory = resource_factory
@@ -11,12 +14,15 @@ module Valkyrie::Persistence::Postgres
 
     # Create a new instance of the class described in attributes[:internal_resource]
     # and send it all the attributes that @orm_object has
+    # @return [Valkyrie::Resource]
     def convert!
       @resource ||= resource
     end
 
     private
 
+      # Construct a new Valkyrie Resource using the attributes retrieved from the database
+      # @return [Valkyrie::Resource]
       def resource
         resource_klass.new(
           attributes.merge(
@@ -26,6 +32,8 @@ module Valkyrie::Persistence::Postgres
         )
       end
 
+      # Construct the optimistic lock token using the adapter and lock version for the Resource
+      # @return [Valkyrie::Persistence::OptimisticLockToken]
       def lock_token
         return lock_token_warning unless orm_object.class.column_names.include?("lock_version")
         @lock_token ||=
@@ -35,6 +43,7 @@ module Valkyrie::Persistence::Postgres
           )
       end
 
+      # Issue a migration warning for previous releases of Valkyrie which did not support optimistic locking
       def lock_token_warning
         return nil unless resource_klass.optimistic_locking_enabled?
         warn "[MIGRATION REQUIRED] You have loaded a resource from the Postgres adapter with " \
@@ -44,10 +53,14 @@ module Valkyrie::Persistence::Postgres
         nil
       end
 
+      # Retrieve the Class used to construct the Valkyrie Resource
+      # @return [Class]
       def resource_klass
         internal_resource.constantize
       end
 
+      # Access the String for the Valkyrie Resource type within the attributes
+      # @return [String]
       def internal_resource
         attributes[:internal_resource]
       end
@@ -57,6 +70,8 @@ module Valkyrie::Persistence::Postgres
         @attributes ||= orm_object.attributes.merge(rdf_metadata).symbolize_keys
       end
 
+      # Generate a Hash derived from Valkyrie Resource metadata encoded in the RDF
+      # @return [Hash]
       def rdf_metadata
         @rdf_metadata ||= RDFMetadata.new(orm_object.metadata).result
       end
@@ -66,12 +81,16 @@ module Valkyrie::Persistence::Postgres
       # for {Valkyrie::Resource}
       class RDFMetadata
         attr_reader :metadata
+
+        # @param [Hash] metadata
         def initialize(metadata)
           # nil hash values are handled by the default state in dry-types
           # anyways, so don't bother processing them here.
           @metadata = metadata.compact
         end
 
+        # Convert the database attribute values and map these to the existing keys in the Valkyrie Resource metadata
+        # @return [Hash]
         def result
           Hash[
             metadata.map do |key, value|
@@ -80,16 +99,26 @@ module Valkyrie::Persistence::Postgres
           ]
         end
 
+        # Abstract base class for mapping PostgreSQL database field values to Valkyrie Resource attributes
         class PostgresValue < ::Valkyrie::ValueMapper
         end
+
         # Converts {RDF::Literal} typed-literals from JSON-LD stored into an
         #   {RDF::Literal}
         class HashValue < ::Valkyrie::ValueMapper
           PostgresValue.register(self)
+
+          # Determines whether or not a value is a Hash containing the key "@value"
+          # @param [Object] value
+          # @return [Boolean]
           def self.handles?(value)
             value.is_a?(Hash) && value["@value"]
           end
 
+          # Constructs a RDF::Literal object using the Object keyed to "@value"
+          # in the value Hash, as well as the language keyed to "@language" and
+          # datatype keyed to "@type"
+          # @return [RDF::Literal]
           def result
             RDF::Literal.new(value["@value"],
                              language: value["@language"],
@@ -100,10 +129,16 @@ module Valkyrie::Persistence::Postgres
         # Converts stored IDs into {Valkyrie::ID}s
         class IDValue < ::Valkyrie::ValueMapper
           PostgresValue.register(self)
+
+          # Determines whether or not a value is a Hash containing the key "id" (excluding those storing the Valkyrie Resource type)
+          # @param [Object] value
+          # @return [Boolean]
           def self.handles?(value)
             value.is_a?(Hash) && value["id"] && !value["internal_resource"]
           end
 
+          # Constructs a Valkyrie::ID object using the String keyed to "id" in the value
+          # @return [Valkyrie::ID]
           def result
             Valkyrie::ID.new(value["id"])
           end
@@ -112,10 +147,16 @@ module Valkyrie::Persistence::Postgres
         # Converts stored URIs into {RDF::URI}s
         class URIValue < ::Valkyrie::ValueMapper
           PostgresValue.register(self)
+
+          # Determines whether or not a value is a Hash containing the key "@id"
+          # @param [Object] value
+          # @return [Boolean]
           def self.handles?(value)
             value.is_a?(Hash) && value["@id"]
           end
 
+          # Constructs a RDF::URI object using the URI keyed to @id in the value
+          # @return [RDF::URI]
           def result
             ::RDF::URI.new(value["@id"])
           end
@@ -124,10 +165,16 @@ module Valkyrie::Persistence::Postgres
         # Converts nested records into {Valkyrie::Resource}s
         class NestedRecord < ::Valkyrie::ValueMapper
           PostgresValue.register(self)
+
+          # Determines whether or not a value is a Hash containing multiple keys
+          # @param [Object] value
+          # @return [Boolean]
           def self.handles?(value)
             value.is_a?(Hash) && value.keys.length > 1
           end
 
+          # Generates a Hash derived from the RDFMetadata for the value
+          # @return [Hash]
           def result
             RDFMetadata.new(value).result.symbolize_keys
           end
@@ -136,13 +183,19 @@ module Valkyrie::Persistence::Postgres
         # Handles iterating over arrays of values and converting each value.
         class EnumeratorValue < ::Valkyrie::ValueMapper
           PostgresValue.register(self)
+
+          # Determines whether or not a value has enumerable behavior
+          # @param [Object] value
+          # @return [Boolean]
           def self.handles?(value)
             value.respond_to?(:each)
           end
 
+          # Convert the elements in the enumerable value in Valkyrie attribute values
+          # Casts single-valued arrays to the first value, letting Types::Set and
+          # Types::Array handle converting it back.
+          # @return [Array<Object>]
           def result
-            # Cast single-valued arrays to the first value, let Types::Set and
-            # Types::Array handle converting it back.
             if value.length == 1
               calling_mapper.for(value.first).result
             else
@@ -156,6 +209,11 @@ module Valkyrie::Persistence::Postgres
         # Converts Date strings to `DateTime`
         class DateValue < ::Valkyrie::ValueMapper
           PostgresValue.register(self)
+
+          # Determines whether or not a value is an ISO 8601 datestamp String
+          # e. g. 1970-01-01
+          # @param [Object] value
+          # @return [Boolean]
           def self.handles?(value)
             return false unless value.is_a?(String)
             return false unless value[4] == "-"
@@ -166,6 +224,8 @@ module Valkyrie::Persistence::Postgres
             false
           end
 
+          # Generates a Time object in the UTC from the datestamp string value
+          # @return [Time]
           def result
             DateTime.iso8601(value).utc
           end