valkyrie 0.1.0 → 1.0.0.rc1

data/lib/valkyrie/metadata_adapter.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 module Valkyrie
+  # MetadataAdapter is the primary DataMapper object for metadata persistence.
+  #  Used to register and locate adapters, persisters, and query services for individual
+  #  metadata storage backends (such as fedora, postgres, etc)
   class MetadataAdapter
     class_attribute :adapters
     self.adapters = {}
@@ -14,8 +17,33 @@ module Valkyrie
       # Find an adapter by its short name.
       # @param short_name [Symbol]
       # @return [#persister,#query_service]
+      # @raise RuntimeError when the given short_name is not found amongst the registered adapters
       def find(short_name)
-        adapters[short_name.to_sym]
+        symbolized_key = short_name.to_sym
+        return adapters[symbolized_key] if adapters.key?(symbolized_key)
+        raise "Unable to find unregistered adapter `#{short_name}'"
+      end
+
+      # @api public
+      # @since 0.1.0
+      # Find the persister registered under the given short-name
+      #
+      # @param short_name [Symbol]
+      # @return [Object] an object that behaves like "a Valkyrie::Persister"
+      # @see GEM_ROOT/lib/valkyrie/specs/shared_specs/persister.rb
+      def find_persister_for(short_name)
+        find(short_name).persister
+      end
+
+      # @api public
+      # @since 0.1.0
+      # Find the query service registered under the given short-name
+      #
+      # @param short_name [Symbol]
+      # @return [Object] an object that behaves like "a Valkyrie query provider"
+      # @see GEM_ROOT/lib/valkyrie/specs/shared_specs/queries.rb
+      def find_query_service_for(short_name)
+        find(short_name).query_service
       end
     end
   end

data/lib/valkyrie/persistence.rb

@@ -1,6 +1,31 @@
 # frozen_string_literal: true
 module Valkyrie
+  # This is a namespacing module for metadata persisters as per the DataMapper pattern
+  #  https://en.wikipedia.org/wiki/Data_mapper_pattern
+  #
+  # @note These persisters do not store binary content.
+  #       See Valkyrie::Storage for persisting binary content (files).
+  #
+  # @example Register persisters in an initializer using Valkyrie::MetadataAdapter.register
+  #   Valkyrie::MetadataAdapter.register(
+  #     Valkyrie::Persistence::Memory::MetadataAdapter.new,
+  #     :memory
+  #   )
+  #
+  # @example Retrieve a registered persister using Valkyrie::MetadataAdapter.find
+  #   Valkyrie::MetadataAdapter.find(:memory)
+  #   => <Valkyrie::Persistence::Memory::MetadataAdapter:0x007fa6ec031bd8>
+  #
+  # @example Saving an object
+  #
+  #   object1 = MyModel.new title: 'My Cool Object', authors: ['Jones, Alice', 'Smith, Bob']
+  #   object1 = Valkyrie.config.metadata_adapter.persister.save(model: object1)
+  #
+  # @see https://github.com/samvera-labs/valkyrie/wiki/Persistence
+  # @see lib/valkyrie/specs/shared_specs/persister.rb
+  #
   module Persistence
+    require 'valkyrie/persistence/custom_query_container'
     require 'valkyrie/persistence/memory'
     require 'valkyrie/persistence/postgres'
     require 'valkyrie/persistence/solr'
@@ -10,5 +35,7 @@ module Valkyrie
     require 'valkyrie/persistence/buffered_persister'
     class ObjectNotFoundError < StandardError
     end
+    class UnsupportedDatatype < StandardError
+    end
   end
 end

data/lib/valkyrie/persistence/buffered_persister.rb

@@ -1,8 +1,24 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to proxy another Metadata Persister
+  #
+  # Provides with_buffer to send multiple updates at one time to the proxied persister
+  #  In some cases this will realize performance gains
+  #
+  # @example
+  #     buffered_persister.with_buffer do |persist, buffer|
+  #       yield Valkyrie::AdapterContainer.new(persister: persist, query_service: metadata_adapter.query_service)
+  #       buffer.persister.deletes.uniq(&:id).each do |delete|
+  #         index_persister.delete(resource: delete)
+  #       end
+  #       index_persister.save_all(resources: buffer.query_service.find_all)
+  #     end
+  #
+  # @see Valkyrie::Persistence::DeleteTrackingBuffer for more information on deletes used in the example above
+  #
   class BufferedPersister
     attr_reader :persister, :buffer_class
-    delegate :adapter, to: :persister
+    delegate :adapter, :wipe!, to: :persister
     def initialize(persister, buffer_class: Valkyrie::Persistence::DeleteTrackingBuffer)
       @persister = persister
       @buffer_class = buffer_class

data/lib/valkyrie/persistence/composite_persister.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
-  ##
-  # Wrap up multiple persisters under a common interface, to transparently
+  # Wraps up multiple persisters under a common interface, to transparently
   # persist to multiple places at once.
+  #
+  # @example
+  #   persister = Valkyrie.config.metadata_adapter
+  #   index_persister = Valkyrie::MetadataAdapter.find(:index_solr)
+  #   Valkyrie::MetadataAdapter.register(
+  #     Valkyrie::Persistence::CompositePersister.new(persister, index_persister),
+  #     :my_composite_persister
+  #   )
+  #
   class CompositePersister
     attr_reader :persisters
     def initialize(*persisters)
@@ -25,5 +33,9 @@ module Valkyrie::Persistence
     def delete(resource:)
       persisters.inject(resource) { |m, persister| persister.delete(resource: m) }
     end
+
+    def wipe!
+      persisters.each_entry(&:wipe!)
+    end
   end
 end

data/lib/valkyrie/persistence/custom_query_container.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Valkyrie::Persistence
+  # Allows for implementors to register and use custom queries on a
+  #  per persister basis
+  #
+  # @example Custom Query Class
+  #
+  #     # Snippet from custom query class see: https://github.com/pulibrary/figgy/blob/d0b1305a1564c2aa4e7d6c1e99f0c2a88ed673f4/app/queries/find_by_string_property.rb
+  #     class FindByStringProperty
+  #       def self.queries
+  #         [:find_by_string_property]
+  #       end
+  #
+  #       ...
+  #
+  #       def initialize(query_service:)
+  #         @query_service = query_service
+  #       end
+  #       ...
+  #
+  #       def find_by_string_property(property:, value:)
+  #         internal_array = "{\"#{property}\": [\"#{value}\"]}"
+  #         run_query(query, internal_array)
+  #       end
+  #       ...
+  #     end
+  #
+  # @example Registration
+  #
+  #   # in config/initializers/valkyrie.rb
+  #   [FindByStringProperty].each do |query_handler|
+  #     Valkyrie.config.metadata_adapter.query_service.custom_queries.register_query_handler(query_handler)
+  #   end
+  #
+  # @see lib/valkyrie/persistence/solr/query_service.rb for use of this class
+  #
+  class CustomQueryContainer
+    attr_reader :query_service, :query_handlers
+    def initialize(query_service:)
+      @query_service = query_service
+      @query_handlers = []
+    end
+
+    def register_query_handler(query_handler)
+      @query_handlers << query_handler
+    end
+
+    def method_missing(meth_name, *args, &block)
+      query_handler = find_query_handler(meth_name).new(query_service: query_service)
+      return super unless query_handler
+      query_handler.__send__(meth_name, *args, &block)
+    end
+
+    def find_query_handler(method)
+      query_handlers.find { |x| x.queries.include?(method) }
+    end
+
+    def respond_to_missing?(meth_name, _args)
+      find_query_handler(meth_name).present?
+    end
+  end
+end

data/lib/valkyrie/persistence/delete_tracking_buffer.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata in Memory
+  #  In Addition this stores an array of all deleted resources
+  #
+  # This is used by the Valkyrie::Persistence::BufferedPersister to
+  #   buffer deletes for efficiency
+  #
+  # @see Valkyrie::Persistence::BufferedPersister
+  #
   class DeleteTrackingBuffer < Valkyrie::Persistence::Memory::MetadataAdapter
     def persister
       @persister ||= DeleteTrackingBuffer::Persister.new(self)

data/lib/valkyrie/persistence/fedora.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
+#
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata into Fedora
   module Fedora
+    require 'valkyrie/persistence/fedora/permissive_schema'
     require 'valkyrie/persistence/fedora/metadata_adapter'
     require 'valkyrie/persistence/fedora/persister'
     require 'valkyrie/persistence/fedora/query_service'

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

@@ -1,8 +1,11 @@
 # 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.
   class ListNode
     attr_reader :rdf_subject, :graph
-    attr_accessor :prev, :next, :target
+    attr_writer :next, :prev
+    attr_accessor :target
     attr_writer :next_uri, :prev_uri
     attr_accessor :proxy_in, :proxy_for
     attr_reader :adapter
@@ -55,7 +58,7 @@ module Valkyrie::Persistence::Fedora
 
     private
 
-      attr_reader :next_uri, :prev_uri, :graph, :node_cache
+      attr_reader :next_uri, :prev_uri, :node_cache
 
       class Builder
         attr_reader :uri, :graph

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

@@ -1,14 +1,23 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Fedora
+  # Metadata Adapter for Fedora adapter.
+  #
+  # @example Instantiate with connection to Fedora.
+  #   Valkyrie::Persistence::Fedora::MetadataAdapter.new(
+  #     connection: ::Ldp::Client.new("http://localhost:8988/rest"),
+  #     base_path: "test_fed",
+  #     schema: Valkyrie::Persistence::Fedora::PermissiveSchema.new(title: RDF::URI("http://bad.com/title"))
+  #   )
   class MetadataAdapter
-    attr_reader :connection, :base_path
-    def initialize(connection:, base_path: "/")
+    attr_reader :connection, :base_path, :schema
+    def initialize(connection:, base_path: "/", schema: Valkyrie::Persistence::Fedora::PermissiveSchema.new)
       @connection = connection
       @base_path = base_path
+      @schema = schema
     end
 
     def query_service
-      Valkyrie::Persistence::Fedora::QueryService.new(adapter: self)
+      @query_service ||= Valkyrie::Persistence::Fedora::QueryService.new(adapter: self)
     end
 
     def persister
@@ -32,14 +41,7 @@ module Valkyrie::Persistence::Fedora
     end
 
     def connection_prefix
-      "#{connection.options}/#{base_path}"
-    end
-
-    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)
+      "#{connection.http.url_prefix}/#{base_path}"
     end
   end
 end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Fedora
-  ##
   # Ruby object representation of an ORE doubly linked list.
+  # Used in the Fedora adapter for persisting ordered members.
   class OrderedList
     include Enumerable
     attr_reader :graph, :head_subject, :tail_subject, :adapter
@@ -139,7 +139,7 @@ module Valkyrie::Persistence::Fedora
       class TailSentinel < Sentinel
         def initialize(*args)
           super
-          prev.next = self if prev && prev.next != self
+          prev.next = self if prev&.next != self
         end
       end
   end

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

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Fedora
-  ##
   # Lazily iterates over a doubly linked list, fixing up nodes if necessary.
+  # Used for reading ordered members out of Fedora, and then converting them to
+  # member_ids.
   class OrderedReader
     include Enumerable
     attr_reader :root
@@ -14,7 +15,7 @@ module Valkyrie::Persistence::Fedora
       while proxy
         yield proxy unless proxy.nil?
         next_proxy = proxy.next
-        next_proxy.try(:prev=, proxy) if next_proxy && next_proxy.prev != proxy
+        next_proxy.try(:prev=, proxy) if next_proxy&.prev != proxy
         proxy = next_proxy
       end
     end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+module Valkyrie::Persistence::Fedora
+  # Default schema for Fedora MetadataAdapter. It's used to generate a mapping
+  # of {Valkyrie::Resource} attributes to predicates. This implementation will
+  # make up a URI if one doesn't exist in a passed in schema.
+  #
+  # @example Passing in a mapping
+  #   schema = Valkyrie::Persistence::Fedora::PermissiveSchema.new(member_ids:
+  #     RDF::URI("http://mypredicates.com/member_ids"))
+  #   schema.predicate_for(resource: Resource.new, property: :member_ids) # => RDF::URI<"http://mypredicates.com/member_ids">
+  #   schema.predicate_for(resource: Resource.new, property: :unknown) # => RDF::URI<"http://example.com/predicate/unknown">
+  class PermissiveSchema
+    URI_PREFIX = 'http://example.com/predicate/'
+
+    # @return [RDF::URI]
+    def self.valkyrie_id
+      uri_for('valkyrie_id')
+    end
+
+    # @return [RDF::URI]
+    def self.id
+      uri_for(:id)
+    end
+
+    # @return [RDF::URI]
+    def self.member_ids
+      uri_for(:member_ids)
+    end
+
+    # @return [RDF::URI]
+    def self.valkyrie_bool
+      uri_for(:valkyrie_bool)
+    end
+
+    # @return [RDF::URI]
+    def self.valkyrie_datetime
+      uri_for(:valkyrie_datetime)
+    end
+
+    # @return [RDF::URI]
+    def self.valkyrie_int
+      uri_for(:valkyrie_int)
+    end
+
+    # @return [RDF::URI]
+    def self.valkyrie_time
+      uri_for(:valkyrie_time)
+    end
+
+    # Cast the property to a URI in the namespace
+    # @param property [Symbol]
+    # @return [RDF::URI]
+    def self.uri_for(property)
+      RDF::URI("#{URI_PREFIX}#{property}")
+    end
+
+    attr_reader :schema
+    def initialize(schema = {})
+      @schema = schema
+    end
+
+    def predicate_for(resource:, property:)
+      schema.fetch(property) { self.class.uri_for(property) }
+    end
+
+    # Find the property in the schema. If it's not there check to see
+    # if this prediate is in the URI_PREFIX namespace, return the suffix as the property
+    # @example:
+    #   property_for(resource: nil, predicate: "http://example.com/predicate/internal_resource")
+    #   #=> 'internal_resource'
+    def property_for(resource:, predicate:)
+      (schema.find { |_k, v| v == RDF::URI(predicate.to_s) } || []).first || predicate.to_s.gsub(URI_PREFIX, '')
+    end
+  end
+end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Fedora
+  # Persister for Fedora MetadataAdapter.
   class Persister
     require 'valkyrie/persistence/fedora/persister/resource_factory'
     attr_reader :adapter
@@ -8,10 +9,12 @@ module Valkyrie::Persistence::Fedora
       @adapter = adapter
     end
 
+    # (see Valkyrie::Persistence::Memory::Persister#save)
     def save(resource:)
       initialize_repository
       resource.created_at ||= Time.current
       resource.updated_at ||= Time.current
+      ensure_multiple_values!(resource)
       orm = resource_factory.from_resource(resource: resource)
       if !orm.new? || resource.id
         orm.update do |req|
@@ -23,18 +26,28 @@ module Valkyrie::Persistence::Fedora
       resource_factory.to_resource(object: orm)
     end
 
+    # (see Valkyrie::Persistence::Memory::Persister#save_all)
     def save_all(resources:)
       resources.map do |resource|
         save(resource: resource)
       end
     end
 
+    # (see Valkyrie::Persistence::Memory::Persister#delete)
     def delete(resource:)
       orm = resource_factory.from_resource(resource: resource)
       orm.delete
       resource
     end
 
+    # (see Valkyrie::Persistence::Memory::Persister#wipe!)
+    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)
+    end
+
     def initialize_repository
       @initialized ||=
         begin
@@ -43,5 +56,14 @@ module Valkyrie::Persistence::Fedora
           true
         end
     end
+
+    private
+
+      def ensure_multiple_values!(resource)
+        bad_keys = resource.attributes.except(:internal_resource, :created_at, :updated_at, :new_record, :id).select do |_k, v|
+          !v.nil? && !v.is_a?(Array)
+        end
+        raise ::Valkyrie::Persistence::UnsupportedDatatype, "#{resource}: #{bad_keys.keys} have non-array values, which can not be persisted by Valkyrie. Cast to arrays." unless bad_keys.keys.empty?
+      end
   end
 end