qa 1.0.0 → 1.1.0

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

@@ -0,0 +1,186 @@
+# Provide attr_reader methods specific to term configuration for linked data authority configurations.  This is separated
+# out for readability and file length.
+# @see Qa::Authorities::LinkedData::Config
+# @see Qa::Authorities::LinkedData::SearchConfig
+module Qa::Authorities
+  module LinkedData
+    class TermConfig
+      # @param [Hash] config the term portion of the config
+      def initialize(config)
+        @term_config = 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?
+        term_config.present?
+      end
+
+      # Return term url encoding defined in the configuration for this authority.
+      # @return [Hash] the configured term url
+      def term_url
+        Config.config_value(term_config, :url)
+      end
+
+      # Return term url template defined in the configuration for this authority.
+      # @return [String] the configured term url template
+      def term_url_template
+        Config.config_value(term_url, :template)
+      end
+
+      # Return term url parameter mapping defined in the configuration for this authority.
+      # @return [Hash] the configured term url parameter mappings with variable name as key
+      def term_url_mappings
+        return @term_url_mappings unless @term_url_mappings.nil?
+        mappings = Config.config_value(term_url, :mapping)
+        return {} if mappings.nil?
+        Hash[*mappings.collect { |m| [m[:variable].to_sym, m] }.flatten]
+      end
+
+      # Is the term_id substitution expected to be a URI?
+      # @return [True|False] true if the id substitution is expected to be a URI in the term url; otherwise, false
+      def term_id_expects_uri?
+        return false if term_config.nil? || !(term_config.key? :term_id)
+        term_config[:term_id] == "URI"
+      end
+
+      # Is the term_id substitution expected to be an ID?
+      # @return [True|False] true if the id substitution is expected to be an ID in the term url; otherwise, false
+      def term_id_expects_id?
+        return false if term_config.nil? || !(term_config.key? :term_id)
+        term_config[:term_id] == "ID"
+      end
+
+      # Return the preferred language for literal value selection for term fetch.  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?
+        lang = Config.config_value(term_config, :language)
+        return nil if lang.nil?
+        lang = [lang] if lang.is_a? String
+        @term_language = lang.collect(&:to_sym)
+      end
+
+      # Return results predicates
+      # @return [Hash] all the configured predicates to pull out of the results
+      def term_results
+        Config.config_value(term_config, :results)
+      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)
+      end
+
+      # Return results label_predicate
+      # @return [String] the configured predicate to use to extract label values from the results
+      def term_results_label_predicate
+        Config.predicate_uri(term_results, :label_predicate)
+      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_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_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_predicate
+      # @return [String] the configured predicate to use to extract URIs for sameas terms from the results
+      def term_results_sameas_predicate
+        Config.predicate_uri(term_results, :sameas_predicate)
+      end
+
+      # 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)
+      end
+
+      # Are there replacement parameters configured for term fetch?
+      # @return [True|False] true if there are replacement parameters configured for term fetch; otherwise, false
+      def term_replacements?
+        term_replacement_count.positive?
+      end
+
+      # Return the number of possible replacement values to make in the term URL
+      # @return [Integer] the configured number of possible replacements in the term url
+      def term_replacement_count
+        term_replacements.size
+      end
+
+      # Return the replacement configurations
+      # @return [Hash] the configurations for term url replacements
+      def term_replacements
+        return @term_replacements unless @term_replacements.nil?
+        @term_replacements = {}
+        @term_replacements = term_url_mappings.select { |k, _v| !term_qa_replacement_patterns.include?(k) } unless term_config.nil? || term_url_mappings.nil?
+        @term_replacements
+      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
+
+      # Is a specific subauthority configured for term fetch?
+      # @return [True|False] true if the specified subauthority is configured for term fetch; otherwise, false
+      def term_subauthority?(subauth_name)
+        subauth_name = subauth_name.to_sym if subauth_name.is_a? String
+        term_subauthorities.key? subauth_name
+      end
+
+      # Return the number of subauthorities defined for term fetch
+      # @return [Integer] the number of subauthorities defined for term fetch
+      def term_subauthority_count
+        term_subauthorities.size
+      end
+
+      # Return the list of subauthorities for term fetch
+      # @return [Hash] the configurations for term url replacements
+      def term_subauthorities
+        @term_subauthorities ||= {} if term_config.nil? || !(term_config.key? :subauthorities)
+        @term_subauthorities ||= term_config[:subauthorities]
+      end
+
+      # Return the replacement configurations
+      # @return [Hash] the configurations for term url replacements
+      def term_subauthority_replacement_pattern
+        return {} unless term_subauthorities?
+        @term_subauthority_replacement_pattern ||= {} if term_config.nil? || !term_subauthorities?
+        pattern = term_qa_replacement_patterns[:subauth]
+        @term_subauthority_replacement_pattern ||= { pattern: pattern, default: term_url_mappings[pattern.to_sym][:default] }
+      end
+
+      # Build a linked data authority term url
+      # @param [String] the id
+      # @param [String] (optional) subauthority key
+      # @param [Hash] (optional) replacement values with { pattern_name (defined in YAML config) => value }
+      # @return [String] the term encoded url
+      def term_url_with_replacements(id, sub_auth = nil, replacements = {})
+        return nil unless supports_term?
+        sub_auth = sub_auth.to_sym if sub_auth.is_a? String
+        url = Config.replace_pattern(term_url_template, term_qa_replacement_patterns[:term_id], id)
+        url = Config.process_subauthority(url, term_subauthority_replacement_pattern, term_subauthorities, sub_auth) if term_subauthorities?
+        url = Config.apply_replacements(url, term_replacements, replacements) if term_replacements?
+        url
+      end
+    end
+  end
+end

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

@@ -0,0 +1,148 @@
+# This module has the primary QA find method.  It also includes methods to process the linked data result and convert
+# it into the expected QA json term result format.
+module Qa::Authorities
+  module LinkedData
+    class FindTerm
+      include Qa::Authorities::LinkedData::RdfHelper
+
+      # @param [TermConfig] term_config The term portion of the config
+      def initialize(term_config)
+        @term_config = term_config
+      end
+
+      attr_reader :term_config
+
+      delegate :term_subauthority?, to: :term_config
+
+      # Find a single term in a linked data authority
+      # @param [String] the id of the term to fetch
+      # @param [Symbol] (optional) language: language used to select literals when multi-language is supported (e.g. :en, :fr, etc.)
+      # @param [Hash] (optional) replacements: replacement values with { pattern_name (defined in YAML config) => value }
+      # @param [String] subauth: the subauthority from which to fetch the term
+      # @return [String] json results
+      # @example Json Results for Linked Data Term
+      #   { "uri":"http://id.worldcat.org/fast/530369",
+      #     "id":"530369","label":"Cornell University",
+      #     "altlabel":["Ithaca (N.Y.). Cornell University"],
+      #     "sameas":["http://id.loc.gov/authorities/names/n79021621","https://viaf.org/viaf/126293486"],
+      #     "predicates":{
+      #     "http://purl.org/dc/terms/identifier":"530369",
+      #     "http://www.w3.org/2004/02/skos/core#inScheme":["http://id.worldcat.org/fast/ontology/1.0/#fast","http://id.worldcat.org/fast/ontology/1.0/#facet-Corporate"],
+      #     "http://www.w3.org/1999/02/22-rdf-syntax-ns#type":"http://schema.org/Organization",
+      #     "http://www.w3.org/2004/02/skos/core#prefLabel":"Cornell University",
+      #     "http://schema.org/name":["Cornell University","Ithaca (N.Y.). Cornell University"],
+      #     "http://www.w3.org/2004/02/skos/core#altLabel":["Ithaca (N.Y.). Cornell University"],
+      #     "http://schema.org/sameAs":["http://id.loc.gov/authorities/names/n79021621","https://viaf.org/viaf/126293486"] } }
+      def find(id, language: nil, replacements: {}, subauth: nil)
+        raise Qa::InvalidLinkedDataAuthority, "Unable to initialize linked data term sub-authority #{subauth}" unless subauth.nil? || term_subauthority?(subauth)
+        language ||= term_config.term_language
+        url = term_config.term_url_with_replacements(id, subauth, replacements)
+        Rails.logger.info "QA Linked Data term url: #{url}"
+        graph = get_linked_data(url)
+        return "{}" unless graph.size.positive?
+        parse_term_authority_response(id, graph, language)
+      end
+
+      private
+
+        def parse_term_authority_response(id, graph, language)
+          graph = filter_language(graph, language) unless language.nil?
+          results = extract_preds(graph, preds_for_term)
+          consolidated_results = consolidate_term_results(results)
+          json_results = convert_term_to_json(consolidated_results)
+          termhash = select_json_result_for_id(json_results, id)
+          predicates_hash = predicates_with_subject_uri(graph, termhash[:uri])
+          termhash['predicates'] = predicates_hash unless predicates_hash.length <= 0
+          termhash
+        end
+
+        def preds_for_term
+          { required: required_term_preds, optional: optional_term_preds }
+        end
+
+        def required_term_preds
+          label_pred_uri = term_config.term_results_label_predicate
+          raise Qa::InvalidConfiguration, "required label_predicate is missing in configuration for LOD authority #{auth_name}" if label_pred_uri.nil?
+          { label: label_pred_uri }
+        end
+
+        def optional_term_preds
+          preds = {}
+          preds[:altlabel] = term_config.term_results_altlabel_predicate unless term_config.term_results_altlabel_predicate.nil?
+          preds[:id] = term_config.term_results_id_predicate unless term_config.term_results_id_predicate.nil?
+          preds[:narrower] = term_config.term_results_narrower_predicate unless term_config.term_results_narrower_predicate.nil?
+          preds[:broader] = term_config.term_results_broader_predicate unless term_config.term_results_broader_predicate.nil?
+          preds[:sameas] = term_config.term_results_sameas_predicate unless term_config.term_results_sameas_predicate.nil?
+          preds
+        end
+
+        def consolidate_term_results(results)
+          consolidated_results = {}
+          results.each do |statement|
+            stmt_hash = statement.to_h
+            uri = stmt_hash[:uri].to_s
+            consolidated_hash = init_consolidated_hash(consolidated_results, uri, stmt_hash[:id].to_s)
+
+            consolidated_hash[:label] = object_value(stmt_hash, consolidated_hash, :label, false)
+            altlabel = object_value(stmt_hash, consolidated_hash, :altlabel, false)
+            narrower = object_value(stmt_hash, consolidated_hash, :narrower)
+            broader = object_value(stmt_hash, consolidated_hash, :broader)
+            sameas = object_value(stmt_hash, consolidated_hash, :sameas)
+
+            consolidated_hash[:altlabel] = altlabel unless altlabel.nil?
+            consolidated_hash[:narrower] = narrower unless narrower.nil?
+            consolidated_hash[:broader] = broader unless broader.nil?
+            consolidated_hash[:sameas] = sameas unless sameas.nil?
+            consolidated_results[uri] = consolidated_hash
+          end
+          consolidated_results.each do |res|
+            consolidated_hash = res[1]
+            consolidated_hash[:label] = sort_string_by_language consolidated_hash[:label]
+            consolidated_hash[:altlabel] = sort_string_by_language consolidated_hash[:altlabel]
+            consolidated_hash[:sort] = sort_string_by_language consolidated_hash[:sort]
+          end
+          consolidated_results
+        end
+
+        def convert_term_to_json(consolidated_results)
+          json_results = []
+          consolidated_results.each do |uri, h|
+            json_hash = { uri: uri, id: h[:id], label: h[:label] }
+            json_hash[:altlabel] = h[:altlabel] unless h[:altlabel].nil?
+            json_hash[:narrower] = h[:narrower] unless h[:narrower].nil?
+            json_hash[:broader] = h[:broader] unless h[:broader].nil?
+            json_hash[:sameas] = h[:sameas] unless h[:sameas].nil?
+            json_results << json_hash
+          end
+          json_results
+        end
+
+        def select_json_result_for_id(json_results, id)
+          json_results.select! { |r| r[:uri].include? id } if json_results.size > 1
+          json_results.select! { |r| r[:uri].ends_with? id } if json_results.size > 1
+          json_results.first
+        end
+
+        def predicates_with_subject_uri(graph, expected_uri)
+          predicates_hash = {}
+          graph.statements.each do |st|
+            subj = st.subject.to_s
+            next unless subj == expected_uri
+            pred = st.predicate.to_s
+            obj  = st.object.to_s
+            next if blank_node? obj
+            if predicates_hash.key?(pred)
+              objs = predicates_hash[pred]
+              objs = [] unless objs.is_a?(Array)
+              objs << predicates_hash[pred] unless objs.length.positive?
+              objs << obj
+              predicates_hash[pred] = objs
+            else
+              predicates_hash[pred] = [obj]
+            end
+          end
+          predicates_hash
+        end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module Qa::Authorities
+  module LinkedData
+    # A wrapper around configured linked data authorities for use with questioning_authority.  The search and find methods
+    # can be called directly from an instance of this class.  The Qa::LinkedDataTermsController uses these methods to provide
+    # a URL based API for searching and term retrieval.
+    #
+    # @see Qa::Authorities::LinkedData::SearchQuery#search
+    # @see Qa::Authorities::LinkedData::FindTerm#find
+    # @see Qa::LinkedDataTermsController#search
+    # @see Qa::LinkedDataTermsController#show
+    # @see Qa::Authorities::LinkedData::Config
+    class GenericAuthority < Base
+      attr_reader :auth_config
+
+      delegate :supports_term?, :term_subauthorities?, :term_subauthority?,
+               :term_id_expects_uri?, :term_id_expects_id?, to: :term_config
+
+      delegate :supports_search?, to: :search_config
+      delegate :subauthority?, :subauthorities?, to: :search_config, prefix: 'search'
+
+      def initialize(auth_name)
+        @auth_config = Qa::Authorities::LinkedData::Config.new(auth_name)
+      end
+
+      include WebServiceBase
+
+      def search_service
+        @search_service ||= Qa::Authorities::LinkedData::SearchQuery.new(search_config)
+      end
+
+      def item_service
+        @item_service ||= Qa::Authorities::LinkedData::FindTerm.new(term_config)
+      end
+
+      delegate :search, to: :search_service
+      delegate :find, to: :item_service
+
+      private
+
+        def search_config
+          auth_config.search
+        end
+
+        def term_config
+          auth_config.term
+        end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+require 'rdf'
+
+# Encapsulates processing of RDF results returned by the linked data authority.  This is used exclussively by Qa::Authorities::LinkedData::GenericAuthority
+# @see Qa::Authorities::LinkedData::GenericAuthority
+module Qa::Authorities
+  module LinkedData
+    module RdfHelper
+      private
+
+        def object_value(stmt_hash, consolidated_hash, name, as_string = true)
+          new_object_value = stmt_hash[name]
+          new_object_value = new_object_value.to_s if as_string
+          all_object_values = consolidated_hash[name] || []
+          all_object_values << new_object_value unless new_object_value.nil? || all_object_values.include?(new_object_value)
+          all_object_values
+        end
+
+        def init_consolidated_hash(consolidated_results, uri, id)
+          consolidated_hash = consolidated_results[uri] || {}
+          if consolidated_hash.empty?
+            consolidated_hash[:id] = uri
+            consolidated_hash[:id] = id unless id.nil? || id.length <= 0
+          end
+          consolidated_hash
+        end
+
+        def get_linked_data(url)
+          begin
+            graph = RDF::Graph.load(url)
+          rescue IOError => e
+            process_error(e, url)
+          end
+          graph
+        end
+
+        def process_error(e, url)
+          uri = URI(url)
+          response_code = ioerror_code(e)
+          case response_code
+          when 'format'
+            raise RDF::FormatError, "Unknown RDF format of results returned by #{uri}. (RDF::FormatError)  You may need to include gem 'linkeddata'."
+          when '404'
+            raise Qa::TermNotFound, "#{uri} Not Found - Term may not exist at LOD Authority. (HTTPNotFound - 404)"
+          when '500'
+            raise Qa::ServiceUnavailable, "#{uri.hostname} on port #{uri.port} is not responding.  Try again later. (HTTPServerError - 500)"
+          when '503'
+            raise Qa::ServiceUnavailable, "#{uri.hostname} on port #{uri.port} is not responding.  Try again later. (HTTPServiceUnavailable - 503)"
+          else
+            raise Qa::ServiceUnavailable, "Unknown error for #{uri.hostname} on port #{uri.port}.  Try again later. (Cause - #{e.message})"
+          end
+        end
+
+        def ioerror_code(e)
+          msg = e.message
+          return 'format' if msg.start_with? "Unknown RDF format"
+          a = msg.size - 4
+          z = msg.size - 2
+          msg[a..z]
+        end
+
+        def filter_language(graph, language)
+          language = normalize_language(language)
+          return graph if language.nil?
+          graph.each do |st|
+            graph.delete(st) unless !st.object.respond_to?(:language) || st.object.language.nil? || language.include?(st.object.language)
+          end
+          graph
+        end
+
+        def normalize_language(language)
+          language = [language.to_sym] if language.is_a? String
+          language = [language] if language.is_a? Symbol
+          return nil unless language.is_a? Array
+          language
+        end
+
+        def extract_preds(graph, preds)
+          RDF::Query.execute(graph) do
+            preds[:required].each do |key, pred|
+              pattern([:uri, pred, key])
+            end
+            preds[:optional].each do |key, pred|
+              pattern([:uri, pred, key], optional: true)
+            end
+          end
+        end
+
+        def sort_string_by_language(str_literals)
+          return str_literals if str_literals.nil? || str_literals.size <= 0
+          str_literals.sort! { |a, b| a.language <=> b.language }
+          str_literals.collect!(&:to_s)
+          str_literals.uniq!
+          str_literals.delete_if { |s| s.nil? || s.length <= 0 }
+        end
+
+        def blank_node?(obj)
+          return true if obj.to_s.starts_with? "_:g"
+          false
+        end
+    end
+  end
+end