qa 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ab8962fbfa1793451a7cc2d54cb7dfac7b78888c
-  data.tar.gz: 05aa5d8b96b64e9de68996ab84a00e3e79ab4d8c
+  metadata.gz: f8ae75788063293cff50f32548b9eccbd6d0c837
+  data.tar.gz: 3aad18f6f86d31d4e8a13941407c8890d1389a21
 SHA512:
-  metadata.gz: 0c3c034f33d2cfb2c1f1062eac7423d05c2dcca1bc23106a2c14d7f62e39b83c7c8592c07685673cda14e0c58ab734666d4185a8be55ab2266218421ce051e29
-  data.tar.gz: 3e139a9edf37c8b5fe9a12a37a8e2e79a507943ef41d502c3b6c56afbfa4eadbb9fe2aa2dbe6ba3079a47b2b4c365f942078fa86b13561d877fb6acdb8b524c2
+  metadata.gz: 4c1bd3ffc5d4d6d663fa656cebc9400f390a393862c3d68c454866f42f50f803236f64cd97dc3c0a63e5e895e2ca575b2f32b5d9e5372c6fe572bf08b1484397
+  data.tar.gz: 761ef1f50ecdfdc425a8deb49b3672508955725aa3339514c517b8bbc0cd6d1285b689adde5d35e2e3aa877e659ead79492c6ad6d82de345bd6c3cb230245f93

data/README.md

@@ -2,7 +2,7 @@
 
 Code:
 [![Gem Version](https://badge.fury.io/rb/qa.png)](http://badge.fury.io/rb/qa)
-[![Build Status](https://travis-ci.org/samvera/questioning_authority.png?branch=master)](https://travis-ci.org/samvera/questioning_authority)
+[![Build Status](https://circleci.com/gh/samvera/questioning_authority.svg?style=svg)](https://circleci.com/gh/samvera/questioning_authority)
 [![Coverage Status](https://coveralls.io/repos/github/samvera/questioning_authority/badge.svg?branch=master)](https://coveralls.io/github/samvera/questioning_authority?branch=master)
 
 Docs:

data/app/controllers/qa/linked_data_terms_controller.rb

@@ -16,11 +16,12 @@ class Qa::LinkedDataTermsController < ::ApplicationController
     head :not_found
   end
 
-  # Return a list of supported authority names
-  # get "/list/linked_data/authorities"
+  # Return a list of supported authority names optionally with details about the authority
+  # get "/list/linked_data/authorities?details=true|false" (default details=false)
   # @see Qa::LinkedData::AuthorityService#authority_names
+  # @see Qa::LinkedData::AuthorityService#authority_details
   def list
-    render json: Qa::LinkedData::AuthorityService.authority_names.to_json
+    details? ? render_detail_list : render_simple_list
   end
 
   # Reload authority configurations
@@ -34,8 +35,8 @@ class Qa::LinkedDataTermsController < ::ApplicationController
   # Return a list of terms based on a query
   # get "/search/linked_data/:vocab(/:subauthority)"
   # @see Qa::Authorities::LinkedData::SearchQuery#search
-  def search # rubocop:disable Metrics/MethodLength
-    terms = @authority.search(query, subauth: subauthority, language: language, replacements: replacement_params, context: context?)
+  def search # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    terms = @authority.search(query, subauth: subauthority, language: language, replacements: replacement_params, context: context?, performance_data: performance_data?)
     cors_allow_origin_header(response)
     render json: terms
   rescue Qa::ServiceUnavailable
@@ -58,7 +59,7 @@ class Qa::LinkedDataTermsController < ::ApplicationController
   # get "/show/linked_data/:vocab/:subauthority/:id
   # @see Qa::Authorities::LinkedData::FindTerm#find
   def show # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-    term = @authority.find(id, subauth: subauthority, language: language, replacements: replacement_params, jsonld: jsonld?)
+    term = @authority.find(id, subauth: subauthority, language: language, replacements: replacement_params, jsonld: jsonld?, performance_data: performance_data?)
     cors_allow_origin_header(response)
     content_type = jsonld? ? 'application/ld+json' : 'application/json'
     render json: term, content_type: content_type
@@ -85,7 +86,7 @@ class Qa::LinkedDataTermsController < ::ApplicationController
   # get "/fetch/linked_data/:vocab"
   # @see Qa::Authorities::LinkedData::FindTerm#find
   def fetch # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-    term = @authority.find(uri, subauth: subauthority, language: language, replacements: replacement_params, jsonld: jsonld?)
+    term = @authority.find(uri, subauth: subauthority, language: language, replacements: replacement_params, jsonld: jsonld?, performance_data: performance_data?)
     cors_allow_origin_header(response)
     content_type = jsonld? ? 'application/ld+json' : 'application/json'
     render json: term, content_type: content_type
@@ -110,6 +111,14 @@ class Qa::LinkedDataTermsController < ::ApplicationController
 
   private
 
+    def render_simple_list
+      render json: Qa::LinkedData::AuthorityService.authority_names.to_json
+    end
+
+    def render_detail_list
+      render json: Qa::LinkedData::AuthorityService.authority_details.to_json
+    end
+
     def check_authority
       if params[:vocab].nil? || !params[:vocab].size.positive? # rubocop:disable Style/GuardClause
         msg = "Required param 'vocab' is missing or empty"
@@ -180,7 +189,9 @@ class Qa::LinkedDataTermsController < ::ApplicationController
     end
 
     def language
-      params[:lang]
+      request_language = request.env['HTTP_ACCEPT_LANGUAGE']
+      request_language = request_language.scan(/^[a-z]{2}/).first if request_language.present?
+      params[:lang] || request_language
     end
 
     def subauthority
@@ -188,7 +199,7 @@ class Qa::LinkedDataTermsController < ::ApplicationController
     end
 
     def replacement_params
-      params.reject { |k, _v| ['q', 'vocab', 'controller', 'action', 'subauthority', 'language', 'id'].include?(k) }
+      params.reject { |k, _v| ['q', 'vocab', 'controller', 'action', 'subauthority', 'lang', 'id'].include?(k) }
     end
 
     def subauth_warn_msg
@@ -210,6 +221,16 @@ class Qa::LinkedDataTermsController < ::ApplicationController
       context.casecmp('true').zero?
     end
 
+    def details?
+      details = params.fetch(:details, 'false')
+      details.casecmp('true').zero?
+    end
+
+    def performance_data?
+      performance_data = params.fetch(:performance_data, 'false')
+      performance_data.casecmp('true').zero?
+    end
+
     def validate_auth_reload_token
       token = params.key?(:auth_token) ? params[:auth_token] : nil
       valid = Qa.config.valid_authority_reload_token?(token)

data/app/controllers/qa/terms_controller.rb

@@ -28,9 +28,10 @@ class Qa::TermsController < ::ApplicationController
 
   # If the subauthority supports it, return all the information for a given term
   def show
-    term = @authority.find(params[:id])
+    term = @authority.method(:find).arity == 2 ? @authority.find(params[:id], self) : @authority.find(params[:id])
     cors_allow_origin_header(response)
-    render json: term
+    content_type = params["format"] == "jsonld" ? 'application/ld+json' : 'application/json'
+    render json: term, content_type: content_type
   end
 
   def check_vocab_param

data/app/models/qa/linked_data/config/context_property_map.rb

@@ -67,7 +67,7 @@ module Qa
         # Values of this property for a specfic subject URI
         # @return [Array<String>] values for this property
         def values(graph, subject_uri)
-          ldpath_evaluate(basic_program, graph, subject_uri)
+          Qa::LinkedData::LdpathService.ldpath_evaluate(program: basic_program, graph: graph, subject_uri: subject_uri)
         end
 
         # Values of this property for a specfic subject URI with URI values expanded to include id and label.
@@ -98,44 +98,25 @@ module Qa
           end
 
           def basic_program
-            @basic_program ||= ldpath_program(ldpath)
+            @basic_program ||= Qa::LinkedData::LdpathService.ldpath_program(ldpath: ldpath, prefixes: prefixes)
           end
 
           def expansion_label_program
-            @expansion_label_program ||= ldpath_program(expansion_label_ldpath)
+            @expansion_label_program ||= Qa::LinkedData::LdpathService.ldpath_program(ldpath: expansion_label_ldpath, prefixes: prefixes)
           end
 
           def expansion_id_program
-            @expansion_id_program ||= ldpath_program(expansion_id_ldpath)
-          end
-
-          def ldpath_program(ldpath)
-            program_code = ""
-            prefixes.each { |key, url| program_code << "@prefix #{key} : <#{url}> \;\n" }
-            program_code << "property = #{ldpath} \;"
-            Ldpath::Program.parse program_code
-          rescue => e
-            Rails.logger.warn("WARNING: #{I18n.t('qa.linked_data.ldpath.parse_logger_error')} (ldpath='#{ldpath}')\n    cause: #{e.message}")
-            raise StandardError, I18n.t('qa.linked_data.ldpath.parse_error')
-          end
-
-          def ldpath_evaluate(program, graph, subject_uri)
-            return VALUE_ON_ERROR if program.blank?
-            output = program.evaluate subject_uri, graph
-            output.present? ? output['property'].uniq : nil
-          rescue => e
-            Rails.logger.warn("WARNING: #{I18n.t('qa.linked_data.ldpath.evaluate_logger_error')} (ldpath='#{ldpath}')\n    cause: #{e.message}")
-            raise StandardError, I18n.t('qa.linked_data.ldpath.evaluate_error')
+            @expansion_id_program ||= Qa::LinkedData::LdpathService.ldpath_program(ldpath: expansion_id_ldpath, prefixes: prefixes)
           end
 
           def expansion_label(graph, uri)
-            label = ldpath_evaluate(expansion_label_program, graph, RDF::URI(uri))
+            label = Qa::LinkedData::LdpathService.ldpath_evaluate(program: expansion_label_program, graph: graph, subject_uri: RDF::URI(uri))
             label.size == 1 ? label.first : label
           end
 
           def expansion_id(graph, uri)
             return uri if expansion_id_ldpath.blank?
-            id = ldpath_evaluate(expansion_id_program, graph, RDF::URI(uri))
+            id = Qa::LinkedData::LdpathService.ldpath_evaluate(program: expansion_id_program, graph: graph, subject_uri: RDF::URI(uri))
             id.size == 1 ? id.first : id
           end
       end

data/app/services/qa/iri_template_service.rb

@@ -1,31 +1,39 @@
 # Provide service for building a URL based on an IRI Templated Link and its variable mappings based on provided substitutions.
 module Qa
   class IriTemplateService
-    # Construct an url from an IriTemplate making identified substitutions
-    # @param url_config [Qa::IriTemplate::UrlConfig] configuration (json) holding the template and variable mappings
-    # @param substitutions [HashWithIndifferentAccess] name-value pairs to substitute into the url template
-    # @return [String] url with substitutions
-    def self.build_url(url_config:, substitutions:)
-      # TODO: This is a very simple approach using direct substitution into the template string.
-      #   Better would be to...
-      #     * patterns without a substitution are not included in the resulting URL
-      #     * appropriately adds '?' or '&'
-      #     * ensure proper escaping of values (e.g. value="A simple string" which is encoded as A%20simple%20string)
-      #   Even more advanced would be to...
-      #     * support BasicRepresentation (which is what it does now)
-      #     * support ExplicitRepresentation
-      #        * literal encoding for values (e.g. value="A simple string" becomes %22A%20simple%20string%22)
-      #        * language encoding for values (e.g. value="A simple string" becomes value="A simple string"@en which is encoded as %22A%20simple%20string%22%40en)
-      #        * type encoding for values (e.g. value=5.5 becomes value="5.5"^^http://www.w3.org/2001/XMLSchema#decimal which is encoded
-      #                                         as %225.5%22%5E%5Ehttp%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%23decimal)
-      # Fuller implementations parse the template into component parts and then build the URL by adding parts in as applicable.
-      url = url_config.template
-      url_config.mapping.each do |m|
-        key = m.variable
-        url = url.gsub("{#{key}}", m.simple_value(substitutions[key]))
-        url = url.gsub("{?#{key}}", m.parameter_value(substitutions[key]))
+    class << self
+      # Construct an url from an IriTemplate making identified substitutions
+      # @param url_config [Qa::IriTemplate::UrlConfig] configuration (json) holding the template and variable mappings
+      # @param substitutions [HashWithIndifferentAccess] name-value pairs to substitute into the url template
+      # @return [String] url with substitutions
+      def build_url(url_config:, substitutions:)
+        # TODO: This is a very simple approach using direct substitution into the template string.
+        #   Better would be to...
+        #     * appropriately adds '?' or '&'
+        #     * ensure proper escaping of values (e.g. value="A simple string" which is encoded as A%20simple%20string)
+        #   Even more advanced would be to...
+        #     * support BasicRepresentation (which is what it does now)
+        #     * support ExplicitRepresentation
+        #        * literal encoding for values (e.g. value="A simple string" becomes %22A%20simple%20string%22)
+        #        * language encoding for values (e.g. value="A simple string" becomes value="A simple string"@en which is encoded as %22A%20simple%20string%22%40en)
+        #        * type encoding for values (e.g. value=5.5 becomes value="5.5"^^http://www.w3.org/2001/XMLSchema#decimal which is encoded
+        #                                         as %225.5%22%5E%5Ehttp%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%23decimal)
+        # Fuller implementations parse the template into component parts and then build the URL by adding parts in as applicable.
+        url = url_config.template
+        url_config.mapping.each do |m|
+          key = m.variable
+          url = url.gsub("{#{key}}", m.simple_value(substitutions[key]))
+          url = url.gsub("{?#{key}}", m.parameter_value(substitutions[key]))
+        end
+        clean(url)
       end
-      url
+
+      private
+
+        # In the process of substitution, if a value is missing, you can end up with '?&', '&&', or ending with '&'.  These are all removed this method.
+        def clean(url)
+          url.gsub(/&&*/, '&').chomp('&').gsub('?&', '?')
+        end
     end
   end
 end

data/app/services/qa/linked_data/authority_service.rb

@@ -41,6 +41,14 @@ module Qa
       def self.authority_names
         authority_configs.keys.sort
       end
+
+      # Get the list of names and details of the loaded authorities
+      # @return [Array<String>] names of the authority config files that are currently loaded
+      def self.authority_details
+        details = []
+        authority_names.each { |auth_name| details << Qa::Authorities::LinkedData::Config.new(auth_name).authority_info }
+        details.flatten
+      end
     end
   end
 end

data/app/services/qa/linked_data/authority_url_service.rb

@@ -4,16 +4,17 @@ module Qa
     class AuthorityUrlService
       class << self
         # Build a url for an authority/subauthority for the specified action.
-        # @param authority [Symbol] name of a registered authority
-        # @param subauthority [String] name of a subauthority
+        # @param action_config [Qa::Authorities::LinkedData::SearchConfig | Qa::Authorities::LinkedData::TermConfig] action configuration for the authority
         # @param action [Symbol] action with valid values :search or :term
         # @param action_request [String] the request the user is making of the authority (e.g. query text or term id/uri)
-        # @param substitutions [Hash] variable-value pairs to substitute into the URL template
-        # @return a valid URL the submits the action request to the external authority
-        def build_url(action_config:, action:, action_request:, substitutions: {}, subauthority: nil)
+        # @param substitutions [Hash] variable-value pairs to substitute into the URL template (optional)
+        # @param subauthority [String] name of a subauthority (optional)
+        # @param language [Array<Symbol>] languages for filtering returned literals (optional)
+        # @return a valid URL that submits the action request to the external authority
+        def build_url(action_config:, action:, action_request:, substitutions: {}, subauthority: nil, language: nil) # rubocop:disable Metrics/ParameterLists
           action_validation(action)
           url_config = action_config.url_config
-          selected_substitutions = url_config.extract_substitutions(combined_substitutions(action_config, action, action_request, substitutions, subauthority))
+          selected_substitutions = url_config.extract_substitutions(combined_substitutions(action_config, action, action_request, substitutions, subauthority, language))
           Qa::IriTemplateService.build_url(url_config: url_config, substitutions: selected_substitutions)
         end
 
@@ -24,9 +25,10 @@ module Qa
             raise Qa::UnsupportedAction, "#{action} Not Supported - Action must be one of the supported actions (e.g. :term, :search)"
           end
 
-          def combined_substitutions(action_config, action, action_request, substitutions, subauthority)
+          def combined_substitutions(action_config, action, action_request, substitutions, subauthority, language) # rubocop:disable Metrics/ParameterLists
             substitutions[action_request_variable(action_config, action)] = action_request
-            substitutions[action_subauth_variable(action_config)] = action_subauth_variable_value(action_config, subauthority) if subauthority.present?
+            substitutions[action_subauth_variable(action_config)] = action_subauth_variable_value(action_config, subauthority) if supports_subauthorities?(action_config) && subauthority.present?
+            substitutions[action_language_variable(action_config)] = language_value(language) if supports_language_parameter?(action_config) && language.present?
             substitutions
           end
 
@@ -35,6 +37,10 @@ module Qa
             action_config.qa_replacement_patterns[key]
           end
 
+          def supports_subauthorities?(action_config)
+            action_config.supports_subauthorities?
+          end
+
           def action_subauth_variable(action_config)
             action_config.qa_replacement_patterns[:subauth]
           end
@@ -42,6 +48,19 @@ module Qa
           def action_subauth_variable_value(action_config, subauthority)
             action_config.subauthorities[subauthority.to_sym]
           end
+
+          def supports_language_parameter?(action_config)
+            action_config.supports_language_parameter?
+          end
+
+          def action_language_variable(action_config)
+            action_config.qa_replacement_patterns[:lang]
+          end
+
+          def language_value(language)
+            return nil if language.blank?
+            language.first
+          end
       end
     end
   end

data/app/services/qa/linked_data/deep_sort_service.rb

@@ -2,8 +2,9 @@
 module Qa
   module LinkedData
     class DeepSortService
-      # @params [Array<Hash<Symbol,Array<RDF::Literal>>>] the array of hashes to sort
-      # @params [sort_key] the key in the hash on whose value the array will be sorted
+      # @param [Array<Hash<Symbol,Array<RDF::Literal>>>] the array of hashes to sort
+      # @param [sort_key] the key in the hash on whose value the array will be sorted
+      # @param [Symbol] preferred language to appear first in the list; defaults to no preference
       # @return instance of this class
       # @example the_array parameter
       #   [

data/app/services/qa/linked_data/graph_service.rb

@@ -41,6 +41,19 @@ module Qa
           values
         end
 
+        # Get subjects that have the object value for the predicate in the graph.
+        # @param graph [RDF::Graph] the graph to search
+        # @param predicate [RDF::URI] the URI of the predicate
+        # @param object_value [String] the object value
+        # @return [Array] all subjects for the predicate-object_value pair
+        def subjects_for_object_value(graph:, predicate:, object_value:)
+          subjects = []
+          graph.query([:subject, predicate, object_value]) do |statement|
+            subjects << statement.subject
+          end
+          subjects
+        end
+
         def deep_copy(graph:)
           new_graph = RDF::Graph.new
           graph.statements.each do |st|

data/app/services/qa/linked_data/language_service.rb

@@ -2,13 +2,24 @@
 module Qa
   module LinkedData
     class LanguageService
+      WILDCARD = '*'.freeze
+
       class << self
+        # @param user_langauge [Symbol|String] the language code (e.g. :en, :fr) specified as URL parameter or on URL header
+        # @param authority_language [Symbol|String|Array<Symbol|String>] the default language specified in the authority's configuration file
+        # @return [Array<Symbol>] the selected language(s) normalized as an array of symbols (e.g. [:en, :fr])
+        # @note Precedence from high to low:
+        #       * user_language (with URL parameter preferred over URL header)
+        #       * authority_language (defined in authority config)
+        #       * site default_language (defined in QA initializer)
         def preferred_language(user_language: nil, authority_language: nil)
           return normalize_language(user_language) if user_language.present?
           return normalize_language(authority_language) if authority_language.present?
           normalize_language(Qa.config.default_language)
         end
 
+        # @param [RDF::Literal] the literal to check
+        # @return [Boolean] true if literal has a language tag; otherwise, false
         def literal_has_language_marker?(literal)
           return false unless literal.respond_to?(:language)
           literal.language.present?
@@ -22,6 +33,7 @@ module Qa
           def normalize_language(language)
             return language if language.blank?
             language = [language] unless language.is_a? Array
+            return nil if language.include?(WILDCARD)
             language.map(&:to_sym)
           end
       end

data/app/services/qa/linked_data/language_sort_service.rb

@@ -7,7 +7,6 @@ module Qa
       attr_reader :literals, :preferred_language
       attr_reader :languages, :bins
       private :literals, :preferred_language, :languages, :bins
-      # private :literals, :preferred_language, :languages, :languages=, :bins, :bins=
 
       # @param [Array<RDF::Literals>] string literals to sort
       # @param [Symbol] preferred language to appear first in the list; defaults to no preference
@@ -20,7 +19,7 @@ module Qa
       end
 
       # Sort the literals stored in this instance of the service
-      # @return sorted version of literals
+      # @return [Array<RDF::Literals] sorted version of literals
       def sort
         return literals unless literals.present?
         return @sorted_literals if @sorted_literals.present?
@@ -30,6 +29,12 @@ module Qa
         @sorted_literals = construct_sorted_literals
       end
 
+      # Sort the literals and return as an array of strings with only unique literals and empty strings removed
+      # @return [Array<String>] sorted version of literals as strings
+      def uniq_sorted_strings
+        sort.map(&:to_s).uniq.delete_if(&:blank?)
+      end
+
       private
 
         def construct_sorted_literals

data/app/services/qa/linked_data/ldpath_service.rb

@@ -0,0 +1,40 @@
+# Defines the external authority predicates used to extract additional context from the graph.
+require 'ldpath'
+
+module Qa
+  module LinkedData
+    class LdpathService
+      VALUE_ON_ERROR = [].freeze
+
+      # Create the ldpath program for a given ldpath.
+      # @param ldpath [String] ldpath to follow to get a value from a graph (documation: http://marmotta.apache.org/ldpath/language.html)
+      # @param prefixes [Hash] shortcut names for URI prefixes with key = part of predicate that is the same for all terms (e.g. { "madsrdf": "http://www.loc.gov/mads/rdf/v1#" })
+      # @return [Ldpath::Program] an executable program that will extract a value from a graph
+      def self.ldpath_program(ldpath:, prefixes: {})
+        program_code = ""
+        prefixes.each { |key, url| program_code << "@prefix #{key} : <#{url}> \;\n" }
+        program_code << "property = #{ldpath} \;"
+        Ldpath::Program.parse program_code
+      rescue => e
+        Rails.logger.warn("WARNING: #{I18n.t('qa.linked_data.ldpath.parse_logger_error')}... cause: #{e.message}\n   ldpath_program=\n#{program_code}")
+        raise StandardError, I18n.t("qa.linked_data.ldpath.parse_error") + "... cause: #{e.message}"
+      end
+
+      # Evaluate an ldpath for a specific subject uri in the context of a graph and return the extracted values.
+      # @param program [Ldpath::Program] an executable program that will extract a value from a graph
+      # @param graph [RDF::Graph] the graph from which the values will be extracted
+      # @param subject_uri [RDF::URI] retrieved values will be limited to those with the subject uri
+      # @param limit_to_context [Boolean] if true, the evaluation process will not make any outside network calls.
+      #        It will limit results to those found in the context graph.
+      ## @return [Array<String>] the extracted values based on the ldpath
+      def self.ldpath_evaluate(program:, graph:, subject_uri:, limit_to_context: Qa.config.limit_ldpath_to_context?)
+        return VALUE_ON_ERROR if program.blank?
+        output = program.evaluate(subject_uri, context: graph, limit_to_context: limit_to_context)
+        output.present? ? output['property'].uniq : nil
+      rescue => e
+        Rails.logger.warn("WARNING: #{I18n.t('qa.linked_data.ldpath.evaluate_logger_error')} (cause: #{e.message}")
+        raise StandardError, I18n.t("qa.linked_data.ldpath.evaluate_error") + "... cause: #{e.message}"
+      end
+    end
+  end
+end