blacklight_oai_provider 0.1.0 → 4.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3c8443a7d656487d8e2aa2cfd0ebd3b7b659d85b
+  data.tar.gz: 07f9b6fb1ca30e96915f1d9ea13f1afc962ec5a1
+SHA512:
+  metadata.gz: f0e3e076577da7493f9cb6ed7606720854e270892e85bef93d1e5959585c60cd61deb16790ee99c287625d5ddc971bacfb33446eea2b288b0108171eeb17fc21
+  data.tar.gz: f91efbafee6de242c66fb288b442b01cef71c70a123d6661209cc4a261ba22c1b6c0c598813e2a0b9e2ad77b396b7734fa5690d3d28d272fea29b7d3fd336258

data/.gitignore

@@ -0,0 +1,18 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+.ruby-version
+.ruby-gemset
+.byebug_history
+
+# rspec failure tracking
+.rspec_status
+
+.internal_test_app

data/.rubocop.yml

@@ -0,0 +1,39 @@
+require: rubocop-rspec
+
+inherit_from:
+  - .rubocop_todo.yml
+
+AllCops:
+  DisplayCopNames: true
+  Exclude:
+  - "blacklight_oai_provider.gemspec"
+
+Rails:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - "lib/railties/blacklight_oai_provider.rake"
+
+Metrics/LineLength:
+  Max: 200
+
+Style/StringLiterals:
+  Enabled: false
+
+Layout/IndentationConsistency:
+  EnforcedStyle: normal
+
+Rails/OutputSafety:
+  Enabled: false
+
+# engine_cart block includes conditional, not duplication
+Bundler/DuplicatedGem:
+  Exclude:
+  - 'Gemfile'
+
+# engine_cart block is following default Rails order
+Bundler/OrderedGems:
+  Exclude:
+  - 'Gemfile'

data/.rubocop_todo.yml

@@ -0,0 +1,130 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2017-10-26 15:19:14 -0400 using RuboCop version 0.50.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: empty_lines, no_empty_lines
+Layout/EmptyLinesAroundBlockBody:
+  Exclude:
+    - 'spec/requests/list_metadata_formats_spec.rb'
+
+# Offense count: 4
+Metrics/AbcSize:
+  Max: 25
+
+# Offense count: 2
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 39
+
+# Offense count: 2
+RSpec/BeforeAfterAll:
+  Exclude:
+    - 'spec/spec_helper.rb'
+    - 'spec/rails_helper.rb'
+    - 'spec/support/**/*.rb'
+    - 'spec/requests/list_identifiers_spec.rb'
+
+# Offense count: 6
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/features/html_rendering_spec.rb'
+    - 'spec/requests/get_record_spec.rb'
+    - 'spec/requests/identify_spec.rb'
+    - 'spec/requests/list_identifiers_spec.rb'
+    - 'spec/requests/list_metadata_formats_spec.rb'
+    - 'spec/requests/list_records_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: CustomIncludeMethods.
+RSpec/EmptyExampleGroup:
+  Exclude:
+    - 'spec/requests/list_records_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: Max.
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/controllers/catalog_controller_spec.rb'
+
+# Offense count: 6
+RSpec/MultipleExpectations:
+  Max: 2
+
+# Offense count: 2
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: strict, flexible
+Rails/TimeZone:
+  Exclude:
+    - 'spec/requests/identify_spec.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles, ProceduralMethods, FunctionalMethods, IgnoredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# IgnoredMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/models/solr_document_spec.rb'
+
+# Offense count: 3
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: braces, no_braces, context_dependent
+Style/BracesAroundHashParameters:
+  Exclude:
+    - 'lib/blacklight_oai_provider/solr_document_wrapper.rb'
+    - 'spec/models/solr_document_spec.rb'
+
+# Offense count: 12
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'app/controllers/concerns/blacklight_oai_provider/controller.rb'
+    - 'app/models/concerns/blacklight_oai_provider/solr_document.rb'
+    - 'lib/blacklight_oai_provider.rb'
+    - 'lib/blacklight_oai_provider/engine.rb'
+    - 'lib/blacklight_oai_provider/exceptions.rb'
+    - 'lib/blacklight_oai_provider/resumption_token.rb'
+    - 'lib/blacklight_oai_provider/routes.rb'
+    - 'lib/blacklight_oai_provider/solr_document_provider.rb'
+    - 'lib/blacklight_oai_provider/solr_document_wrapper.rb'
+    - 'lib/blacklight_oai_provider/version.rb'
+    - 'lib/generators/blacklight_oai_provider/install_generator.rb'
+
+# Offense count: 24
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: when_needed, always, never
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Offense count: 2
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Exclude:
+    - 'lib/generators/blacklight_oai_provider/install_generator.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: MinSize, SupportedStyles.
+# SupportedStyles: percent, brackets
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: IgnoredMethods.
+# IgnoredMethods: respond_to, define_method
+Style/SymbolProc:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/.solr_wrapper

@@ -0,0 +1,8 @@
+# Place any default configuration for solr_wrapper here
+port: 8983
+verbose: true
+version: 5.5.5
+managed: true
+collection:
+  dir: solr/conf/
+  name: blacklight-core

data/.travis.yml

@@ -0,0 +1,16 @@
+notifications:
+  email: false
+
+language: ruby
+sudo: false
+rvm:
+  - 2.3.3
+  - 2.2
+  - 2.1
+
+env:
+ - "RAILS_VERSION=4.2.9"
+ - "RAILS_VERSION=4.1.16"
+
+before_install:
+  - gem install bundler

data/Gemfile

@@ -2,5 +2,37 @@ source 'http://rubygems.org'
 
 gemspec
 
-gem 'combustion'
-gem 'sqlite3'
+# BEGIN ENGINE_CART BLOCK
+# engine_cart: 1.1.0
+# engine_cart stanza: 0.10.0
+# the below comes from engine_cart, a gem used to test this Rails engine gem in the context of a Rails app.
+file = File.expand_path('Gemfile', ENV['ENGINE_CART_DESTINATION'] || ENV['RAILS_ROOT'] || File.expand_path('.internal_test_app', File.dirname(__FILE__)))
+if File.exist?(file)
+  begin
+    eval_gemfile file
+  rescue Bundler::GemfileError => e
+    Bundler.ui.warn '[EngineCart] Skipping Rails application dependencies:'
+    Bundler.ui.warn e.message
+  end
+else
+  Bundler.ui.warn "[EngineCart] Unable to find test application dependencies in #{file}, using placeholder dependencies"
+
+  if ENV['RAILS_VERSION']
+    if ENV['RAILS_VERSION'] == 'edge'
+      gem 'rails', github: 'rails/rails'
+      ENV['ENGINE_CART_RAILS_OPTIONS'] = '--edge --skip-turbolinks'
+    else
+      gem 'rails', ENV['RAILS_VERSION']
+    end
+  end
+
+  case ENV['RAILS_VERSION']
+  when /^4.2/
+    gem 'responders', '~> 2.0'
+    gem 'sass-rails', '>= 5.0'
+    gem 'coffee-rails', '~> 4.1.0'
+  when /^4.[01]/
+    gem 'sass-rails', '< 5.0'
+  end
+end
+# END ENGINE_CART BLOCK

data/README.md

@@ -0,0 +1,131 @@
+# BlacklightOaiProvider
+OAI-PMH service endpoint for Blacklight applications
+
+## Description
+The BlacklightOaiProvider plugin provides an [Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH)](http://www.openarchives.org/pmh/) data provider endpoint, using the [ruby-oai gem](https://github.com/code4lib/ruby-oai). This endpoint enables service providers harvest a data provider's metadata.
+
+### Versioning
+Starting `v4.1` major plugin versions are synced with major Blacklight versions. The last known version to work with Blacklight 3.x/Rails 3.x is `v0.1.0`.
+
+A few maintenance branches have been left in place in case there is interest to add support for older versions of Rails/Blacklight:
+
+`v3.x` -> Support for Blacklight 3.0
+
+`v4.x` -> Support for Blacklight 4.0 and Rails 3.0
+
+## Requirements
+A Rails app running Rails 4.x and Blacklight 4.x.
+
+OAI-PMH requires a timestamp field for all records. The Solr index should include an appropriate field. This field should be able to support date range queries. By default, the name of this field is `timestamp` (more on how to configure this below).
+
+A properly configured documentHandler in the blacklight/solr configuration.
+
+## Installation
+
+Add
+
+```ruby
+    gem 'blacklight_oai_provider', git: 'https://github.com/projectblacklight/blacklight_oai_provider'
+```
+
+to your Gemfile and run `bundle install`.
+
+Then run
+```ruby
+    rails generate blacklight_oai_provider:install
+```
+to install the appropriate extensions into your `CatalogController` and `SolrDocument` classes. If you want to do customize the way this installs, instead you may:
+
+- add this to your Solr Document model:
+```ruby
+    include BlacklightOaiProvider::SolrDocument
+```
+- add this to your Controller:
+```ruby
+    include BlacklightOaiProvider::Controller
+```
+
+## Configuration
+
+While the plugin provides some sensible (albeit generic) defaults out of the box, you probably will want to customize the OAI provider configuration.
+
+### Blacklight configuration
+You can provide OAI-PMH provider parameters by placing the following in your blacklight configuration (most likely in `app/controllers/catalog_controller.rb`)
+
+```ruby
+  configure_blacklight do |config|
+
+    # ...
+
+    config.oai = {
+      :provider => {
+        :repository_name => 'Test',
+        :repository_url => 'http://localhost',
+        :record_prefix => '',
+        :admin_email => 'root@localhost'
+      },
+      :document => {
+        :model => SolrDocument, # SolrDocument class you are using.
+        :limit => 25
+      }
+    }
+
+    # ...
+
+  end
+```
+
+The "provider" configuration is documented as part of the ruby-oai gem at http://oai.rubyforge.org/
+
+_Note:_ The document handler in your blacklight controller must be configured properly for this plugin to correctly look up records.
+
+### SolrDocument configuration
+To change the name of the timestamp solr field in your `SolrDocument` model change the following attribute:
+```ruby
+    self.timestamp_key = 'record_creation_date' # Default: 'timestamp'
+```
+
+The metadata displayed in the xml serialization of each record is based off the `field_semantics` hash in the `SolrDocument` model. To update/change these fields add something like the following to your model:
+
+```ruby
+  field_semantics.merge!(
+    creator: "author_display",
+    date: "pub_date",
+    subject: "subject_topic_facet",
+    title: "title_display",
+    language: "language_facet",
+    format: "format"
+  )
+```
+
+The fields used by the dublin core serialization are:
+```ruby
+  [:contributor, :coverage, :creator, :date, :description, :format, :identifier, :language, :publisher, :relation, :rights, :source, :subject, :title, :type]
+```
+
+## Injection
+This plugin assumes it is in a Blacklight Rails app, uses Blacklight methods, Rails methods, and standard ruby module includes to inject it's behaviors into the app.
+
+You can turn off this injection if you like, although it will make the plugin less (or non-) functional unless you manually do similar injection. See `lib/blacklight_oai_provider.rb#inject!` to see exactly what's going on.
+
+In any initializer, you can set:
+```ruby
+  BlacklightOaiProvider.omit_inject = true
+```
+to turn off all injection. The plugin will be completely non-functional if you do this, of course. But perhaps you could try to re-use some of it's classes in a non-Blacklight, highly hacked Blacklight, or even non-Rails application this way.
+
+You can also turn off injection of individual components, which could be more useful:
+```ruby
+  BlacklightOaiProvider.omit_inject = {
+    :routes => false,
+  }
+```
+## Tests
+We use `engine_cart` and `solr_wrapper` to run tests on a dummy instance of an app using this plugin.
+
+To run the entire test suite:
+```ruby
+  rake ci
+```
+
+You can test OAI-PMH conformance against http://www.openarchives.org/data/registerasprovider.html#Protocol_Conformance_Testing or browse the data at http://re.cs.uct.ac.za/

data/Rakefile

@@ -2,3 +2,28 @@ require 'rake'
 require 'bundler'
 
 Bundler::GemHelper.install_tasks
+
+require 'engine_cart/rake_task'
+require 'solr_wrapper'
+
+task default: [:rubocop, :ci]
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+EngineCart.fingerprint_proc = EngineCart.rails_fingerprint_proc
+
+desc 'Run test suite'
+task ci: ['engine_cart:generate'] do
+  SolrWrapper.wrap do |solr|
+    solr.with_collection(name: 'blacklight-core', dir: File.join(File.expand_path(__dir__), "solr", "conf")) do
+      within_test_app do
+        system "RAILS_ENV=test rake blacklight_oai_provider:index:seed"
+      end
+      Rake::Task['spec'].invoke
+    end
+  end
+end

data/VERSION

@@ -1 +1 @@
-0.1.0
+4.1.0

data/app/assets/{xsl → stylesheets/blacklight_oai_provider}/oai2.xsl

@@ -528,13 +528,20 @@ p.intro {
 <!-- oai resumptionToken -->
 
 <xsl:template match="oai:resumptionToken">
-   <p>There are more results.</p>
-   <table class="values">
-     <tr><td class="key">resumptionToken:</td>
-     <td class="value"><xsl:value-of select="."/>
+  <xsl:choose>
+    <xsl:when test="self::node()[text()]">
+      <p>There are more results.</p>
+      <table class="values">
+        <tr><td class="key">resumptionToken:</td>
+        <td class="value"><xsl:value-of select="."/>
 <xsl:text> </xsl:text>
 <a class="link" href="?verb={/oai:OAI-PMH/oai:request/@verb}&amp;resumptionToken={.}">Resume</a></td></tr>
-   </table>
+      </table>
+    </xsl:when>
+    <xsl:otherwise>
+      <p>End of results.</p>
+    </xsl:otherwise>
+  </xsl:choose>
 </xsl:template>
 
 <!-- unknown metadata format -->

data/app/controllers/concerns/blacklight_oai_provider/controller.rb

@@ -0,0 +1,38 @@
+# Meant to be applied on top of a controller that implements
+# Blacklight::SolrHelper. Will inject range limiting behaviors
+# to solr parameters creation.
+module BlacklightOaiProvider
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :oai_config
+    end
+
+    # Action method of our own!
+    # Delivers a _partial_ that's a display of a single fields range facets.
+    # Used when we need a second Solr query to get range facets, after the
+    # first found min/max from result set.
+    def oai
+      options = params.delete_if { |k, _| %w[controller action].include?(k) }
+      body = oai_provider
+             .process_request(options)
+             .gsub('<?xml version="1.0" encoding="UTF-8"?>') do |m|
+               "#{m}\n<?xml-stylesheet type=\"text/xsl\" href=\"#{ActionController::Base.helpers.asset_path('blacklight_oai_provider/oai2.xsl')}\"?>\n"
+             end
+      render text: body, content_type: 'text/xml'
+    end
+
+    # Uses Blacklight.config, needs to be modified when
+    # that changes to be controller-based. This is the only method
+    # in this plugin that accesses Blacklight.config, single point
+    # of contact.
+    def oai_config
+      blacklight_config.oai || {}
+    end
+
+    def oai_provider
+      @oai_provider ||= BlacklightOaiProvider::SolrDocumentProvider.new(self, oai_config)
+    end
+  end
+end

data/app/models/concerns/blacklight_oai_provider/solr_document.rb

@@ -0,0 +1,23 @@
+module BlacklightOaiProvider
+  module SolrDocument
+    extend ActiveSupport::Concern
+
+    def timestamp
+      timestamp = get(self.class.timestamp_key)
+      raise BlacklightOaiProvider::Exceptions::MissingTimestamp if timestamp.blank?
+      Time.zone.parse(timestamp) # Solr timestamps are all in UTC.
+    end
+
+    def to_oai_dc
+      export_as('oai_dc_xml')
+    end
+
+    module ClassMethods
+      attr_writer :timestamp_key
+
+      def timestamp_key
+        @timestamp_key ||= 'timestamp'
+      end
+    end
+  end
+end

data/blacklight_oai_provider.gemspec

@@ -1,15 +1,19 @@
- # -*- coding: utf-8 -*-
 require File.join(File.dirname(__FILE__), "lib/blacklight_oai_provider/version")
 
 Gem::Specification.new do |s|
   s.name = "blacklight_oai_provider"
   s.version = BlacklightOaiProvider::VERSION
   s.platform = Gem::Platform::RUBY
-  s.authors = ["Chris Beer"]
-  s.email = ["chris@cbeer.info"]
+  s.authors = ["Chris Beer", "Carla Galarza"]
+  s.email = ["chris@cbeer.info", "cmg2228@columbia.edu"]
   s.homepage    = "http://projectblacklight.org/"
   s.summary = "Blacklight Oai Provider plugin"
 
+  s.post_install_message = %q{
+BlacklightOaiProvider v4.1 implements configuration changes. Please visit README for more information.
+
+}
+
   s.rubyforge_project = "blacklight"
 
   s.files         = `git ls-files`.split("\n")
@@ -17,13 +21,16 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-
-  s.add_dependency "rails", "~> 3.0"
-  s.add_dependency "blacklight", "~> 3.2"
+  s.add_dependency "rails", "~> 4.0"
+  s.add_dependency "blacklight", "~> 4.0"
   s.add_dependency "oai"
-  s.add_development_dependency 'rspec'
-  s.add_development_dependency 'rspec-rails'
+  s.add_development_dependency 'rspec-rails', "~> 3.0"
   s.add_development_dependency 'capybara'
-  s.add_development_dependency 'vcr'
-  s.add_development_dependency 'fakeweb'
+  s.add_development_dependency 'solr_wrapper'
+  s.add_development_dependency 'engine_cart'
+  s.add_development_dependency "chromedriver-helper"
+  s.add_development_dependency "selenium-webdriver"
+  s.add_development_dependency 'byebug'
+  s.add_development_dependency 'rubocop', '~> 0.50.0'
+  s.add_development_dependency "rubocop-rspec", '~> 1.18.0'
 end

data/config/initializers/oai_patches.rb

@@ -0,0 +1,20 @@
+# Fix the OAI gem resource identifier format
+# See: https://github.com/code4lib/ruby-oai/issues/38
+
+Rails.application.config.to_prepare do
+  OAI::Provider::Response::RecordResponse.class_eval do
+    private
+
+    def identifier_for(record)
+      "#{provider.prefix}:#{record.id}"
+    end
+  end
+
+  OAI::Provider::Response::Base.class_eval do
+    private
+
+    def extract_identifier(id)
+      id.sub("#{provider.prefix}:", '')
+    end
+  end
+end

data/lib/blacklight_oai_provider/engine.rb

@@ -4,14 +4,27 @@ require 'rails'
 
 module BlacklightOaiProvider
   class Engine < Rails::Engine
-  
     # Do these things in a to_prepare block, to try and make them work
     # in development mode with class-reloading. The trick is we can't
     # be sure if the controllers we're modifying are being reloaded in
     # dev mode, if they are in the BL plugin and haven't been copied to
-    # local, they won't be. But we do our best. 
+    # local, they won't be. But we do our best.
     config.to_prepare do
       BlacklightOaiProvider.inject!
     end
+
+    # Add XSL Stylesheet to list of assets to be precompiled.
+    initializer "blacklight_oai_provider.assets.precompile" do |app|
+      app.config.assets.precompile += %w[blacklight_oai_provider/oai2.xsl]
+    end
+
+    # Load rake tasks.
+    rake_tasks do
+      Dir.chdir(File.expand_path(File.join(File.dirname(__FILE__), '..'))) do
+        Dir.glob(File.join('railties', '*.rake')).each do |railtie|
+          load railtie
+        end
+      end
+    end
   end
 end

data/lib/blacklight_oai_provider/exceptions.rb

@@ -0,0 +1,9 @@
+module BlacklightOaiProvider
+  module Exceptions
+    class MissingTimestamp < StandardError
+      def initialize(msg = "Missing required timestamp field")
+        super
+      end
+    end
+  end
+end

data/lib/blacklight_oai_provider/resumption_token.rb

@@ -0,0 +1,51 @@
+module BlacklightOaiProvider
+  class ResumptionToken < ::OAI::Provider::ResumptionToken
+    # parses a token string and returns a ResumptionToken
+    def self.parse(token_string)
+      options = {}
+      total = nil
+      matches = /(.+):(\d+)$/.match(token_string)
+      options[:last] = matches.captures[1].to_i
+
+      parts = matches.captures[0].split('.')
+      options[:metadata_prefix] = parts.shift
+      parts.each do |part|
+        case part
+        when /^s/
+          options[:set] = part.sub(/^s\(/, '').sub(/\)$/, '')
+        when /^f/
+          options[:from] = parse_date(part.sub(/^f\(/, '').sub(/\)$/, ''))
+        when /^u/
+          options[:until] = parse_date(part.sub(/^u\(/, '').sub(/\)$/, ''))
+        when /^t/
+          total = part.sub(/^t\(/, '').sub(/\)$/, '').to_i
+        end
+      end
+      new(options, nil, total)
+    rescue StandardError
+      raise OAI::ResumptionTokenException
+    end
+
+    # Force date to be in UTC. If date does not have a timezone UTC is assumed.
+    # If date is a different timezone it is converted to UTC.
+    def self.parse_date(str)
+      ActiveSupport::TimeZone.new('UTC').parse(str)
+    end
+
+    def encode_conditions
+      encoded_token = @prefix.to_s.dup
+      encoded_token << ".s(#{set})" if set
+      encoded_token << ".f(#{from.utc.xmlschema})" if from
+      encoded_token << ".u(#{self.until.utc.xmlschema})" if self.until
+      encoded_token << ".t(#{total})" if total
+      encoded_token << ":#{last}"
+    end
+
+    def to_xml
+      xml = Builder::XmlMarkup.new
+      token = total && (last > total) ? '' : encode_conditions
+      xml.resumptionToken(token, hash_of_attributes)
+      xml.target!
+    end
+  end
+end