qa 4.0.0 → 4.1.0

data/lib/qa/authorities/discogs/generic_authority.rb

@@ -0,0 +1,151 @@
+require 'rdf'
+module Qa::Authorities
+  class Discogs::GenericAuthority < Base
+    include WebServiceBase
+    include Discogs::DiscogsTranslation
+
+    class_attribute :discogs_secret, :discogs_key
+    attr_accessor :primary_artists
+
+    # @param [String] subauthority to use
+    def initialize(subauthority)
+      @subauthority = subauthority
+      self.primary_artists = []
+    end
+
+    # @param [String] the query
+    # @param [Class] QA::TermsController
+    # @return json results
+    def search(q, tc)
+      # Discogs distinguishes between masters and releases, where a release represents a specific
+      # physical or digital object and a master represents a set of similar releases. Use of a
+      # subauthority (e.g., /qa/search/discogs/master) will target a specific type. Using the "all"
+      #  subauthority will search for both types.
+      unless discogs_key && discogs_secret
+        Rails.logger.error "Questioning Authority tried to call Discogs, but no secret and/or key were set."
+        return []
+      end
+      parse_authority_response(json(build_query_url(q, tc.params["subauthority"])))
+    end
+
+    # If the subauthority = "all" (though it shouldn't), call the fetch_discogs_results method to determine
+    # whether the id matches a release or master. And if the requested format is json-ld, call the build_graph
+    # method in the translation module; otherwise, just return the Discogs json.  check the response to
+    # determine if it should go to the translation module.
+    #
+    # @param [String] the Discogs id of the selected item
+    # @param [Class] QA::TermsController
+    # @return either json results or jsonld
+    def find(id, tc)
+      response = tc.params["subauthority"].include?("all") ? fetch_discogs_results(id) : json(find_url(id, tc.params["subauthority"]))
+      return build_graph(response) unless tc.params["format"] != "jsonld" || response["message"].present?
+      response
+    end
+
+    # @param [String] the query
+    # @param [String] the subauthority
+    # @return [String] the url
+    def build_query_url(q, subauthority)
+      escaped_q = ERB::Util.url_encode(q)
+      "https://api.discogs.com/database/search?q=#{escaped_q}&type=#{subauthority}&key=#{discogs_key}&secret=#{discogs_secret}"
+    end
+
+    # @param [String] the id of the selected item
+    # @param [String] the subauthority
+    # @return [String] the url
+    def find_url(id, subauthority)
+      "https://api.discogs.com/#{subauthority}s/#{id}"
+    end
+
+    private
+
+      # In the unusual case that we have an id and the subauthority is "all", we don't know which Discogs url to
+      # use. If the id is a match for both a release and a master (or neither), return that info as the
+      # message. Otherwise, return the data for the release or master.
+      # @param [String] the id of the selected item
+      # @return json results
+      def fetch_discogs_results(id)
+        release_resp = json(find_url(id, "release"))
+        master_resp = json(find_url(id, "master"))
+        message_status = check_for_msg_response(release_resp, master_resp)
+
+        return { "message" => "Neither a master nor a release matches the requested ID." } if message_status == "no responses"
+        if message_status == "two responses"
+          return { "message" => "Both a master and a release match the requested ID.",
+                   "resource_url" => ["https://api.discogs.com/masters/#{id}", "https://api.discogs.com/releases/#{id}"] }
+        end
+        return master_resp unless master_resp.key?("message")
+        # return release_resp unless release_resp.key?("message")
+        release_resp
+      end
+
+      # @param json results
+      # @param json results
+      # @return [String] status information
+      def check_for_msg_response(release_resp, master_resp)
+        if release_resp.key?("message") && master_resp.key?("message")
+          "no responses"
+        elsif !release_resp.key?("message") && !master_resp.key?("message")
+          "two responses"
+        else
+          "mixed"
+        end
+      end
+
+      # @param [Hash] the http response from discogs
+      # @example returns parsed discogs data with context
+      # {
+      #   "uri": "https://api.discogs.com/releases/4212473",
+      #   "id": "4212473",
+      #   "label": "Frank Sinatra And The Modernaires - Sorry / Why Remind Me",
+      # }
+      #   "context": {
+      #     "Image URL": [
+      #       "https://img.discogs.com/2e-YoNr0dvmMgbzEN0hjHD6X0sU=/fit-in/600x580/filters:strip_icc():format(jpeg):mode_rgb():quality(90)/discogs-images/R-4212473-1358693671-5430.jpeg.jpg"
+      #     ],
+      #     "Year": [
+      #       "1950"
+      #     ],
+      #     "Record Labels": [
+      #       "Columbia"
+      #     ],
+      #     "Formats": [
+      #       "Shellac",
+      #       "10\"",
+      #       "78 RPM"
+      #     ],
+      #     "Type": [
+      #       "release"
+      #     ]
+      #   }
+      def parse_authority_response(response)
+        response['results'].map do |result|
+          { 'uri' => result['resource_url'].to_s,
+            'id' => result['id'].to_s,
+            'label' => result['title'].to_s,
+            'context' => assemble_search_context(result) }
+        end
+      end
+
+      # @param [Hash] the results hash from the JSON returned by Discogs
+      def assemble_search_context(result)
+        { "Image URL" => get_context_for_string(result['cover_image']),
+          "Year" =>  get_context_for_string(result['year']),
+          "Record Labels" => get_context_for_array(result['label']),
+          "Formats" => get_context_for_array(result['format']),
+          "Type" => get_context_for_string(result['type']) }
+      end
+
+      # checks if the param is null, returns appropriate value
+      # @param [String] returns an empty string if item is not presentr
+      def get_context_for_string(item)
+        [item.present? ? item.to_s : ""]
+      end
+
+      # checks if the param is null, returns appropriate value
+      # @param [Array] returns an empty array if item is not presentr
+      def get_context_for_array(item)
+        item.present? ? item : [""]
+      end
+  end
+end

data/lib/qa/authorities/discogs_subauthority.rb

@@ -0,0 +1,9 @@
+module Qa::Authorities::DiscogsSubauthority
+  def authorities
+    [
+      "master",
+      "release",
+      "all"
+    ]
+  end
+end

data/lib/qa/authorities/linked_data/config.rb

@@ -28,11 +28,11 @@ module Qa::Authorities
       end
 
       def search
-        @search ||= Qa::Authorities::LinkedData::SearchConfig.new(authority_config.fetch(:search), prefixes)
+        @search ||= Qa::Authorities::LinkedData::SearchConfig.new(authority_config.fetch(:search), prefixes, self)
       end
 
       def term
-        @term ||= Qa::Authorities::LinkedData::TermConfig.new(authority_config.fetch(:term), prefixes)
+        @term ||= Qa::Authorities::LinkedData::TermConfig.new(authority_config.fetch(:term), prefixes, self)
       end
 
       def prefixes
@@ -47,6 +47,10 @@ module Qa::Authorities
         config_version == version
       end
 
+      def authority_info
+        search.info + term.info
+      end
+
       # Return the full configuration for an authority
       # @return [String] the authority configuration
       def authority_config
@@ -79,7 +83,7 @@ module Qa::Authorities
         def convert_1_0_url_to_2_0_url(action_key)
           url_template = @authority_config.fetch(action_key, {}).fetch(:url, {}).fetch(:template, "")
           return if url_template.blank?
-          warn "[DEPRECATED] #Linked data configuration #{authority_name} has 1.0 version format which is deprecated; update to version 2.0 configuration."
+          Qa.deprecation_warning(msg: "Linked data configuration #{authority_name} has 1.0 version format which is deprecated; update to version 2.0 configuration.")
           @authority_config[action_key][:url][:template] = url_template.gsub("{?", "{")
         end
     end

data/lib/qa/authorities/linked_data/config/search_config.rb

@@ -4,18 +4,21 @@
 # @see Qa::Authorities::LinkedData::TermConfig
 module Qa::Authorities
   module LinkedData
-    class SearchConfig
-      attr_reader :prefixes
+    class SearchConfig # rubocop:disable Metrics/ClassLength
+      attr_reader :prefixes, :full_config, :search_config
+      private :full_config, :search_config
+
+      delegate :authority_name, to: :full_config
 
       # @param [Hash] config the search portion of the config
-      def initialize(config, prefixes = {})
+      # @param [Hash<Symbol><String>] prefixes URL map of prefixes to use with ldpaths
+      # @param [Qa::Authorities::LinkedData::Config] full_config the full linked data configuration that the passed in search config is part of
+      def initialize(config, prefixes = {}, full_config = nil)
         @search_config = config
         @prefixes = prefixes
+        @full_config = full_config
       end
 
-      attr_reader :search_config
-      private :search_config
-
       # Does this authority configuration have search defined?
       # @return [Boolean] true if search is configured; otherwise, false
       def supports_search?
@@ -29,6 +32,7 @@ module Qa::Authorities
       end
 
       # Return the preferred language for literal value selection for search query.
+      # This is the default used for this authority if the user does not pass in a language.
       # Only applies if the authority provides language encoded literals.
       # @return [String] the configured language for search query
       def language
@@ -39,40 +43,80 @@ module Qa::Authorities
         @language = lang.collect(&:to_sym)
       end
 
-      # Return results predicates if specified
-      # @return [Hash,NilClass] all the configured predicates to pull out of the results
+      # Return results ldpaths or predicates if specified
+      # @return [Hash,NilClass] all the configured ldpaths or predicates to pull out of the results
       def results
         search_config[:results]
       end
 
+      # Return results id_ldpath
+      # @return [String] the configured ldpath to use to extract the id from the results
+      def results_id_ldpath
+        Config.config_value(results, :id_ldpath)
+      end
+
       # Return results id_predicate
       # @return [String] the configured predicate to use to extract the id from the results
       def results_id_predicate
+        Qa.deprecation_warning(
+          in_msg: 'Qa::Authorities::LinkedData::SearchConfig',
+          msg: "`results_id_predicate` is deprecated; use `results_id_ldpath` by updating linked data search config results to specify as `id_ldpath`"
+        )
         Config.predicate_uri(results, :id_predicate)
       end
 
+      # Return results label_ldpath
+      # @return [String] the configured ldpath to use to extract label values from the results
+      def results_label_ldpath
+        Config.config_value(results, :label_ldpath)
+      end
+
       # Return results label_predicate
       # @return [String] the configured predicate to use to extract label values from the results
       def results_label_predicate
+        Qa.deprecation_warning(
+          in_msg: 'Qa::Authorities::LinkedData::SearchConfig',
+          msg: "`results_label_predicate` is deprecated; use `results_label_ldpath` by updating linked data search config results to specify as `label_ldpath`"
+        )
         Config.predicate_uri(results, :label_predicate)
       end
 
+      # Return results altlabel_ldpath
+      # @return [String] the configured ldpath to use to extract altlabel values from the results
+      def results_altlabel_ldpath
+        Config.config_value(results, :altlabel_ldpath)
+      end
+
       # Return results altlabel_predicate
       # @return [String] the configured predicate to use to extract altlabel values from the results
       def results_altlabel_predicate
+        Qa.deprecation_warning(
+          in_msg: 'Qa::Authorities::LinkedData::SearchConfig',
+          msg: "`results_altlabel_predicate` is deprecated; use `results_altlabel_ldpath` by updating linked data search config results to specify as `altlabel_ldpath`"
+        )
         Config.predicate_uri(results, :altlabel_predicate)
       end
 
       # Does this authority configuration support sorting of search results?
       # @return [True|False] true if sorting of search results is supported; otherwise, false
       def supports_sort?
-        return true unless results_sort_predicate.nil? || !results_sort_predicate.size.positive?
+        return true unless results_sort_ldpath.present? || !results_sort_predicate.present?
         false
       end
 
+      # Return results sort_ldpath
+      # @return [String] the configured ldpath to use for sorting results from the query search
+      def results_sort_ldpath
+        Config.config_value(results, :sort_ldpath)
+      end
+
       # Return results sort_predicate
       # @return [String] the configured predicate to use for sorting results from the query search
       def results_sort_predicate
+        Qa.deprecation_warning(
+          in_msg: 'Qa::Authorities::LinkedData::SearchConfig',
+          msg: "`results_sort_predicate` is deprecated; use `results_sort_ldpath` by updating linked data search config results to specify as `sort_ldpath`"
+        )
         Config.predicate_uri(results, :sort_predicate)
       end
 
@@ -90,10 +134,20 @@ module Qa::Authorities
         @context_map ||= Qa::LinkedData::Config::ContextMap.new(search_config.fetch(:context), prefixes)
       end
 
-      # Return parameters that are required for QA api
+      # Return parameters that are supported directly by QA api (e.g. q, subauth, lang)
       # @return [Hash] the configured search url parameter mappings
       def qa_replacement_patterns
-        search_config.fetch(:qa_replacement_patterns)
+        search_config.fetch(:qa_replacement_patterns, {})
+      end
+
+      # @return [Boolean] true if supports language parameter; otherwise, false
+      def supports_subauthorities?
+        qa_replacement_patterns.key?(:subauth) && subauthorities?
+      end
+
+      # @return [Boolean] true if supports language parameter; otherwise, false
+      def supports_language_parameter?
+        qa_replacement_patterns.key? :lang
       end
 
       # Are there subauthorities configured for search query?
@@ -121,6 +175,40 @@ module Qa::Authorities
         @subauthorities ||= {} if search_config.nil? || !(search_config.key? :subauthorities)
         @subauthorities ||= search_config.fetch(:subauthorities)
       end
+
+      def info
+        return [] unless supports_search?
+        auth_name = authority_name.downcase.to_s
+        language = Qa::LinkedData::LanguageService.preferred_language(authority_language: language).map(&:to_s)
+        details = summary_without_subauthority(auth_name, language)
+        subauthorities.each_key { |subauth_name| details << summary_with_subauthority(auth_name, subauth_name.downcase.to_s, language) }
+        details
+      end
+
+      private
+
+        def summary_without_subauthority(auth_name, language)
+          [
+            {
+              "label" => "#{auth_name} search (QA)",
+              "uri" => "urn:qa:search:#{auth_name}",
+              "authority" => auth_name,
+              "action" => "search",
+              "language" => language
+            }
+          ]
+        end
+
+        def summary_with_subauthority(auth_name, subauth_name, language)
+          {
+            "label" => "#{auth_name} search #{subauth_name} (QA)",
+            "uri" => "urn:qa:search:#{auth_name}:#{subauth_name}",
+            "authority" => auth_name,
+            "subauthority" => subauth_name,
+            "action" => "search",
+            "language" => language
+          }
+        end
     end
   end
 end

data/lib/qa/authorities/linked_data/config/term_config.rb

@@ -5,15 +5,20 @@
 module Qa::Authorities
   module LinkedData
     class TermConfig
+      attr_reader :prefixes, :full_config, :term_config
+      private :full_config, :term_config
+
+      delegate :authority_name, to: :full_config
+
       # @param [Hash] config the term portion of the config
-      def initialize(config, prefixes = {})
+      # @param [Hash<Symbol><String>] prefixes URL map of prefixes to use with ldpaths
+      # @param [Qa::Authorities::LinkedData::Config] full_config the full linked data configuration that the passed in search config is part of
+      def initialize(config, prefixes = {}, full_config = nil)
         @term_config = config
         @prefixes = prefixes
+        @full_config = full_config
       end
 
-      attr_reader :term_config
-      private :term_config
-
       # Does this authority configuration have term defined?
       # @return [True|False] true if term fetching is configured; otherwise, false
       def supports_term?
@@ -41,6 +46,8 @@ module Qa::Authorities
       end
 
       # Return the preferred language for literal value selection for term fetch.  Only applies if the authority provides language encoded literals.
+      # This is the default used for this authority if the user does not pass in a language.
+      # Only applies if the authority provides language encoded literals.
       # @return [Symbol] the configured language for term fetch (default - :en)
       def term_language
         return @term_language unless @term_language.nil?
@@ -49,17 +56,33 @@ module Qa::Authorities
         lang = [lang] if lang.is_a? String
         @term_language = lang.collect(&:to_sym)
       end
+      alias language term_language
 
-      # Return results predicates
-      # @return [Hash] all the configured predicates to pull out of the results
+      # Return results ldpaths or predicates
+      # @return [Hash] all the configured ldpaths or predicates to pull out of the results
       def term_results
         Config.config_value(term_config, :results)
       end
 
+      # Return results id_ldpath
+      # @return [String] the configured ldpath to use to extract the id from the results
+      def term_results_id_ldpath
+        Config.config_value(term_results, :id_ldpath)
+      end
+
       # Return results id_predicate
       # @return [String] the configured predicate to use to extract the id from the results
       def term_results_id_predicate
-        Config.predicate_uri(term_results, :id_predicate)
+        return @pred_id unless @pred_id.blank?
+        @pred_id = Config.predicate_uri(term_results, :id_predicate)
+        return @pred_id unless @pred_id.blank?
+        @pred_id = pred_id_from_ldpath
+      end
+
+      # Return results label_ldpath
+      # @return [String] the configured ldpath to use to extract label values from the results
+      def term_results_label_ldpath
+        Config.config_value(term_results, :label_ldpath)
       end
 
       # Return results label_predicate
@@ -68,24 +91,48 @@ module Qa::Authorities
         Config.predicate_uri(term_results, :label_predicate)
       end
 
+      # Return results altlabel_ldpath
+      # @return [String] the configured ldpath to use to extract altlabel values from the results
+      def term_results_altlabel_ldpath
+        Config.config_value(term_results, :altlabel_ldpath)
+      end
+
       # Return results altlabel_predicate
       # @return [String] the configured predicate to use to extract altlabel values from the results
       def term_results_altlabel_predicate
         Config.predicate_uri(term_results, :altlabel_predicate)
       end
 
+      # Return results broader_ldpath
+      # @return [String] the configured ldpath to use to extract URIs for broader terms from the results
+      def term_results_broader_ldpath
+        Config.config_value(term_results, :broader_ldpath)
+      end
+
       # Return results broader_predicate
       # @return [String] the configured predicate to use to extract URIs for broader terms from the results
       def term_results_broader_predicate
         Config.predicate_uri(term_results, :broader_predicate)
       end
 
+      # Return results narrower_ldpath
+      # @return [String] the configured ldpath to use to extract URIs for narrower terms from the results
+      def term_results_narrower_ldpath
+        Config.config_value(term_results, :narrower_ldpath)
+      end
+
       # Return results narrower_predicate
       # @return [String] the configured predicate to use to extract URIs for narrower terms from the results
       def term_results_narrower_predicate
         Config.predicate_uri(term_results, :narrower_predicate)
       end
 
+      # Return results sameas_ldpath
+      # @return [String] the configured ldpath to use to extract URIs for sameas terms from the results
+      def term_results_sameas_ldpath
+        Config.config_value(term_results, :sameas_ldpath)
+      end
+
       # Return results sameas_predicate
       # @return [String] the configured predicate to use to extract URIs for sameas terms from the results
       def term_results_sameas_predicate
@@ -95,15 +142,26 @@ module Qa::Authorities
       # Return parameters that are required for QA api
       # @return [Hash] the configured term url parameter mappings
       def term_qa_replacement_patterns
-        Config.config_value(term_config, :qa_replacement_patterns)
+        term_config.fetch(:qa_replacement_patterns, {})
       end
       alias qa_replacement_patterns term_qa_replacement_patterns
 
+      # @return [Boolean] true if supports language parameter; otherwise, false
+      def supports_subauthorities?
+        qa_replacement_patterns.key?(:subauth) && subauthorities?
+      end
+
+      # @return [Boolean] true if supports language parameter; otherwise, false
+      def supports_language_parameter?
+        qa_replacement_patterns.key? :lang
+      end
+
       # Are there subauthorities configured for term fetch?
       # @return [True|False] true if there are subauthorities configured term fetch; otherwise, false
       def term_subauthorities?
         term_subauthority_count.positive?
       end
+      alias subauthorities? term_subauthorities?
 
       # Is a specific subauthority configured for term fetch?
       # @return [True|False] true if the specified subauthority is configured for term fetch; otherwise, false
@@ -125,6 +183,52 @@ module Qa::Authorities
         @term_subauthorities ||= term_config[:subauthorities]
       end
       alias subauthorities term_subauthorities
+
+      def info
+        return [] unless supports_term?
+        auth_name = authority_name.downcase.to_s
+        language = Qa::LinkedData::LanguageService.preferred_language(authority_language: language).map(&:to_s)
+        details = summary_without_subauthority(auth_name, language)
+        subauthorities.keys { |subauth_name| details << summary_with_subauthority(auth_name, subauth_name.downcase.to_s, language) }
+        details
+      end
+
+      private
+
+        def pred_id_from_ldpath
+          # prefix example: { skos: 'http://www.w3.org/2004/02/skos/core#' }
+          # ldpath example: 'skos:id :: xsd:string'
+          id_ldpath = term_results_id_ldpath
+          return nil if id_ldpath.blank?
+          tokens = id_ldpath.split(':')
+          return nil if tokens.size < 2
+          prefix = tokens.first.to_sym
+          prefix_path = prefixes[prefix]
+          prefix_path + tokens.second.strip
+        end
+
+        def summary_without_subauthority(auth_name, language)
+          [
+            {
+              "label" => "#{auth_name} term (QA)",
+              "uri" => "urn:qa:term:#{auth_name}",
+              "authority" => auth_name,
+              "action" => "term",
+              "language" => language
+            }
+          ]
+        end
+
+        def summary_with_subauthority(auth_name, subauth_name, language)
+          {
+            "label" => "#{auth_name} term #{subauth_name} (QA)",
+            "uri" => "urn:qa:term:#{auth_name}:#{subauth_name}",
+            "authority" => auth_name,
+            "subauthority" => subauth_name,
+            "action" => "term",
+            "language" => language
+          }
+        end
     end
   end
 end