blacklight_oai_provider 0.0.1pre1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,73 @@
+BlacklightOaiProvider: OAI-PMH service endpoint for Blacklight applications
+
+= Description
+
+The BlacklightOaiProvider plugin provides an Open Archives Initiative Protocolo for Metadata Harvesting (OAI-PMH) <http://www.openarchives.org/pmh/> data provider endpoint, using the ruby-oai gem, that let serice providers harvest that metadata.
+
+= Requirements
+
+A Rails app using Blacklight 3.x.
+
+OAI-PMH requires a timestamp field for all records, so your Solr index should include an appropriate field. By default, the name of this field is simply 'timestamp'.
+
+= Installation
+
+Add
+
+    gem "blacklight_oai_provider"
+
+to your Gemfile and  run "bundle install".
+
+Then run "rails generate blacklight_oai_provider" to install the appropriate extensions into your CatalogController and SolrDocument classes. In you want to do customize the way this installs, instead you may:
+
+- add this to your Solr Document model:
+    
+    use_extension(BlacklightOaiProvider::SolrDocumentExtension)
+
+- add this to your Controler:
+
+
+
+= Configuration
+
+While the plugin provides some sensible (albeit generic) defaults out of the box, you probably will want to customize the OAI provider configuration. You can provide OAI-PMH provider parameters by placing the following in your blacklight configuration (in ./config/initializers/blacklight_config.rb), e.g.:
+
+config[:oai] = {
+    :provider => {
+      :repository_name => 'Test',
+      :repository_url => 'http://localhost',
+      :record_prefix => '',
+      :admin_email => 'root@localhost'
+    },
+    :document => {
+      :timestamp => 'timestamp',
+      :limit => 25
+    }
+  }
+
+The "provider" configuration is documented as part of the ruby-oai gem at http://oai.rubyforge.org/
+
+
+== 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:
+
+  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:
+   
+  BlacklightOaiProvider.omit_inject = {
+    :routes => false,
+  }
+
+= Tests
+
+There are none. This is bad I know, sorry. 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

@@ -0,0 +1,4 @@
+require 'rake'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks

data/VERSION

@@ -0,0 +1 @@
+0.0.1pre1

data/blacklight_oai_provider.gemspec

@@ -0,0 +1,24 @@
+ # -*- 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_beer@wgbh.org"]
+  s.homepage    = "http://projectblacklight.org/"
+  s.summary = "Blacklight Oai Provider plugin"
+
+  s.rubyforge_project = "blacklight"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  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"
+  s.add_dependency "oai"
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# We want to add a new collection action to Catalog, without over-writing
+# what's already there. This SEEMS to do it. 
+Rails.application.routes.draw do
+end
+

data/lib/blacklight_oai_provider/controller_extension.rb

@@ -0,0 +1,29 @@
+# Meant to be applied on top of a controller that implements
+# Blacklight::SolrHelper. Will inject range limiting behaviors
+# to solr parameters creation. 
+module BlacklightOaiProvider::ControllerExtension
+  def self.included(some_class)
+    some_class.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,v| %w{controller action}.include?(k) }
+    render :text => oai_provider.process_request(options), :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

data/lib/blacklight_oai_provider/engine.rb

@@ -0,0 +1,17 @@
+require 'blacklight'
+require 'blacklight_range_limit'
+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. 
+    config.to_prepare do
+      BlacklightOaiProvider.inject!
+    end
+  end
+end

data/lib/blacklight_oai_provider/route_sets.rb

@@ -0,0 +1,13 @@
+module BlacklightOaiProvider
+  module RouteSets
+    protected
+    def catalog
+      add_routes do |options|
+        match 'catalog/oai' => 'catalog#oai', :as => 'oai_provider'
+      end
+
+      super
+    end
+  end
+end
+

data/lib/blacklight_oai_provider/solr_document_extension.rb

@@ -0,0 +1,10 @@
+# Meant to be applied on top of SolrDocument to implement
+# methods required by the ruby-oai provider
+module BlacklightOaiProvider::SolrDocumentExtension
+  def timestamp
+    Time.parse get('timestamp')
+  end
+  def to_oai_dc
+    export_as('oai_dc_xml')
+  end
+end

data/lib/blacklight_oai_provider/solr_document_provider.rb

@@ -0,0 +1,19 @@
+module BlacklightOaiProvider
+  class SolrDocumentProvider < ::OAI::Provider::Base
+    attr_accessor :options
+    def initialize controller, options = {}
+
+      options[:provider] ||= {}
+      options[:document] ||= {}
+
+      self.class.model = SolrDocumentWrapper.new(controller, options[:document])
+
+      options[:repository_name] ||= controller.view_context.send(:application_name)
+      options[:repository_url] ||= controller.view_context.send(:oai_provider_url)
+
+      options[:provider].each do |k,v|
+        self.class.send k, v
+      end
+    end
+  end
+end

data/lib/blacklight_oai_provider/solr_document_wrapper.rb

@@ -0,0 +1,58 @@
+module BlacklightOaiProvider
+  class SolrDocumentWrapper < ::OAI::Provider::Model
+    attr_reader :model, :timestamp_field
+    attr_accessor :options, :extra_controller_params
+    def initialize(controller, options = {})
+      @controller = controller
+
+      defaults = { :timestamp => 'timestamp', :limit => 15} 
+      @options = defaults.merge options
+
+      @timestamp_field = @options[:timestamp]
+      @limit = @options[:limit]
+      @extra_controller_params = {}
+    end
+
+    def sets
+    end
+
+    def earliest
+      Time.parse @controller.get_search_results({:sort => @timestamp_field +' asc', :rows => 1}, extra_controller_params).last.first.get(@timestamp_field)
+    end
+
+    def latest
+      Time.parse @controller.get_search_results({:sort => @timestamp_field +' desc', :rows => 1}, extra_controller_params).last.first.get(@timestamp_field)
+    end
+
+    def find(selector, options={})
+      return next_set(options[:resumption_token]) if options[:resumption_token]
+
+      if :all == selector
+        response, records = @controller.get_search_results({:sort => @timestamp_field + ' asc', :per_page => @limit}, extra_controller_params)
+
+        if @limit && response.total >= @limit
+          return select_partial(OAI::Provider::ResumptionToken.new(options.merge({:last => 0})))
+        end
+      else                                                    
+        records = @controller.get_search_results({:phrase_filters => {:id => selector.split('/', 2).last}}, extra_controller_params).last.first
+      end
+      records
+    end
+
+    def select_partial token
+      records = @controller.get_search_results({:sort => @timestamp_field + ' asc', :per_page => @limit, :page => token.last}, extra_controller_params).last
+
+      raise ::OAI::ResumptionTokenException.new unless records
+
+      OAI::Provider::PartialResult.new(records, token.next(token.last+1))
+    end
+
+    def next_set(token_string)
+      raise ::OAI::ResumptionTokenException.new unless @limit
+
+      token = OAI::Provider::ResumptionToken.parse(token_string)
+      select_partial(token)
+    end
+  end
+end
+

data/lib/blacklight_oai_provider/version.rb

@@ -0,0 +1,10 @@
+module BlacklightOaiProvider
+  unless BlacklightOaiProvider.const_defined? :VERSION
+    def self.version
+      @version ||= File.read(File.join(File.dirname(__FILE__), '..', '..', 'VERSION')).chomp
+    end
+
+    VERSION = self.version
+  end
+end
+

data/lib/blacklight_oai_provider.rb

@@ -0,0 +1,33 @@
+# BlacklightOaiProvider
+
+module BlacklightOaiProvider
+
+  autoload :ControllerExtension, 'blacklight_oai_provider/controller_extension'
+  autoload :SolrDocumentExtension, 'blacklight_oai_provider/solr_document_extension'
+  autoload :SolrDocumentProvider, 'blacklight_oai_provider/solr_document_provider'
+  autoload :SolrDocumentWrapper, 'blacklight_oai_provider/solr_document_wrapper'
+  autoload :RouteSets, 'blacklight_oai_provider/route_sets'
+
+  require 'oai'
+  require 'blacklight_oai_provider/version'
+  require 'blacklight_oai_provider/engine'
+  
+  @omit_inject = {}
+  def self.omit_inject=(value)
+    value = Hash.new(true) if value == true
+    @omit_inject = value      
+  end
+  def self.omit_inject ; @omit_inject ; end
+  
+  def self.inject!
+    unless BlacklightRangeLimit.omit_inject[:routes]
+      Blacklight::Routes.send(:include, BlacklightOaiProvider::RouteSets)
+    end
+  end
+
+  # Add element to array only if it's not already there
+  def self.safe_arr_add(array, element)
+    array << element unless array.include?(element)
+  end
+  
+end

data/lib/generators/blacklight_oai_provider/blacklight_oai_provider_generator.rb

@@ -0,0 +1,27 @@
+require 'rails/generators'
+
+class BlacklightOaiProviderGenerator < Rails::Generators::Base
+
+  argument :model_name, :type => :string, :default => "SolrDocument"
+  argument :controller_name, :type => :string, :default => "CatalogController"
+
+  def inject_solr_document_extension
+    file_path = "app/models/#{model_name.underscore}.rb"
+
+    if File.exists? file_path
+      inject_into_file file_path, :after => "include Blacklight::Solr::Document" do
+        "\n  SolrDocument.use_extension( BlacklightOaiProvider::SolrDocumentExtension )\n"
+      end
+    end
+  end
+
+  def inject_catalog_controller_extension
+    file_path = "app/controllers/#{controller_name.underscore}.rb"
+    if File.exists? file_path
+      inject_into_file file_path, :after => "include Blacklight::Catalog" do
+        "\n  include BlacklightOaiProvider::ControllerExtension\n"
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: blacklight_oai_provider
+version: !ruby/object:Gem::Version
+  version: 0.0.1pre1
+  prerelease: 5
+platform: ruby
+authors:
+- Chris Beer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-07-22 00:00:00.000000000 -04:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &2153081380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2153081380
+- !ruby/object:Gem::Dependency
+  name: blacklight
+  requirement: &2153080820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2153080820
+- !ruby/object:Gem::Dependency
+  name: oai
+  requirement: &2153080220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2153080220
+description: 
+email:
+- chris_beer@wgbh.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- blacklight_oai_provider.gemspec
+- config/routes.rb
+- lib/blacklight_oai_provider.rb
+- lib/blacklight_oai_provider/README.rdoc
+- lib/blacklight_oai_provider/controller_extension.rb
+- lib/blacklight_oai_provider/engine.rb
+- lib/blacklight_oai_provider/route_sets.rb
+- lib/blacklight_oai_provider/solr_document_extension.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/blacklight_oai_provider_generator.rb
+has_rdoc: true
+homepage: http://projectblacklight.org/
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: blacklight
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Blacklight Oai Provider plugin
+test_files: []