valkyrie 1.2.0.rc1 → 1.2.0.rc2

data/lib/valkyrie/persistence/solr/queries.rb

@@ -11,5 +11,6 @@ module Valkyrie::Persistence::Solr
     require 'valkyrie/persistence/solr/queries/find_inverse_references_query'
     require 'valkyrie/persistence/solr/queries/find_members_query'
     require 'valkyrie/persistence/solr/queries/find_references_query'
+    require 'valkyrie/persistence/solr/queries/find_ordered_references_query'
   end
 end

data/lib/valkyrie/persistence/solr/queries/default_paginator.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence::Solr::Queries
   # Acts as a null object representing the default case for paginating over solr
-  # results. Often only used for the first iteration of a loop.
+  # results. Often only used for the first iteration of a loop, or to retrieve
+  # all Documents in an index.
   class DefaultPaginator
+    # Default parameter for the next page in search results in a Solr query request
+    # @see https://lucene.apache.org/solr/guide/pagination-of-results.html
+    # @return [Integer]
     def next_page
       1
     end
 
+    # Default parameter for the number of documents in a page of search results in a Solr query request
+    # @see https://lucene.apache.org/solr/guide/pagination-of-results.html
+    # @return [Integer]
     def per_page
       100
     end
 
+    # Default state for the whether or not additional pages of search results in a Solr query response exist
+    # @see https://lucene.apache.org/solr/guide/pagination-of-results.html
+    # @return [Boolean]
     def has_next?
       true
     end

data/lib/valkyrie/persistence/solr/queries/find_all_query.rb

@@ -4,16 +4,25 @@ module Valkyrie::Persistence::Solr::Queries
   # {Valkyrie::Resource}s
   class FindAllQuery
     attr_reader :connection, :resource_factory, :model
+
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
+    # @param [Class] model
     def initialize(connection:, resource_factory:, model: nil)
       @connection = connection
       @resource_factory = resource_factory
       @model = model
     end
 
+    # Iterate over each Solr Document and convert each Document into a Valkyrie Resource
+    # @return [Array<Valkyrie::Resource>]
     def run
       enum_for(:each)
     end
 
+    # Queries for all Documents in the Solr index
+    # For each Document, it yields the Valkyrie Resource which was converted from it
+    # @yield [Valkyrie::Resource]
     def each
       docs = DefaultPaginator.new
       while docs.has_next?
@@ -24,6 +33,9 @@ module Valkyrie::Persistence::Solr::Queries
       end
     end
 
+    # Generates the Solr query for retrieving all Documents in the index
+    # If a model is specified for the query, it is scoped to that Valkyrie resource type
+    # @return [String]
     def query
       if !model
         "*:*"

data/lib/valkyrie/persistence/solr/queries/find_by_alternate_identifier_query.rb

@@ -4,21 +4,33 @@ module Valkyrie::Persistence::Solr::Queries
   class FindByAlternateIdentifierQuery
     attr_reader :connection, :resource_factory
     attr_writer :alternate_identifier
+
+    # @param [Valkyrie::ID] alternate_identifier
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
     def initialize(alternate_identifier, connection:, resource_factory:)
       @alternate_identifier = alternate_identifier
       @connection = connection
       @resource_factory = resource_factory
     end
 
+    # Constructs a Valkyrie Resource found using the alternate ID
+    # @raise [Valkyrie::Persistence::ObjectNotFoundError]
+    # @return [Valkyrie::Resource]
     def run
       raise ::Valkyrie::Persistence::ObjectNotFoundError unless resource
       resource_factory.to_resource(object: resource)
     end
 
+    # Retrieve the string value for the alternate ID
+    # @return [String]
     def alternate_identifier
       @alternate_identifier.to_s
     end
 
+    # Query Solr for for the first document with the alternate ID in a field
+    # @note the field used here is alternate_ids_ssim and the value is prefixed by "id-"
+    # @return [Hash]
     def resource
       connection.get("select", params: { q: "alternate_ids_ssim:\"id-#{alternate_identifier}\"", fl: "*", rows: 1 })["response"]["docs"].first
     end

data/lib/valkyrie/persistence/solr/queries/find_by_id_query.rb

@@ -4,21 +4,32 @@ module Valkyrie::Persistence::Solr::Queries
   class FindByIdQuery
     attr_reader :connection, :resource_factory
     attr_writer :id
+
+    # @param [Valkyrie::ID] id
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
     def initialize(id, connection:, resource_factory:)
       @id = id
       @connection = connection
       @resource_factory = resource_factory
     end
 
+    # Constructs a Valkyrie Resource found using the ID
+    # @raise [Valkyrie::Persistence::ObjectNotFoundError]
+    # @return [Valkyrie::Resource]
     def run
       raise ::Valkyrie::Persistence::ObjectNotFoundError unless resource
       resource_factory.to_resource(object: resource)
     end
 
+    # Retrieve the string value for the ID
+    # @return [String]
     def id
       @id.to_s
     end
 
+    # Query Solr for for the first document with the ID in a field
+    # @return [Hash]
     def resource
       connection.get("select", params: { q: "id:\"#{id}\"", fl: "*", rows: 1 })["response"]["docs"].first
     end

data/lib/valkyrie/persistence/solr/queries/find_inverse_references_query.rb

@@ -4,6 +4,11 @@ module Valkyrie::Persistence::Solr::Queries
   # reference a {Valkyrie::Resource} in a given property.
   class FindInverseReferencesQuery
     attr_reader :resource, :property, :connection, :resource_factory
+
+    # @param [Valkyrie::Resource] resource
+    # @param [String] property
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
     def initialize(resource:, property:, connection:, resource_factory:)
       @resource = resource
       @property = property
@@ -11,10 +16,15 @@ module Valkyrie::Persistence::Solr::Queries
       @resource_factory = resource_factory
     end
 
+    # Iterate over each Solr Document and convert each Document into a Valkyrie Resource
+    # @return [Array<Valkyrie::Resource>]
     def run
       enum_for(:each)
     end
 
+    # Queries for all Documents in the Solr index
+    # For each Document, it yields the Valkyrie Resource which was converted from it
+    # @yield [Valkyrie::Resource]
     def each
       docs = DefaultPaginator.new
       while docs.has_next?
@@ -25,6 +35,9 @@ module Valkyrie::Persistence::Solr::Queries
       end
     end
 
+    # Query Solr for for all documents with the ID in the requested field
+    # @note the field used here is a _ssim dynamic field and the value is prefixed by "id-"
+    # @return [Hash]
     def query
       "#{property}_ssim:id-#{resource.id}"
     end

data/lib/valkyrie/persistence/solr/queries/find_many_by_ids_query.rb

@@ -3,16 +3,25 @@ module Valkyrie::Persistence::Solr::Queries
   class FindManyByIdsQuery
     attr_reader :connection, :resource_factory
     attr_accessor :ids
+
+    # @param [Array<Valkyrie::ID>] ids
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
     def initialize(ids, connection:, resource_factory:)
       @ids = ids
       @connection = connection
       @resource_factory = resource_factory
     end
 
+    # Iterate over each Solr Document and convert each Document into a Valkyrie Resource
+    # @return [Array<Valkyrie::Resource>]
     def run
       resources.map { |solr_resource| resource_factory.to_resource(object: solr_resource) }
     end
 
+    # Query Solr for for all documents with the IDs in the requested field
+    # @note this uses the "OR" operator for concatenating IDs and requests 1000000000 Documents
+    # @return [Array<Hash>]
     def resources
       id_query = ids.map { |id| "\"#{id}\"" }.join(' OR ')
       @resources ||= connection.get("select", params: { q: "id:(#{id_query})", fl: "*", defType: 'lucene', rows: 1_000_000_000 })["response"]["docs"]

data/lib/valkyrie/persistence/solr/queries/find_members_query.rb

@@ -4,6 +4,11 @@ module Valkyrie::Persistence::Solr::Queries
   # {Valkyrie::Resource}s
   class FindMembersQuery
     attr_reader :resource, :connection, :resource_factory, :model
+
+    # @param [Valkyrie::Resource] resource
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
+    # @param [Class] model
     def initialize(resource:, connection:, resource_factory:, model:)
       @resource = resource
       @connection = connection
@@ -11,10 +16,16 @@ module Valkyrie::Persistence::Solr::Queries
       @model = model
     end
 
+    # Iterate over each Solr Document and convert each Document into a Valkyrie Resource
+    # @return [Array<Valkyrie::Resource>]
     def run
       enum_for(:each)
     end
 
+    # Queries for all member Documents in the Solr index
+    # For each Document, it yields the Valkyrie Resource which was converted from it
+    # Results are ordered by the member IDs specified in the Valkyrie Resource attribute
+    # @yield [Valkyrie::Resource]
     def each
       return [] unless resource.id.present?
       unordered_members.sort_by { |x| member_ids.index(x.id) }.each do |member|
@@ -22,12 +33,17 @@ module Valkyrie::Persistence::Solr::Queries
       end
     end
 
+    # Retrieving the Solr Documents for the member resources, construct Valkyrie Resources for each
+    # @return [Array<Valkyrie::Resource>]
     def unordered_members
       docs.map do |doc|
         resource_factory.to_resource(object: doc)
       end
     end
 
+    # Query Solr for all members of the Valkyrie Resource
+    # If a model is specified, this is used to filter the results
+    # @return [Array<Hash>]
     def docs
       options = { q: query, rows: 1_000_000_000 }
       options[:fq] = "{!raw f=internal_resource_ssim}#{model}" if model
@@ -36,14 +52,21 @@ module Valkyrie::Persistence::Solr::Queries
       result["response"]["docs"]
     end
 
+    # Access the IDs of the members for the Valkyrie Resource
+    # @return [Array<Valkyrie::ID>]
     def member_ids
       Array.wrap(resource.member_ids)
     end
 
+    # Generate the Solr join query using the id_ssi field
+    # @see https://lucene.apache.org/solr/guide/other-parsers.html#join-query-parser
+    # @return [String]
     def query
       "{!join from=#{MEMBER_IDS} to=join_id_ssi}id:#{id}"
     end
 
+    # Retrieve the string value for the ID
+    # @return [String]
     def id
       resource.id.to_s
     end

data/lib/valkyrie/persistence/solr/queries/find_ordered_references_query.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module Valkyrie::Persistence::Solr::Queries
+  # Responsible for returning all {Valkyrie::Resource}s which are referenced in
+  # a given {Valkyrie::Resource}'s property, in the order given in that property.
+  class FindOrderedReferencesQuery
+    attr_reader :resource, :property, :connection, :resource_factory
+    def initialize(resource:, property:, connection:, resource_factory:)
+      @resource = resource
+      @property = property
+      @connection = connection
+      @resource_factory = resource_factory
+    end
+
+    def run
+      enum_for(:each)
+    end
+
+    def each
+      # map them off of the property to fix solr's deduplication
+      property_values.map { |id| unordered_members.find { |member| member.id == id } } .each do |value|
+        yield value
+      end
+    end
+
+    def unordered_members
+      docs.map do |doc|
+        resource_factory.to_resource(object: doc)
+      end
+    end
+
+    def docs
+      options = { q: query, rows: 1_000_000_000 }
+      options[:defType] = 'lucene'
+      result = connection.get("select", params: options)
+      result.fetch('response').fetch('docs')
+    end
+
+    def property_values
+      Array.wrap(resource[property])
+    end
+
+    def query
+      "{!join from=#{property}_ssim to=join_id_ssi}id:#{id}"
+    end
+
+    def id
+      resource.id.to_s
+    end
+  end
+end

data/lib/valkyrie/persistence/solr/queries/find_references_query.rb

@@ -4,6 +4,11 @@ module Valkyrie::Persistence::Solr::Queries
   # a given {Valkyrie::Resource}'s property.
   class FindReferencesQuery
     attr_reader :resource, :property, :connection, :resource_factory
+
+    # @param [Valkyrie::Resource] resource
+    # @param [String] property resource property referencing other resources
+    # @param [RSolr::Client] connection
+    # @param [ResourceFactory] resource_factory
     def initialize(resource:, property:, connection:, resource_factory:)
       @resource = resource
       @property = property
@@ -11,10 +16,15 @@ module Valkyrie::Persistence::Solr::Queries
       @resource_factory = resource_factory
     end
 
+    # Iterate over each Solr Document and convert each Document into a Valkyrie Resource
+    # @return [Array<Valkyrie::Resource>]
     def run
       enum_for(:each)
     end
 
+    # Queries for all Documents in the Solr index
+    # For each Document, it yields the Valkyrie Resource which was converted from it
+    # @yield [Valkyrie::Resource]
     def each
       docs = DefaultPaginator.new
       while docs.has_next?
@@ -27,10 +37,15 @@ module Valkyrie::Persistence::Solr::Queries
       end
     end
 
+    # Generate the Solr join query using the id_ssi field
+    # @see https://lucene.apache.org/solr/guide/other-parsers.html#join-query-parser
+    # @return [String]
     def query
       "{!join from=#{property}_ssim to=join_id_ssi}id:#{id}"
     end
 
+    # Retrieve the string value for the ID
+    # @return [String]
     def id
       resource.id.to_s
     end

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

@@ -4,30 +4,34 @@ module Valkyrie::Persistence::Solr
   # Query Service for Solr MetadataAdapter.
   class QueryService
     attr_reader :connection, :resource_factory
-
-    # @param connection [RSolr::Client]
-    # @param resource_factory [Valkyrie::Persistence::Solr::ResourceFactory]
-    # @note (see Valkyrie::Persistence::Memory::QueryService#initialize)
+    # @param [RSolr::Client] connection
+    # @param [Valkyrie::Persistence::Solr::ResourceFactory] resource_factory
     def initialize(connection:, resource_factory:)
       @connection = connection
       @resource_factory = resource_factory
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_by)
+    # Find resources by Valkyrie ID
+    # @param [Valkyrie::ID] id
+    # @return [Valkyrie::Resource]
     def find_by(id:)
       id = Valkyrie::ID.new(id.to_s) if id.is_a?(String)
       validate_id(id)
       Valkyrie::Persistence::Solr::Queries::FindByIdQuery.new(id, connection: connection, resource_factory: resource_factory).run
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_by_alternate_identifier)
+    # Find resources by a Valkyrie alternate identifier
+    # @param [Valkyrie::ID] alternate_identifier
+    # @return [Valkyrie::Resource]
     def find_by_alternate_identifier(alternate_identifier:)
       alternate_identifier = Valkyrie::ID.new(alternate_identifier.to_s) if alternate_identifier.is_a?(String)
       validate_id(alternate_identifier)
       Valkyrie::Persistence::Solr::Queries::FindByAlternateIdentifierQuery.new(alternate_identifier, connection: connection, resource_factory: resource_factory).run
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_many_by_ids)
+    # Find resources using a set of Valkyrie IDs
+    # @param [Array<Valkyrie::ID>] ids
+    # @return [Array<Valkyrie::Resource>]
     def find_many_by_ids(ids:)
       ids.map! do |id|
         id = Valkyrie::ID.new(id.to_s) if id.is_a?(String)
@@ -37,49 +41,78 @@ module Valkyrie::Persistence::Solr
       Valkyrie::Persistence::Solr::Queries::FindManyByIdsQuery.new(ids, connection: connection, resource_factory: resource_factory).run
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_all)
+    # Find all of the Valkyrie Resources persisted in the Solr index
+    # @return [Array<Valkyrie::Resource>]
     def find_all
       Valkyrie::Persistence::Solr::Queries::FindAllQuery.new(connection: connection, resource_factory: resource_factory).run
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_all_of_model)
+    # Find all of the Valkyrie Resources of a model persisted in the Solr index
+    # @param [Class, String] model the Valkyrie::Resource Class
+    # @return [Array<Valkyrie::Resource>]
     def find_all_of_model(model:)
       Valkyrie::Persistence::Solr::Queries::FindAllQuery.new(connection: connection, resource_factory: resource_factory, model: model).run
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_parents)
+    # Find all of the parent resources for a given Valkyrie Resource
+    # @param [Valkyrie::Resource] member resource
+    # @return [Array<Valkyrie::Resource>] parent resources
     def find_parents(resource:)
       find_inverse_references_by(resource: resource, property: :member_ids)
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_members)
+    # Find all of the member resources for a given Valkyrie Resource
+    # @param [Valkyrie::Resource] parent resource
+    # @return [Array<Valkyrie::Resource>] member resources
     def find_members(resource:, model: nil)
       Valkyrie::Persistence::Solr::Queries::FindMembersQuery.new(resource: resource, model: model, connection: connection, resource_factory: resource_factory).run
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_references_by)
+    # Find all of the resources referenced by a given Valkyrie Resource using a specific property
+    # @param [Valkyrie::Resource] resource
+    # @param [Symbol, String] property
+    # @return [Array<Valkyrie::Resource>] referenced resources
     def find_references_by(resource:, property:)
-      Valkyrie::Persistence::Solr::Queries::FindReferencesQuery.new(resource: resource, property: property, connection: connection, resource_factory: resource_factory).run
+      if ordered_property?(resource: resource, property: property)
+        Valkyrie::Persistence::Solr::Queries::FindOrderedReferencesQuery.new(resource: resource, property: property, connection: connection, resource_factory: resource_factory).run
+      else
+        Valkyrie::Persistence::Solr::Queries::FindReferencesQuery.new(resource: resource, property: property, connection: connection, resource_factory: resource_factory).run
+      end
     end
 
-    # (see Valkyrie::Persistence::Memory::QueryService#find_inverse_references_by)
+    # Find all of the resources referencing a given Valkyrie Resource using a specific property
+    # (e. g. find all resources referencing a parent resource as a collection using the property "member_of_collections")
+    # @param [Valkyrie::Resource] referenced resource
+    # @param [Symbol, String] property
+    # @return [Array<Valkyrie::Resource>] related resources
     def find_inverse_references_by(resource:, property:)
       ensure_persisted(resource)
       Valkyrie::Persistence::Solr::Queries::FindInverseReferencesQuery.new(resource: resource, property: property, connection: connection, resource_factory: resource_factory).run
     end
 
+    # Construct the Valkyrie::Persistence::CustomQueryContainer object using this query service
+    # @return [Valkyrie::Persistence::CustomQueryContainer]
     def custom_queries
       @custom_queries ||= ::Valkyrie::Persistence::CustomQueryContainer.new(query_service: self)
     end
 
     private
 
+      # Determine whether or not a value is a Valkyrie ID
+      # @param [Object] id
+      # @return [Boolean]
       def validate_id(id)
         raise ArgumentError, 'id must be a Valkyrie::ID' unless id.is_a? Valkyrie::ID
       end
 
+      # Ensure that a given Valkyrie Resource has been persisted
+      # @param [Valkyrie::Resource] resource
       def ensure_persisted(resource)
         raise ArgumentError, 'resource is not saved' unless resource.persisted?
       end
+
+      def ordered_property?(resource:, property:)
+        resource.class.schema[property].meta.try(:[], :ordered)
+      end
   end
 end