valkyrie 1.2.0.rc1 → 1.2.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a320a108f82f79f88b27eaeb267b7b134499e346dccaae4f93165ff95e47fa5
-  data.tar.gz: bebc13ba65b1e1e2d69fd9a9c9408f8af8ef4484984a6de568db4c90c34eb15f
+  metadata.gz: 0ce0917b94c4102aec4a20c07ad0a2d9bb8abbec21c87c91ffe3100ee266e5ee
+  data.tar.gz: 11ab274a94c6510b0910a5cf16552244eb693daf1bc595c2f9db91480279ca8a
 SHA512:
-  metadata.gz: 8a32748fc47406abdb640ce4191e6271c61a0813cb2774a444ed5c6a45a5a34fd8e599f37afab22ac6c76d71d25bcaee28df6801a3c57add7617b064fc5ed3fb
-  data.tar.gz: b353cc383371599df898f626b6e211294a34f5e351dad0fc0521a11841e79c04da3699c1e867f54e102c09379cba0366fa62e408738c3f7fa0f2637a20d59a14
+  metadata.gz: 42c1aa0891d23c99092328e0b9ff7eb8e305c25b3210b9f0d64c0493b6f9ad0c55eb091a2cd481bb4212b3ab8eb148cd3ca949e52963549734dde508a11fa411
+  data.tar.gz: 30ed893f5b392f4c765950e003aec192039ce3d53147c8428997df492e64836cd47382414b2cd0141eb5f8f265583ad040823c8037144c498ac8e60307b36611

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# v1.2.0.RC2 2018-08-10
+
+## Changes since last release
+
+* Support for ordered properties.
+  [Documentation](https://github.com/samvera-labs/valkyrie/wiki/Using-Types#ordering-values)
+* Shared specs for Solr indexers.
+
 # v1.2.0.RC1 2018-08-09
 
 ## Changes since last release

data/README.md

@@ -123,8 +123,9 @@ these kinds of classes, you should use these shared specs to test your classes f
 Valkyrie's API.
 
 When breaking changes are introduced, necessitating a major version change, the shared specs will reflect
-this. Likewise, non-breaking changes to Valkyrie can be defined as code changes that do not cause any
-errors with the current shared specs.
+this. When new features are added and a minor version is released there will be no change to the existing shared
+specs, but there may be new ones. These new shared specs will fail in your
+application if you have custom adapters, but your application will still work.
 
 Using the shared specs in your own models is described in more [detail](https://github.com/samvera-labs/valkyrie/wiki/Shared-Specs).
 
@@ -136,11 +137,18 @@ Define a custom work class:
 # frozen_string_literal: true
 class MyModel < Valkyrie::Resource
   include Valkyrie::Resource::AccessControls
-  attribute :title, Valkyrie::Types::Set       # Sets are unordered
-  attribute :authors, Valkyrie::Types::Array   # Arrays are ordered
+  attribute :title, Valkyrie::Types::Set    # Sets deduplicate values
+  attribute :date, Valkyrie::Types::Array   # Arrays can contain duplicate values
 end
 ```
 
+Attributes are unordered by default.  Adding `ordered: true` to an attribute definition will preserve the
+order of multiple values.
+
+```
+attribute :authors, Valkyrie::Types::Array.meta(ordered: true)
+```
+
 Defining resource attributes is explained in greater detail within the [Wiki](https://github.com/samvera-labs/valkyrie/wiki/Using-Types).
 
 #### Work Types Generator

data/lib/valkyrie/persistence/composite_persister.rb

@@ -37,7 +37,7 @@ module Valkyrie::Persistence
       end
     rescue Valkyrie::Persistence::StaleObjectError
       # clear out any IDs returned to reduce potential confusion
-      raise Valkyrie::Persistence::StaleObjectError
+      raise Valkyrie::Persistence::StaleObjectError, "One or more resources have been updated by another process."
     end
 
     # (see Valkyrie::Persistence::Memory::Persister#delete)

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

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Fedora
   # Represents a node in an ORE List. Used for persisting ordered members into
-  # an RDF Graph for Fedora, to keep order maintained.
+  # an Resource Description Framework (RDF) Graph for Fedora, to keep order maintained.
+  #
+  # RDF graph nodes are used to implement a linked list
+  # An RDF hash URI is referenced for the list itself
+  # <http://www.iana.org/assignments/relation/first> is the predicate which links to the first element in the list
+  # <http://www.iana.org/assignments/relation/last> is the predicate which links to the last element
+  # Each element is also referenced using a hash URI
+  # <http://www.iana.org/assignments/relation/next> is the predicate which links one element to the next element in the list
+  # (This permits unidirectional traversal)
+  # <http://www.openarchives.org/ore/terms/proxyFor> is the predicate which links any given element to its value
+  # (These can be IRIs or XML literals supported by a graph store)
+  #
+  # @see http://www.openarchives.org/ore/1.0/datamodel#Proxies
+  # @see https://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1
   class ListNode
     attr_reader :rdf_subject, :graph
     attr_writer :next, :prev
@@ -9,6 +22,11 @@ module Valkyrie::Persistence::Fedora
     attr_writer :next_uri, :prev_uri
     attr_accessor :proxy_in, :proxy_for
     attr_reader :adapter
+
+    # @param node_cache [Hash] structure used to cache the nodes of the graph
+    # @param rdf_subject [RDF::URI] the URI for the linked list in the graph store (usually a hash URI)
+    # @param adapter []
+    # @param graph [RDF::Repository] the RDF graph storing the structure of the RDF statements
     def initialize(node_cache, rdf_subject, adapter, graph = RDF::Repository.new)
       @rdf_subject = rdf_subject
       @graph = graph
@@ -48,25 +66,43 @@ module Valkyrie::Persistence::Fedora
       g
     end
 
+    # Resolves the URI for the value of the list expression
+    # @return [RDF::URI]
     def target_uri
-      adapter.id_to_uri(target_id.to_s)
+      if target_id.is_a?(Valkyrie::ID)
+        adapter.id_to_uri(target_id.to_s)
+      else
+        target_id
+      end
     end
 
+    # Generates the string ID value for the value in the list expression
+    # @return [String]
     def target_id
-      adapter.uri_to_id(proxy_for)
+      if proxy_for.to_s.include?("/") && proxy_for.to_s.start_with?(adapter.connection_prefix)
+        adapter.uri_to_id(proxy_for)
+      else
+        proxy_for
+      end
     end
 
     private
 
       attr_reader :next_uri, :prev_uri, :node_cache
 
+      # Class used to populate the RDF graph structure for the linked lists
       class Builder
         attr_reader :uri, :graph
+
+        # @param uri [RDF::URI] the URI for the linked list in the graph store
+        # @param graph [RDF::Repository] the RDF graph to be populated
         def initialize(uri, graph)
           @uri = uri
           @graph = graph
         end
 
+        # Populates attributes for the LinkedNode
+        # @param instance [ListNode]
         def populate(instance)
           instance.proxy_for = resource.proxy_for.first
           instance.proxy_in = resource.proxy_in.first
@@ -76,11 +112,14 @@ module Valkyrie::Persistence::Fedora
 
         private
 
+          # Constructs a set of triples using ActiveTriples as objects
+          # @return [Valkyrie::Persistence::Fedora::ListNode::Resource]
           def resource
             @resource ||= Resource.new(uri, data: graph)
           end
       end
 
+      # Class for providing a set of triples modeling linked list nodes
       class Resource < ActiveTriples::Resource
         property :proxy_for, predicate: ::RDF::Vocab::ORE.proxyFor, cast: false
         property :proxy_in, predicate: ::RDF::Vocab::ORE.proxyIn, cast: false

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

@@ -10,40 +10,66 @@ module Valkyrie::Persistence::Fedora
   #   )
   class MetadataAdapter
     attr_reader :connection, :base_path, :schema
+
+    # @param [Ldp::Client] connection
+    # @param [String] base_path
+    # @param [Valkyrie::Persistence::Fedora::PermissiveSchema] schema
     def initialize(connection:, base_path: "/", schema: Valkyrie::Persistence::Fedora::PermissiveSchema.new)
       @connection = connection
       @base_path = base_path
       @schema = schema
     end
 
+    # Construct the query service object using this adapter
+    # @return [Valkyrie::Persistence::Fedora::QueryService]
     def query_service
       @query_service ||= Valkyrie::Persistence::Fedora::QueryService.new(adapter: self)
     end
 
+    # Construct the persister object using this adapter
+    # @return [Valkyrie::Persistence::Fedora::Persister]
     def persister
       Valkyrie::Persistence::Fedora::Persister.new(adapter: self)
     end
 
+    # Generate the Valkyrie ID for this unique metadata adapter
+    # This uses the URL of the Fedora endpoint to ensure that this is unique
+    # @return [Valkyrie::ID]
     def id
       @id ||= Valkyrie::ID.new(Digest::MD5.hexdigest(connection_prefix))
     end
 
+    # Construct the factory object used to construct Valkyrie::Resource objects using this adapter
+    # @return [Valkyrie::Persistence::Fedora::Persister::ResourceFactory]
     def resource_factory
       Valkyrie::Persistence::Fedora::Persister::ResourceFactory.new(adapter: self)
     end
 
+    # Generate a Valkyrie ID for a given URI
+    # @param [RDF::URI] uri the URI for a Fedora resource
+    # @return [Valkyrie::ID]
     def uri_to_id(uri)
       Valkyrie::ID.new(CGI.unescape(uri.to_s.gsub(/^.*\//, '')))
     end
 
+    # Generate a URI for a given Valkyrie ID
+    # @param [RDF::URI] id the Valkyrie ID
+    # @return [RDF::URI]
     def id_to_uri(id)
       RDF::URI("#{connection_prefix}/#{pair_path(id)}/#{CGI.escape(id.to_s)}")
     end
 
+    # Generate the pairtree path for a given Valkyrie ID
+    # @see https://confluence.ucop.edu/display/Curation/PairTree
+    # @see https://wiki.duraspace.org/display/FF/Design+-+Identifier+Generation
+    # @param [Valkyrie::ID] id the Valkyrie ID
+    # @return [Array<String>]
     def pair_path(id)
       id.to_s.split(/[-\/]/).first.split("").each_slice(2).map(&:join).join("/")
     end
 
+    # Generate the prefix used in HTTP requests to the Fedora RESTful endpoint
+    # @return [String]
     def connection_prefix
       "#{connection.http.url_prefix}/#{base_path}"
     end

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

@@ -8,6 +8,7 @@ module Valkyrie::Persistence::Fedora
     attr_writer :head, :tail
     delegate :each, to: :ordered_reader
     delegate :length, to: :to_a
+
     # @param [::RDF::Enumerable] graph Enumerable where ORE statements are
     #   stored.
     # @param [::RDF::URI] head_subject URI of head node in list.
@@ -68,6 +69,9 @@ module Valkyrie::Persistence::Fedora
 
       attr_reader :node_cache
 
+      # Append a node to a linked list
+      # @param source [ListNode] the node being appended
+      # @param append_node [ListNode] the node already in the existing list
       def append_to(source, append_node)
         source.prev = append_node
         append_node.next.prev = source
@@ -76,10 +80,14 @@ module Valkyrie::Persistence::Fedora
         @changed = true
       end
 
+      # Constructs a new OrderedReader for this OrderedList
+      # @return [OrderedReader]
       def ordered_reader
         OrderedReader.new(self)
       end
 
+      # Populates the list with constructed ListNode Objects
+      # @param subject [RDF::URI]
       def build_node(subject = nil)
         return nil unless subject
         node_cache.fetch(subject) do
@@ -87,49 +95,69 @@ module Valkyrie::Persistence::Fedora
         end
       end
 
+      # Generates hash URIs for the subject of the LinkedList
+      # Should one of these URIs already be in use, a new URI will be generated
+      # @return [RDF::URI]
       def new_node_subject
         node = ::RDF::URI("##{::RDF::Node.new.id}")
         node = ::RDF::URI("##{::RDF::Node.new.id}") while node_cache.key?(node)
         node
       end
 
+      # Class used for caching LinkedNode objects mapped to URIs
       class NodeCache
         def initialize
           @cache ||= {}
         end
 
+        # Retrieve the ListNode for a given URI
+        # If a block is passed, set its output to the cache
+        # @param uri [RDF::URI]
+        # @return [ListNode]
         def fetch(uri)
           @cache[uri] ||= yield if block_given?
         end
 
+        # Determines whether or not the cache contains a key
+        # @param key [Object]
+        # @return [Boolean]
         def key?(key)
           @cache.key?(key)
         end
       end
 
+      # Class modeling sentinels within the linked list
+      # @see https://en.wikipedia.org/wiki/Sentinel_value
       class Sentinel
-        attr_reader :parent
+        attr_reader :parent, :next, :prev
         attr_writer :next, :prev
+
+        # @param parent [Valkyrie::Persistence::Fedora::OrderedList]
+        # @param next_node [ListNode]
+        # @param prev_node [ListNode]
         def initialize(parent, next_node: nil, prev_node: nil)
           @parent = parent
           @next = next_node
           @prev = prev_node
         end
 
-        attr_reader :next
-
-        attr_reader :prev
-
+        # Ensure that this always behaves like a NilClass
+        # @return [TrueClass]
         def nil?
           true
         end
 
+        # Ensure that this does not have a URI
+        # @return [NilClass]
         def rdf_subject
           nil
         end
       end
 
       class HeadSentinel < Sentinel
+        # @param parent [Valkyrie::Persistence::Fedora::OrderedList]
+        # @param next_node [ListNode]
+        # @param prev_node [ListNode]
         def initialize(*args)
           super
           @next ||= TailSentinel.new(parent, prev_node: self)
@@ -137,6 +165,9 @@ module Valkyrie::Persistence::Fedora
       end
 
       class TailSentinel < Sentinel
+        # @param parent [Valkyrie::Persistence::Fedora::OrderedList]
+        # @param next_node [ListNode]
+        # @param prev_node [ListNode]
         def initialize(*args)
           super
           prev.next = self if prev&.next != self

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

@@ -6,10 +6,14 @@ module Valkyrie::Persistence::Fedora
   class OrderedReader
     include Enumerable
     attr_reader :root
+
+    # @param root [Valkyrie::Persistence::Fedora::OrderedList]
     def initialize(root)
       @root = root
     end
 
+    # Enumerates through each node in the RDF linked list
+    # @yield [Valkyrie::Persistence::Fedora::OrderedList::HeadSentinel, Valkyrie::Persistence::Fedora::ListNode]
     def each
       proxy = first_head
       while proxy
@@ -22,6 +26,8 @@ module Valkyrie::Persistence::Fedora
 
     private
 
+      # Access the "first" (head) node for the linked list
+      # @return [Valkyrie::Persistence::Fedora::OrderedList::HeadSentinel]
       def first_head
         root.head
       end

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

@@ -53,6 +53,11 @@ module Valkyrie::Persistence::Fedora
       uri_for(:valkyrie_datetime)
     end
 
+    # @return [RDF::URI]
+    def self.valkyrie_float
+      uri_for(:valkyrie_float)
+    end
+
     # @return [RDF::URI]
     def self.valkyrie_int
       uri_for(:valkyrie_int)
@@ -76,10 +81,17 @@ module Valkyrie::Persistence::Fedora
     end
 
     attr_reader :schema
+
+    # @param schema [Hash] the structure used to store the mapping between property names and predicates
     def initialize(schema = {})
       @schema = schema
     end
 
+    # Find the predicate in the schema for the Valkyrie property
+    # If this does not exist, a URI using the property name prefixed by URI_PREFIX generates it
+    # @param resource [Valkyrie::Resource]
+    # @param property [String]
+    # @return [RDF::URI]
     def predicate_for(resource:, property:)
       schema.fetch(property) { self.class.uri_for(property) }
     end
@@ -89,8 +101,15 @@ module Valkyrie::Persistence::Fedora
     # @example:
     #   property_for(resource: nil, predicate: "http://example.com/predicate/internal_resource")
     #   #=> 'internal_resource'
+    # @param resource [Valkyrie::Resource]
+    # @param predicate [RDF::URI, String]
+    # @return [String]
     def property_for(resource:, predicate:)
-      (schema.find { |_k, v| v == RDF::URI(predicate.to_s) } || []).first || predicate.to_s.gsub(URI_PREFIX, '')
+      existing_predicates = schema.find { |_k, v| v == RDF::URI(predicate.to_s) }
+      predicate_name = predicate.to_s.gsub(URI_PREFIX, '')
+
+      return predicate_name if existing_predicates.nil? || existing_predicates.empty?
+      existing_predicates.first
     end
   end
 end

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

@@ -34,7 +34,7 @@ module Valkyrie::Persistence::Fedora
 
       alternate_resources ? save_reference_to_resource(persisted_resource, alternate_resources) : persisted_resource
     rescue Ldp::PreconditionFailed
-      raise Valkyrie::Persistence::StaleObjectError, internal_resource.id.to_s
+      raise Valkyrie::Persistence::StaleObjectError, "The object #{internal_resource.id} has been updated by another process."
     end
 
     # (see Valkyrie::Persistence::Memory::Persister#save_all)
@@ -44,7 +44,7 @@ module Valkyrie::Persistence::Fedora
       end
     rescue Valkyrie::Persistence::StaleObjectError
       # blank out the message / id
-      raise Valkyrie::Persistence::StaleObjectError
+      raise Valkyrie::Persistence::StaleObjectError, "One or more resources have been updated by another process."
     end
 
     # (see Valkyrie::Persistence::Memory::Persister#delete)
@@ -62,13 +62,18 @@ module Valkyrie::Persistence::Fedora
     end
 
     # (see Valkyrie::Persistence::Memory::Persister#wipe!)
+    # Deletes Fedora repository resource *and* the tombstone resources which remain
+    # @see https://wiki.duraspace.org/display/FEDORA4x/RESTful+HTTP+API#RESTfulHTTPAPI-RedDELETEDeletearesource
     def wipe!
       connection.delete(base_path)
       connection.delete("#{base_path}/fcr:tombstone")
     rescue => error
-      Valkyrie.logger.debug("Failed to wipe Fedora for some reason.") unless error.is_a?(::Ldp::NotFound)
+      Valkyrie.logger.debug("Failed to wipe Fedora for some reason: #{error}") unless error.is_a?(::Ldp::NotFound)
     end
 
+    # Creates the root LDP Container for the connection with Fedora
+    # @see https://www.w3.org/TR/ldp/#ldpc
+    # @return [Ldp::Container::Basic]
     def initialize_repository
       @initialized ||=
         begin
@@ -80,6 +85,9 @@ module Valkyrie::Persistence::Fedora
 
     private
 
+      # Ensure that all alternate IDs for a given resource are persisted
+      # @param [Valkyrie::Resource] resource
+      # @return [Array<Valkyrie::Persistence::Fedora::AlternateIdentifier>]
       def find_or_create_alternate_ids(resource)
         return nil unless resource.try(:alternate_ids)
 
@@ -93,6 +101,8 @@ module Valkyrie::Persistence::Fedora
         end
       end
 
+      # Ensure that any Resources referenced by alternate IDs are deleted when a Resource has these IDs deleted
+      # @param [Valkyrie::Resource] updated_resource
       def cleanup_alternate_resources(updated_resource)
         persisted_resource = adapter.query_service.find_by(id: updated_resource.id)
         removed_identifiers = persisted_resource.alternate_ids - updated_resource.alternate_ids
@@ -102,6 +112,10 @@ module Valkyrie::Persistence::Fedora
         end
       end
 
+      # Ensure that any Resources referenced by alternate IDs are persisted when a Resource has these IDs added
+      # @param [Valkyrie::Resource] resource
+      # @param [Array<Valkyrie::Persistence::Fedora::AlternateIdentifier>] alternate_resources
+      # @return [Valkyrie::Resource]
       def save_reference_to_resource(resource, alternate_resources)
         alternate_resources.each do |alternate_resource|
           alternate_resource.references = resource.id
@@ -111,6 +125,10 @@ module Valkyrie::Persistence::Fedora
         resource
       end
 
+      # Generate the lock token for a Resource, and set it for attribute
+      # @param [Valkyrie::Resource] resource
+      # @return [Valkyrie::Persistence::OptimisticLockToken]
+      # @see https://github.com/samvera-labs/valkyrie/wiki/Optimistic-Locking
       # @note Fedora's last modified response is not granular enough to produce an effective lock token
       #   therefore, we use the same implementation as the memory adapter. This could fail to lock a
       #   resource if Fedora updated this resource between the time it was saved and Valkyrie created
@@ -121,6 +139,13 @@ module Valkyrie::Persistence::Fedora
         resource.send("#{Valkyrie::Persistence::Attributes::OPTIMISTIC_LOCK}=", token)
       end
 
+      # Determine whether or not a lock token is still valid for a persisted Resource
+      #   If the persisted Resource has been updated since it was last read into memory,
+      #   then the resouce in memory has been invalidated and Valkyrie::Persistence::StaleObjectError
+      #   is raised.
+      # @param [Valkyrie::Resource] resource
+      # @see https://github.com/samvera-labs/valkyrie/wiki/Optimistic-Locking
+      # @raise [Valkyrie::Persistence::StaleObjectError]
       def validate_lock_token(resource)
         return unless resource.optimistic_locking_enabled?
         return if resource.id.blank?
@@ -132,10 +157,12 @@ module Valkyrie::Persistence::Fedora
         retrieved_lock_token = retrieved_lock_tokens.find { |lock_token| lock_token.adapter_id == adapter.id }
         return if retrieved_lock_token.blank?
 
-        raise Valkyrie::Persistence::StaleObjectError, resource.id.to_s unless current_lock_token == retrieved_lock_token
+        raise Valkyrie::Persistence::StaleObjectError, "The object #{resource.id} has been updated by another process." unless current_lock_token == retrieved_lock_token
       end
 
       # Retrieve the lock token that holds Fedora's system-managed last-modified date
+      # @param [Valkyrie::Resource] resource
+      # @return [Valkyrie::Persistence::OptimisticLockToken]
       def native_lock_token(resource)
         return unless resource.optimistic_locking_enabled?
         resource[Valkyrie::Persistence::Attributes::OPTIMISTIC_LOCK].find { |lock_token| lock_token.adapter_id == "native-#{adapter.id}" }
@@ -144,6 +171,8 @@ module Valkyrie::Persistence::Fedora
       # Set Fedora request headers:
       # * `Prefer: handling=lenient; received="minimal"` allows us to avoid sending all server-managed triples
       # * `If-Unmodified-Since` triggers Fedora's server-side optimistic locking
+      # @param request [Faraday::Request]
+      # @param lock_token [Valkyrie::Persistence::OptimisticLockToken]
       def update_request_headers(request, lock_token)
         request.headers["Prefer"] = "handling=lenient; received=\"minimal\""
         request.headers["If-Unmodified-Since"] = lock_token.token if lock_token