oai 0.0.3 → 0.0.4

data/lib/oai/provider.rb

@@ -0,0 +1,300 @@
+require 'active_support'
+require 'builder'
+require 'chronic'
+
+if not defined?(OAI::Const::VERBS)
+  require 'oai/exception'
+  require 'oai/constants'
+  require 'oai/xpath'
+  require 'oai/set'
+end
+
+%w{ response metadata_format resumption_token model partial_result
+    response/record_response response/identify response/get_record
+    response/list_identifiers response/list_records 
+    response/list_metadata_formats response/list_sets response/error
+  }.each { |lib| require File.dirname(__FILE__) + "/provider/#{lib}" }
+  
+if defined?(ActiveRecord)
+  require File.dirname(__FILE__) + "/provider/model/activerecord_wrapper"
+  require File.dirname(__FILE__) + "/provider/model/activerecord_caching_wrapper"
+end
+
+# = OAI::Provider
+#
+# Open Archives Initiative - Protocol for Metadata Harvesting see 
+# http://www.openarchives.org/ 
+#
+# == Features
+# * Easily setup a simple repository
+# * Simple integration with ActiveRecord
+# * Dublin Core metadata format included
+# * Easily add addition metadata formats
+# * Adaptable to any data source
+# * Simple resumption token support
+#
+# == Usage
+#
+# To create a functional provider either subclass Provider::Base, 
+# or reconfigure the defaults.
+# 
+# === Sub classing a provider
+#
+#  class MyProvider < Oai::Provider
+#    repository_name 'My little OAI provider'
+#    repository_url  'http://localhost/provider'
+#    record_prefix 'oai:localhost'
+#    admin_email 'root@localhost'   # String or Array
+#    source_model MyModel.new       # Subclass of OAI::Provider::Model
+#  end
+#
+# === Configuring the default provider
+#
+#  class Oai::Provider::Base
+#    repository_name 'My little OAI Provider'
+#    repository_url 'http://localhost/provider'
+#    record_prefix 'oai:localhost'
+#    admin_email 'root@localhost'
+#    source_model MyModel.new
+#  end
+#
+# The provider does allow a URL to be passed in at request processing time
+# in case the repository URL cannot be determined ahead of time.
+#
+# == Integrating with frameworks
+#
+# === Camping
+#
+# In the Models module of your camping application post model definition:
+# 
+#   class CampingProvider < OAI::Provider::Base
+#     repository_name 'Camping Test OAI Repository'
+#     source_model ActiveRecordWrapper.new(YOUR_ACTIVE_RECORD_MODEL)
+#   end
+#
+# In the Controllers module:
+#
+#   class Oai
+#     def get
+#       @headers['Content-Type'] = 'text/xml'
+#       provider = Models::CampingProvider.new
+#       provider.process_request(@input.merge(:url => "http:"+URL(Oai).to_s))
+#     end
+#   end
+#
+# The provider will be available at "/oai"
+#
+# === Rails
+#
+# At the bottom of environment.rb create a OAI Provider:
+#
+#   # forgive the standard blog example.
+# 
+#   require 'oai'
+#   class BlogProvider < OAI::Provider::Base
+#     repository_name 'My little OAI Provider'
+#     repository_url 'http://localhost:3000/provider'
+#     record_prefix 'oai:blog'
+#     admin_email 'root@localhost'
+#     source_model OAI::Provider::ActiveRecordWrapper.new(Post)
+#   end
+#
+# Create a custom controller:
+#
+#   class OaiController < ApplicationController
+#     def index
+#       # Remove controller and action from the options.  Rails adds them automatically.
+#       options = params.delete_if { |k,v| %w{controller action}.include?(k) }
+#       provider = BlogProvider.new
+#       response =  provider.process_request(options)
+#       render :text => response, :content_type => 'text/xml'
+#     end
+#   end
+#
+# Special thanks to Jose Hales-Garcia for this solution. 
+#
+# == Supporting custom metadata formats
+#
+# See Oai::Metadata for details.
+# 
+# == ActiveRecord Integration
+#
+# ActiveRecord integration is provided by the ActiveRecordWrapper class.
+# It takes one required paramater, the class name of the AR class to wrap,
+# and optional hash of options.
+#
+# Valid options include:
+# * timestamp_field - Specifies the model field to use as the update
+#   filter.  Defaults to 'updated_at'.
+# * limit -           Maximum number of records to return in each page/set.
+#   Defaults to 100.  The wrapper will paginate the result via resumption tokens.  
+#   Caution:  specifying too large a limit will adversely affect performance.
+# 
+# Mapping from a ActiveRecord object to a specific metadata format follows
+# this set of rules:
+#
+# 1. Does Model#to_{metadata_prefix} exist?  If so just return the result.
+# 2. Does the model provide a map via Model.map_{metadata_prefix}?  If so
+#    use the map to generate the xml document.
+# 3. Loop thru the fields of the metadata format and check to see if the
+#    model responds to either the plural, or singular of the field.
+#
+# For maximum control of the xml metadata generated, it's usually best to
+# provide a 'to_{metadata_prefix}' in the model.  If using Builder be sure
+# not to include any instruct! in the xml object.
+#  
+# === Explicit creation example 
+#
+#  class Post < ActiveRecord::Base
+#    def to_oai_dc
+#      xml = Builder::XmlMarkup.new
+#      xml.tag!("oai_dc:dc", 
+#        'xmlns:oai_dc' => "http://www.openarchives.org/OAI/2.0/oai_dc/",
+#        'xmlns:dc' => "http://purl.org/dc/elements/1.1/",
+#        'xmlns:xsi' => "http://www.w3.org/2001/XMLSchema-instance",
+#        'xsi:schemaLocation' => 
+#          %{http://www.openarchives.org/OAI/2.0/oai_dc/ 
+#            http://www.openarchives.org/OAI/2.0/oai_dc.xsd}) do
+#          xml.tag!('oai_dc:title', title)
+#          xml.tag!('oai_dc:description', text)
+#          xml.tag!('oai_dc:creator', user)
+#          tags.each do |tag|
+#            xml.tag!('oai_dc:subject', tag)
+#          end
+#      end
+#      xml.target!
+#    end
+#  end  
+#
+# === Mapping Example
+#
+#  # Extremely contrived mapping
+#  class Post < ActiveRecord::Base
+#    def self.map_oai_dc
+#      {:subject => :tags, 
+#       :description => :text, 
+#       :creator => :user, 
+#       :contibutor => :comments}
+#    end
+#  end
+#
+module OAI::Provider
+  class Base
+    include OAI::Provider
+    
+    class << self
+      attr_reader :formats
+      attr_accessor :name, :url, :prefix, :email, :delete_support, :granularity, :model
+
+      def register_format(format)
+        @formats ||= {}
+        @formats[format.prefix] = format
+      end
+      
+      def format_supported?(prefix)
+        @formats.keys.include?(prefix)
+      end
+      
+      def format(prefix)
+        @formats[prefix]
+      end
+
+      protected 
+      
+      def inherited(klass)
+        self.instance_variables.each do |iv|
+          klass.instance_variable_set(iv, self.instance_variable_get(iv))
+        end
+      end
+
+      alias_method :repository_name,    :name=
+      alias_method :repository_url,     :url=
+      alias_method :record_prefix,      :prefix=
+      alias_method :admin_email,        :email=
+      alias_method :deletion_support,   :delete_support=  
+      alias_method :update_granularity, :granularity=     
+      alias_method :source_model,       :model=
+      
+    end
+
+    # Default configuration of a repository
+    Base.repository_name 'Open Archives Initiative Data Provider'
+    Base.repository_url 'unknown'
+    Base.record_prefix 'oai:localhost'
+    Base.admin_email 'nobody@localhost'
+    Base.deletion_support OAI::Const::Delete::TRANSIENT
+    Base.update_granularity OAI::Const::Granularity::HIGH
+
+    Base.register_format(OAI::Provider::Metadata::DublinCore.instance)
+    
+    # Equivalent to '&verb=Identify', returns information about the repository
+    def identify(options = {})
+      Response::Identify.new(self.class, options).to_xml
+    end
+
+    # Equivalent to '&verb=ListSets', returns a list of sets that are supported
+    # by the repository or an error if sets are not supported.
+    def list_sets(options = {})
+      Response::ListSets.new(self.class, options).to_xml
+    end
+    
+    # Equivalent to '&verb=ListMetadataFormats', returns a list of metadata formats
+    # supported by the repository.
+    def list_metadata_formats(options = {})
+      Response::ListMetadataFormats.new(self.class, options).to_xml
+    end
+
+    # Equivalent to '&verb=ListIdentifiers', returns a list of record headers that 
+    # meet the supplied criteria.
+    def list_identifiers(options = {})
+      Response::ListIdentifiers.new(self.class, options).to_xml
+    end
+    
+    # Equivalent to '&verb=ListRecords', returns a list of records that meet the 
+    # supplied criteria.
+    def list_records(options = {})
+      Response::ListRecords.new(self.class, options).to_xml
+    end
+    
+    # Equivalent to '&verb=GetRecord', returns a record matching the required
+    # :identifier option 
+    def get_record(options = {})
+      Response::GetRecord.new(self.class, options).to_xml
+    end
+    
+    #  xml_response = process_verb('ListRecords', :from => 'October', 
+    #    :until => 'November') # thanks Chronic!
+    #
+    # If you are implementing a web interface using process_request is the
+    # preferred way.
+    def process_request(params = {})
+      begin
+
+        # Allow the request to pass in a url
+        self.class.url = params['url'] ? params.delete('url') : self.class.url
+          
+        verb = params.delete('verb') || params.delete(:verb)
+        
+        unless verb and OAI::Const::VERBS.keys.include?(verb)
+          raise OAI::VerbException.new
+        end
+          
+        send(methodize(verb), params) 
+
+      rescue => err
+        if err.respond_to?(:code)
+          Response::Error.new(self.class, err).to_xml
+        else
+          raise err
+        end
+      end
+    end
+    
+    # Convert valid OAI-PMH verbs into ruby method calls
+    def methodize(verb)
+      verb.gsub(/[A-Z]/) {|m| "_#{m.downcase}"}.sub(/^\_/,'')
+    end
+    
+  end
+  
+end

data/lib/oai/provider/metadata_format.rb

@@ -0,0 +1,72 @@
+module OAI::Provider::Metadata
+  # == Metadata Base Class
+  #
+  # MetadataFormat is the base class from which all other format classes 
+  # should inherit.  Format classes provide mapping of record fields into XML.
+  #
+  # * prefix - contains the metadata_prefix used to select the format
+  # * schema - location of the xml schema
+  # * namespace - location of the namespace document
+  # * element_namespace - the namespace portion of the XML elements
+  # * fields - list of fields in this metadata format
+  #
+  # See OAI::Metadata::DublinCore for an example
+  #
+  class Format
+    include Singleton
+    
+    attr_accessor :prefix, :schema, :namespace, :element_namespace, :fields
+    
+    # Provided a model, and a record belonging to that model this method
+    # will return an xml represention of the record.  This is the method
+    # that should be extended if you need to create more complex xml
+    # representations.
+    def encode(model, record)
+      if record.respond_to?("to_#{prefix}")
+        record.send("to_#{prefix}")
+      else
+        xml = Builder::XmlMarkup.new
+        map = model.respond_to?("map_#{prefix}") ? model.send("map_#{prefix}") : {}
+          xml.tag!("#{prefix}:#{element_namespace}", header_specification) do
+            fields.each do |field|
+              values = value_for(field, record, map)
+              values.each do |value|
+                xml.tag! "#{element_namespace}:#{field}", value
+              end
+            end
+          end
+        xml.target!
+      end
+    end
+
+    private
+
+    # We try a bunch of different methods to get the data from the model.
+    #
+    # 1.  Check if the model defines a field mapping for the field of 
+    #     interest.
+    # 2.  Try calling the pluralized name method on the model.
+    # 3.  Try calling the singular name method on the model
+    def value_for(field, record, map)
+      method = map[field] ? map[field].to_s : field.to_s
+      
+      methods = record.public_methods(false)
+      if methods.include?(method.pluralize)
+        record.send method.pluralize
+      elsif methods.include?(method)
+        record.send method
+      else
+        []
+      end
+    end
+
+    # Subclasses must override
+    def header_specification
+      raise NotImplementedError.new
+    end
+
+  end
+  
+end
+
+Dir.glob(File.dirname(__FILE__) + '/metadata_format/*.rb').each {|lib| require lib}

data/lib/oai/provider/metadata_format/oai_dc.rb

@@ -0,0 +1,29 @@
+module OAI::Provider::Metadata
+  # = OAI::Metadata::DublinCore
+  # 
+  # Simple implementation of the Dublin Core metadata format.
+  class DublinCore < Format
+    
+    def initialize
+      @prefix = 'oai_dc'
+      @schema = 'http://www.openarchives.org/OAI/2.0/oai_dc.xsd'
+      @namespace = 'http://www.openarchives.org/OAI/2.0/oai_dc/'
+      @element_namespace = 'dc'
+      @fields = [ :title, :creator, :subject, :description, :publisher,
+                  :contributor, :date, :type, :format, :identifier,
+                  :source, :language, :relation, :coverage, :rights]
+    end
+
+    def header_specification
+      {
+        'xmlns:oai_dc' => "http://www.openarchives.org/OAI/2.0/oai_dc/",
+        'xmlns:dc' => "http://purl.org/dc/elements/1.1/",
+        'xmlns:xsi' => "http://www.w3.org/2001/XMLSchema-instance",
+        'xsi:schemaLocation' => 
+          %{http://www.openarchives.org/OAI/2.0/oai_dc/ 
+            http://www.openarchives.org/OAI/2.0/oai_dc.xsd}            
+      }
+    end
+
+  end
+end

data/lib/oai/provider/model.rb

@@ -0,0 +1,71 @@
+module OAI::Provider
+  # = OAI::Provider::Model
+  #
+  # Model implementers should subclass OAI::Provider::Model and override 
+  # Model#earliest, Model#latest, and Model#find.  Optionally Model#sets and
+  # Model#deleted? can be used to support sets and record deletions.  It 
+  # is also the responsibility of the model implementer to account for 
+  # resumption tokens if support is required.  Models that don't support 
+  # resumption tokens should raise an exception if a limit is requested     
+  # during initialization.
+  #
+  # earliest - should return the earliest update time in the repository.
+  # latest - should return the most recent update time in the repository.
+  # sets - should return an array of sets supported by the repository.
+  # deleted? - individual records returned should respond true or false
+  # when sent the deleted? message.
+  #
+  # == Resumption Tokens
+  #
+  # For examples of using resumption tokens see the
+  # ActiveRecordWrapper, and ActiveRecordCachingWrapper classes.
+  #
+  # There are several helper models for dealing with resumption tokens please
+  # see the ResumptionToken class for more details.
+  #
+
+  class Model
+    attr_reader :timestamp_field
+    
+    def initialize(limit = nil, timestamp_field = 'updated_at')
+      @limit = limit
+      @timestamp_field = timestamp_field
+    end
+
+    # should return the earliest timestamp available from this model.
+    def earliest
+      raise NotImplementedError.new
+    end
+    
+    # should return the latest timestamp available from this model.
+    def latest
+      raise NotImplementedError.new
+    end
+    
+    def sets
+      nil
+    end
+  
+    # find is the core method of a model, it returns records from the model
+    # bases on the parameters passed in.
+    #
+    # <tt>selector</tt> can be a singular id, or the symbol :all
+    # <tt>options</tt> is a hash of options to be used to constrain the query.
+    #
+    # Valid options:
+    # * :from => earliest timestamp to be included in the results
+    # * :until => latest timestamp to be included in the results
+    # * :set => the set from which to retrieve the results
+    # * :metadata_prefix => type of metadata requested (this may be useful if 
+    #                       not all records are available in all formats)
+    def find(selector, options={})
+      raise NotImplementedError.new
+    end
+    
+    def deleted?
+      false
+    end
+    
+  end
+  
+end