qa 1.0.0 → 1.1.0

data/config/authorities/linked_data/loc.json

@@ -0,0 +1,46 @@
+{
+  "term": {
+    "url": {
+      "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+      "@type": "IriTemplate",
+      "template": "http://id.loc.gov/authorities/{?subauth}/{?term_id}",
+      "variableRepresentation": "BasicRepresentation",
+      "mapping": [
+        {
+          "@type": "IriTemplateMapping",
+          "variable": "term_id",
+          "property": "hydra:freetextQuery",
+          "required": true
+        },
+        {
+          "@type": "IriTemplateMapping",
+          "variable": "subauth",
+          "property": "hydra:freetextQuery",
+          "required": false,
+          "default": "names"
+        }
+      ]
+    },
+    "qa_replacement_patterns": {
+      "term_id": "term_id",
+      "subauth": "subauth"
+    },
+    "term_id": "ID",
+    "language": ["en"],
+    "results": {
+      "id_predicate": "http://id.loc.gov/vocabulary/identifiers/lccn",
+      "label_predicate": "http://www.w3.org/2004/02/skos/core#prefLabel",
+      "altlabel_predicate": "http://www.w3.org/2004/02/skos/core#altLabel",
+      "sameas_predicate": "http://www.w3.org/2004/02/skos/core#exactMatch"
+    },
+    "subauthorities": {
+      "subjects": "subjects",
+      "names": "names",
+      "classification": "classification",
+      "child_subject": "childrensSubjects",
+      "genre": "genreForms",
+      "demographic": "demographicTerms"
+    }
+  },
+  "search": {}
+}

data/config/authorities/linked_data/oclc_fast.json

@@ -0,0 +1,78 @@
+{
+  "term": {
+    "url": {
+      "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+      "@type":    "IriTemplate",
+      "template": "http://id.worldcat.org/fast/{?term_id}",
+      "variableRepresentation": "BasicRepresentation",
+      "mapping": [
+        {
+          "@type":    "IriTemplateMapping",
+          "variable": "term_id",
+          "property": "hydra:freetextQuery",
+          "required": true
+        }
+      ]
+    },
+    "qa_replacement_patterns": {
+      "term_id": "term_id"
+    },
+    "term_id": "ID",
+    "results": {
+      "id_predicate":       "http://purl.org/dc/terms/identifier",
+      "label_predicate":    "http://www.w3.org/2004/02/skos/core#prefLabel",
+      "altlabel_predicate": "http://www.w3.org/2004/02/skos/core#altLabel",
+      "sameas_predicate":   "http://schema.org/sameAs"
+    }
+  },
+  "search": {
+    "url": {
+      "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+      "@type": "IriTemplate",
+      "template": "http://experimental.worldcat.org/fast/search?query={?subauth}+all+%22{?query}%22&sortKeys=usage&maximumRecords={?maximumRecords}",
+      "variableRepresentation": "BasicRepresentation",
+      "mapping": [
+        {
+          "@type": "IriTemplateMapping",
+          "variable": "query",
+          "property": "hydra:freetextQuery",
+          "required": true
+        },
+        {
+          "@type": "IriTemplateMapping",
+          "variable": "subauth",
+          "property": "hydra:freetextQuery",
+          "required": false,
+          "default": "cql.any"
+        },
+        {
+          "@type": "IriTemplateMapping",
+          "variable": "maximumRecords",
+          "property": "hydra:freetextQuery",
+          "required": false,
+          "default": "20"
+        }
+      ]
+    },
+    "qa_replacement_patterns": {
+      "query":   "query",
+      "subauth": "subauth"
+    },
+    "results": {
+      "id_predicate":       "http://purl.org/dc/terms/identifier",
+      "label_predicate":    "http://www.w3.org/2004/02/skos/core#prefLabel",
+      "sort_predicate":     "http://www.w3.org/2004/02/skos/core#prefLabel"
+    },
+    "subauthorities": {
+      "topic":          "oclc.topic",
+      "geographic":     "oclc.geographic",
+      "event_name":     "oclc.eventName",
+      "personal_name":  "oclc.personalName",
+      "corporate_name": "oclc.corporateName",
+      "uniform_title":  "oclc.uniformTitle",
+      "period":         "oclc.period",
+      "form":           "oclc.form",
+      "alt_lc":         "oclc.altlc"
+    }
+  }
+}

data/config/initializers/linked_data_authorities.rb

@@ -0,0 +1,17 @@
+auth_cfg = {}
+# load QA configured linked data authorities
+Dir[File.join(Qa::Engine.root, 'config', 'authorities', 'linked_data', '*.json')].each do |fn|
+  auth = File.basename(fn, '.json').upcase.to_sym
+  json = File.read(File.expand_path(fn, __FILE__))
+  cfg = JSON.parse(json).deep_symbolize_keys
+  auth_cfg[auth] = cfg
+end
+
+# load app configured linked data authorities and overrides
+Dir[File.join(Rails.root, 'config', 'authorities', 'linked_data', '*.json')].each do |fn|
+  auth = File.basename(fn, '.json').upcase.to_sym
+  json = File.read(File.expand_path(fn, __FILE__))
+  cfg = JSON.parse(json).deep_symbolize_keys
+  auth_cfg[auth] = cfg
+end
+LINKED_DATA_AUTHORITIES_CONFIG = auth_cfg.freeze

data/config/routes.rb

@@ -1,4 +1,7 @@
 Qa::Engine.routes.draw do
+  get "/search/linked_data/:vocab(/:subauthority)", controller: :linked_data_terms, action: :search
+  get "/show/linked_data/:vocab/:id", controller: :linked_data_terms, action: :show
+  get "/show/linked_data/:vocab/:subauthority/:id", controller: :linked_data_terms, action: :show
   get "/terms/:vocab(/:subauthority)",  controller: :terms, action: :index
   get "/search/:vocab(/:subauthority)", controller: :terms, action: :search
   get "/show/:vocab/:id", controller: :terms, action: :show

data/lib/qa.rb

@@ -16,4 +16,19 @@ module Qa
 
   # Raised when a subauthority is not valid
   class InvalidSubAuthority < ArgumentError; end
+
+  # Raised when a request is made to a non-configured linked data authority
+  class InvalidLinkedDataAuthority < ArgumentError; end
+
+  # Raised when a response is in an unsupported format
+  class UnsupportedFormat < ArgumentError; end
+
+  # Raised when a configuration parameter is incorrect or is required and missing
+  class InvalidConfiguration < ArgumentError; end
+
+  # Raised when a linked data request to a server returns a 500 error
+  class ServiceUnavailable < ArgumentError; end
+
+  # Raised when the server returns 404 for a find term request
+  class TermNotFound < ArgumentError; end
 end

data/lib/qa/authorities.rb

@@ -19,4 +19,6 @@ module Qa::Authorities
   autoload :WebServiceBase
   autoload :AssignFast
   autoload :AssignFastSubauthority
+  autoload :Crossref
+  autoload :LinkedData
 end

data/lib/qa/authorities/base.rb

@@ -31,7 +31,7 @@ module Qa::Authorities
     #
     # @todo better specify return type
     def find(_id)
-      raise NotImplementedError, "#{self.class}#all is unimplemented."
+      raise NotImplementedError, "#{self.class}#find is unimplemented."
     end
 
     ##

data/lib/qa/authorities/crossref.rb

@@ -0,0 +1,16 @@
+require 'uri'
+module Qa::Authorities
+  module Crossref
+    require 'qa/authorities/crossref/generic_authority'
+    extend AuthorityWithSubAuthority
+
+    def self.subauthority_for(subauthority)
+      validate_subauthority!(subauthority)
+      GenericAuthority.new(subauthority)
+    end
+
+    def self.subauthorities
+      ['funders', 'journals']
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+module Qa::Authorities
+  class Crossref::GenericAuthority < Base
+    include WebServiceBase
+    class_attribute :label, :identifier
+    attr_reader :subauthority
+
+    def initialize(subauthority)
+      @subauthority = subauthority
+    end
+
+    # Create a label from the crossref result hash
+    #
+    # @param item [Hash] the crossref result
+    # @return [String] a label combining the name, alt-names and location
+    self.label = lambda do |item|
+      [item['name'],
+       item['alt-names'].blank? ? nil : "(#{item['alt-names'].join(', ')})",
+       item['location']].compact.join(', ')
+    end
+
+    def search(q)
+      parse_authority_response(json(build_query_url(q)))
+    end
+
+    def build_query_url(q)
+      query = URI.escape(untaint(q))
+      "http://api.crossref.org/#{subauthority}?query=#{query}"
+    end
+
+    def untaint(q)
+      q.gsub(/[^\w\s-]/, '')
+    end
+
+    def find(id)
+      json(find_url(id))
+    end
+
+    def find_url(id)
+      "http://api.crossref.org/#{subauthority}/#{id}"
+    end
+
+    private
+
+      # Reformats the data received from the service
+      def parse_authority_response(response)
+        response['message']['items'].map do |result|
+          case subauthority
+          when 'funders'
+            { id: result['id'],
+              uri: result['uri'],
+              label: label.call(result),
+              value: result['name'] }
+          when 'journals'
+            { id: result['ISSN'].first,
+              label: result['title'],
+              publisher: result['publisher'],
+              issn: result['ISSN'] }
+
+          end
+        end
+      end
+  end
+end

data/lib/qa/authorities/geonames.rb

@@ -38,7 +38,8 @@ module Qa::Authorities
       # Reformats the data received from the service
       def parse_authority_response(response)
         response['geonames'].map do |result|
-          { 'id' => "http://sws.geonames.org/#{result['geonameId']}",
+          # Note: the trailing slash is meaningful.
+          { 'id' => "http://sws.geonames.org/#{result['geonameId']}/",
             'label' => label.call(result) }
         end
       end

data/lib/qa/authorities/linked_data.rb

@@ -0,0 +1,10 @@
+module Qa::Authorities
+  module LinkedData
+    extend ActiveSupport::Autoload
+    autoload :GenericAuthority
+    autoload :RdfHelper
+    autoload :SearchQuery
+    autoload :FindTerm
+    autoload :Config
+  end
+end

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

@@ -0,0 +1,80 @@
+require 'qa/authorities/linked_data/config/term_config'.freeze
+require 'qa/authorities/linked_data/config/search_config'.freeze
+require 'json'
+
+# Provide attr_reader methods for linked data authority configurations.  Some default configurations are provided for several
+# linked data authorities and can be found at /config/authorities/linked_data.  You can add configurations for new authorities by
+# adding the configuration at YOUR_APP/config/authorities/linked_data.  You can modify a QA provided configuration by copying
+# it to YOUR_APP/config/authorities/linked_data and making the modifications there. See README for more information on the
+# structure of the configuration.
+#
+# This configuration processed by this class is used by Qa::Authorities::LinkedData::GenericAuthority to drive url construction
+# and results processing for a specific linked data authority.
+#
+# @see Qa::Authorities::LinkedData::GenericAuthority#initialize
+# @see Qa::Authorities::LinkedData::TermConfig
+# @see Qa::Authorities::LinkedData::SearchConfig
+module Qa::Authorities
+  module LinkedData
+    class Config
+      attr_reader :authority_name
+      attr_reader :authority_config
+
+      # Initialize to hold the configuration for the specifed authority.  Configurations are defined in config/authorities/linked_data.  See README for more information.
+      # @param [String] the name of the configuration file for the authority
+      # @return [Qa::Authorities::LinkedData::Config] instance of this class
+      def initialize(auth_name)
+        @authority_name = auth_name
+        auth_config
+      end
+
+      def search
+        @search ||= Qa::Authorities::LinkedData::SearchConfig.new(auth_config.fetch(:search))
+      end
+
+      def term
+        @term ||= Qa::Authorities::LinkedData::TermConfig.new(auth_config.fetch(:term))
+      end
+
+      # Return the full configuration for an authority
+      # @return [String] the authority configuration
+      def auth_config
+        @authority_config ||= LINKED_DATA_AUTHORITIES_CONFIG[@authority_name]
+        raise Qa::InvalidLinkedDataAuthority, "Unable to initialize linked data authority '#{@authority_name}'" if @authority_config.nil?
+        @authority_config
+      end
+
+      def self.config_value(config, key)
+        return nil if config.nil? || !(config.key? key)
+        config[key]
+      end
+
+      def self.predicate_uri(config, key)
+        pred = config_value(config, key)
+        pred_uri = nil
+        pred_uri = RDF::URI(pred) unless pred.nil? || pred.length <= 0
+        pred_uri
+      end
+
+      def self.replace_pattern(url, pattern, value)
+        url.gsub("{?#{pattern}}", value)
+      end
+
+      def self.process_subauthority(url, subauth_pattern, subauthorities, subauth_key)
+        pattern = subauth_pattern[:pattern]
+        value = subauthorities[subauth_key] || subauth_pattern[:default]
+        replace_pattern(url, pattern, value)
+      end
+
+      def self.apply_replacements(url, config, replacements = {})
+        return url unless config.size.positive?
+        config.each do |param_key, rep_pattern|
+          s_param_key = param_key.to_s
+          value = replacements[param_key] || replacements[s_param_key] || rep_pattern[:default]
+          url = replace_pattern(url, param_key, value)
+        end
+        url
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+# Provide attr_reader methods specific to search configuration for linked data authority configurations.  This is separated
+# out for readability and file length.
+# @see Qa::Authorities::LinkedData::Config
+# @see Qa::Authorities::LinkedData::TermConfig
+module Qa::Authorities
+  module LinkedData
+    class SearchConfig
+      # @param [Hash] config the search portion of the config
+      def initialize(config)
+        @search_config = 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?
+        search_config.present?
+      end
+
+      # Return search url encoding defined in the configuration for this authority
+      # if it was provided
+      # @return [Hash,NilClass] the configured search url
+      def url
+        search_config[:url]
+      end
+
+      # Return search url template defined in the configuration for this authority.
+      # @return [String] the configured search url template
+      def url_template
+        url.fetch(:template)
+      end
+
+      # Return search url parameter mapping defined in the configuration for this authority.
+      # @return [Hash] the configured search url parameter mappings with variable name as key
+      def url_mappings
+        return @url_mappings unless @url_mappings.nil?
+        mappings = Config.config_value(url, :mapping)
+        return {} if mappings.nil?
+        Hash[*mappings.collect { |m| [m[:variable].to_sym, m] }.flatten]
+      end
+
+      # Return the preferred language for literal value selection for search query.
+      # Only applies if the authority provides language encoded literals.
+      # @return [String] the configured language for search query
+      def language
+        return @language unless @language.nil?
+        lang = search_config[:language]
+        return nil if lang.nil?
+        lang = [lang] if lang.is_a? String
+        @language = lang.collect(&:to_sym)
+      end
+
+      # Return results predicates if specified
+      # @return [Hash,NilClass] all the configured predicates to pull out of the results
+      def results
+        search_config[:results]
+      end
+
+      # Return results id_predicate
+      # @return [String] the configured predicate to use to extract the id from the results
+      def results_id_predicate
+        Config.predicate_uri(results, :id_predicate)
+      end
+
+      # Return results label_predicate
+      # @return [String] the configured predicate to use to extract label values from the results
+      def results_label_predicate
+        Config.predicate_uri(results, :label_predicate)
+      end
+
+      # Return results altlabel_predicate
+      # @return [String] the configured predicate to use to extract altlabel values from the results
+      def results_altlabel_predicate
+        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?
+        false
+      end
+
+      # Return results sort_predicate
+      # @return [String] the configured predicate to use for sorting results from the query search
+      def results_sort_predicate
+        Config.predicate_uri(results, :sort_predicate)
+      end
+
+      # Return parameters that are required for QA api
+      # @return [Hash] the configured search url parameter mappings
+      def qa_replacement_patterns
+        search_config.fetch(:qa_replacement_patterns)
+      end
+
+      # Are there replacement parameters configured for search query?
+      # @return [True|False] true if there are replacement parameters configured for search query; otherwise, false
+      def replacements?
+        replacement_count.positive?
+      end
+
+      # Return the number of possible replacement values to make in the search URL
+      # @return [Integer] the configured number of possible replacements in the search url
+      def replacement_count
+        replacements.size
+      end
+
+      # Return the replacement configurations
+      # @return [Hash] the configurations for search url replacements
+      def replacements
+        return @replacements unless @replacements.nil?
+        @replacements = {}
+        @replacements = url_mappings.select { |k, _v| !qa_replacement_patterns.include?(k) } unless search_config.nil? || url_mappings.nil?
+        @replacements
+      end
+
+      # Are there subauthorities configured for search query?
+      # @return [True|False] true if there are subauthorities configured for search query; otherwise, false
+      def subauthorities?
+        subauthority_count.positive?
+      end
+
+      # Is a specific subauthority configured for search query?
+      # @return [True|False] true if the specified subauthority is configured for search query; otherwise, false
+      def subauthority?(subauth_name)
+        subauth_name = subauth_name.to_sym if subauth_name.is_a? String
+        subauthorities.key? subauth_name
+      end
+
+      # Return the number of subauthorities defined for search query
+      # @return [Integer] the number of subauthorities defined for search query
+      def subauthority_count
+        subauthorities.size
+      end
+
+      # Return the list of subauthorities for search query
+      # @return [Hash] the configurations for search url replacements
+      def subauthorities
+        @subauthorities ||= {} if search_config.nil? || !(search_config.key? :subauthorities)
+        @subauthorities ||= search_config.fetch(:subauthorities)
+      end
+
+      # Return the replacement configurations
+      # @return [Hash] the configurations for search url replacements
+      def subauthority_replacement_pattern
+        return {} unless subauthorities?
+        @subauthority_replacement_pattern ||= {} if search_config.nil? || !subauthorities?
+        pattern = qa_replacement_patterns[:subauth]
+        default = url_mappings[pattern.to_sym][:default]
+        @subauthority_replacement_pattern ||= { pattern: pattern, default: default }
+      end
+
+      # Build a linked data authority search url
+      # @param [String] the query
+      # @param [String] (optional) subauthority key
+      # @param [Hash] (optional) replacement values with { pattern_name (defined in YAML config) => value }
+      # @return [String] the search encoded url
+      def url_with_replacements(query, sub_auth = nil, search_replacements = {})
+        return nil unless supports_search?
+        sub_auth = sub_auth.to_sym if sub_auth.is_a? String
+        url = Config.replace_pattern(url_template, qa_replacement_patterns[:query], query)
+        url = Config.process_subauthority(url, subauthority_replacement_pattern, subauthorities, sub_auth) if subauthorities?
+        url = Config.apply_replacements(url, replacements, search_replacements) if replacements?
+        url
+      end
+    end
+  end
+end