oai_talia 0.0.13

data/lib/oai/provider/response.rb

@@ -0,0 +1,161 @@
+require 'builder' unless defined?(Builder)
+module OAI
+  module Provider
+    module Response
+
+      class Base
+        attr_reader :provider, :options
+
+        class << self
+          attr_reader :valid_options, :default_options, :required_options
+          def valid_parameters(*args)
+            @valid_options ||= []
+            @valid_options = (@valid_options + args.dup).uniq
+          end
+
+          def default_parameters(options = {})
+            @default_options ||= {}
+            @default_options.merge! options.dup
+          end
+
+          def required_parameters(*args)
+            valid_parameters(*args)
+            @required_options ||= []
+            @required_options = (@required_options + args.dup).uniq
+          end
+        end
+
+        def initialize(provider, options = {})
+          @provider = provider
+          @original_options = options.dup
+          @options = internalize(options)
+          raise OAI::ArgumentException.new unless valid?
+        end
+
+        def response
+          @builder = Builder::XmlMarkup.new
+          @builder.instruct! :xml, :version=>"1.0", :encoding=>"UTF-8"
+          @builder.tag!('OAI-PMH', header) do 
+            @builder.responseDate Time.now.utc.xmlschema
+            #options parameter has been removed here because with it
+            #the data won't validate against oai validators.  Without, it 
+            #validates.  
+            @builder.request(provider.url) #-- OAI 2.0 Hack - removed request options 
+            yield @builder
+          end
+        end
+
+        private
+
+        def header
+          { 
+            'xmlns' => "http://www.openarchives.org/OAI/2.0/",
+            'xmlns:xsi' => "http://www.w3.org/2001/XMLSchema-instance",
+            'xsi:schemaLocation' => %{http://www.openarchives.org/OAI/2.0/
+              http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd}
+            }
+          end
+
+          def extract_identifier(id)
+            id.sub("#{provider.prefix}/", '')
+          end
+
+          def valid?
+            return true if resumption?
+
+            return true if self.class.valid_options.nil? and options.empty?
+
+            if self.class.required_options
+              return false unless (self.class.required_options - @options.keys).empty?
+            end
+
+            return false if !@options.keys.empty? && (self.class.valid_options.nil? || self.class.valid_options.empty?)
+            return false unless (@options.keys - self.class.valid_options).empty?
+            return false unless valid_times?
+            return false unless valid_format?
+            populate_defaults
+            true
+          end
+
+          def valid_format?
+            return true if @options[:metadata_prefix].nil?
+            raise OAI::FormatException.new unless provider.format_supported?(@options[:metadata_prefix])
+            true
+          end
+
+          def valid_times?
+
+            if (@original_options[:from].nil? || 
+              @original_options[:from] =~ /^\d\d\d\d-\d\d-\d\d(T\d\d:\d\d:\d\dZ)?/  ||
+              @original_options[:from].instance_of?(Time))
+
+
+              if (@original_options[:until].nil? || 
+                @original_options[:until] =~ /^\d\d\d\d-\d\d-\d\d(T\d\d:\d\d:\d\dZ)?/ ||
+                @original_options[:until].instance_of?(Time))
+              else
+                return false
+              end
+            else
+              return false
+            end
+            # if dates are not nil and are strings, make sure they're the same length
+            # testing granularity
+            if ((!@original_options[:from].nil? && @original_options[:from].respond_to?(:length)) && 
+              (!@original_options[:until].nil? && @original_options[:until].respond_to?(:length)))
+              if @original_options[:from].length != @original_options[:until].length
+                return false
+              end
+
+            end
+
+            true
+          end
+
+          def populate_defaults
+            self.class.default_options.each do |k,v|
+              @options[k] = v.respond_to?(:call) ? v.call(self) : v if not @options[k]
+            end
+          end
+
+          def resumption?
+            if @options.keys.include?(:resumption_token) 
+              return true if 1 == @options.keys.size
+              raise OAI::ArgumentException.new
+            end
+          end
+
+          # Convert our internal representations back into standard OAI options
+          def externalize(value)
+            value.to_s.gsub(/_[a-z]/) { |m| m.sub("_", '').capitalize }
+          end
+
+          def parse_date(value)
+            return value if value.respond_to?(:strftime)
+
+            Date.parse(value) # This will raise an exception for badly formatted dates
+            Time.parse(value).utc #  -- UTC Bug fix hack 8/08 not in core
+          rescue
+            raise OAI::ArgumentException.new 
+          end
+
+          def internalize(hash = {})
+            internal = {}
+            hash.keys.each do |key|
+              internal[key.to_s.gsub(/([A-Z])/, '_\1').downcase.intern] = hash[key].dup
+            end
+
+            # Convert date formated strings into internal time values
+            # Convert date formated strings in dates.
+            internal[:from] = parse_date(internal[:from]) if internal[:from]
+            internal[:until] = parse_date(internal[:until]) if internal[:until]
+
+            internal
+          end
+
+        end
+
+      end
+    end
+  end
+

data/lib/oai/provider/resumption_token.rb

@@ -0,0 +1,106 @@
+require 'time'
+require 'enumerator'
+require File.dirname(__FILE__) + "/partial_result"
+
+module OAI::Provider
+  # = OAI::Provider::ResumptionToken
+  #
+  # The ResumptionToken class forms the basis of paging query results.  It
+  # provides several helper methods for dealing with resumption tokens.
+  #
+  class ResumptionToken
+    attr_reader :prefix, :set, :from, :until, :last, :expiration, :total
+
+    # parses a token string and returns a ResumptionToken
+    def self.parse(token_string)
+      begin
+        options = {}
+        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] = Time.parse(part.sub(/^f\(/, '').sub(/\)$/, '')).localtime
+          when /^u/
+            options[:until] = Time.parse(part.sub(/^u\(/, '').sub(/\)$/, '')).localtime
+          end
+        end
+        self.new(options)
+      rescue => err
+        raise ResumptionTokenException.new
+      end
+    end
+    
+    # extracts the metadata prefix from a token string
+    def self.extract_format(token_string)
+      return token_string.split('.')[0]
+    end
+
+    def initialize(options, expiration = nil, total = nil)
+      @prefix = options[:metadata_prefix]
+      @set = options[:set]
+      @last = options[:last]
+      @from = options[:from] if options[:from]
+      @until = options[:until] if options[:until]
+      @expiration = expiration if expiration
+      @total = total if total
+    end
+          
+    # convenience method for setting the offset of the next set of results
+    def next(last)
+      @last = last
+      self
+    end
+    
+    def ==(other)
+      prefix == other.prefix and set == other.set and from == other.from and
+        self.until == other.until and last == other.last and 
+        expiration == other.expiration and total == other.total
+    end
+    
+    # output an xml resumption token
+    def to_xml
+      xml = Builder::XmlMarkup.new
+      xml.resumptionToken(encode_conditions, hash_of_attributes)
+      xml.target!
+    end
+    
+    # return a hash containing just the model selection parameters
+    def to_conditions_hash
+      conditions = {:metadata_prefix => self.prefix }
+      conditions[:set] = self.set if self.set
+      conditions[:from] = self.from if self.from
+      conditions[:until] = self.until if self.until
+      conditions
+    end
+    
+    # return the a string representation of the token minus the offset
+    def to_s
+      encode_conditions.gsub(/:\w+?$/, '')
+    end
+
+    private
+    
+    def encode_conditions
+      encoded_token = @prefix.to_s.dup
+      encoded_token << ".s(#{set})" if set
+      encoded_token << ".f(#{self.from.utc.xmlschema})" if self.from
+      encoded_token << ".u(#{self.until.utc.xmlschema})" if self.until
+      encoded_token << ":#{last}"
+    end
+
+    def hash_of_attributes
+      attributes = {}
+      attributes[:completeListSize] = self.total if self.total
+      attributes[:expirationDate] = self.expiration.utc.xmlschema if self.expiration
+      attributes
+    end
+
+  end
+
+end

data/lib/oai/provider.rb

@@ -0,0 +1,304 @@
+require 'rexml/document'
+require 'singleton'
+require 'builder'
+
+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)
+        if @formats[prefix].nil?
+          raise OAI::FormatException.new
+        else
+          @formats[prefix]
+        end
+      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 1, 2005', 
+    #    :until => 'November 1, 2005') 
+    #
+    # 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/set.rb

@@ -0,0 +1,29 @@
+module OAI
+  
+  # bundles up information about a set retrieved during a 
+  # ListSets request
+  
+  class Set
+    include OAI::XPath
+    attr_accessor :name, :spec, :description
+
+    def initialize(values = {})
+      @name = values.delete(:name)
+      @spec = values.delete(:spec)
+      @description = values.delete(:description)
+      raise ArgumentException, "Invalid options" unless values.empty?
+    end
+    
+    def self.parse(element)
+      set = self.new
+      set.name = set.xpath(element, './/setName')
+      set.spec = set.xpath(element, './/setSpec')
+      set.description = set.xpath_first(element, './/setDescription')
+      set
+    end
+    
+    def to_s
+      "#{@name} [#{@spec}]"
+    end
+  end
+end

data/lib/oai/xpath.rb

@@ -0,0 +1,75 @@
+module OAI
+  module XPath
+
+    # get all matching nodes
+    def xpath_all(doc, path)
+      case parser_type(doc)
+      when 'libxml'
+        return doc.find(path).to_a if doc.find(path)
+      when 'rexml'
+        return REXML::XPath.match(doc, path)
+      end
+      return []
+    end
+
+    # get first matching node
+    def xpath_first(doc, path)
+      elements = xpath_all(doc, path)
+      return elements[0] if elements != nil
+      return nil
+    end
+
+    # get text for first matching node
+    def xpath(doc, path)
+      el = xpath_first(doc, path)
+      return unless el
+      case parser_type(doc)
+      when 'libxml'
+        return el.content
+      when 'rexml'
+        return el.text 
+      end
+      return nil
+    end
+
+    # figure out an attribute
+    def get_attribute(node, attr_name)
+      case node.class.to_s
+      when 'REXML::Element'
+        return node.attribute(attr_name)
+      when 'LibXML::XML::Node'
+  	#There has been a method shift between 0.5 and 0.7
+        if defined?(node.property) == nil
+          return node.attributes[attr_name]
+        else
+	  #node.property is being deprecated.  We'll eventually remove
+	  #this trap
+	  begin
+	    return node[attr_name]
+          rescue
+             return node.property(attr_name)
+          end
+        end	
+      end
+      return nil
+    end
+
+    private 
+   
+    # figure out what sort of object we should do xpath on
+    def parser_type(x)
+      case x.class.to_s
+      when 'LibXML::XML::Document'
+        return 'libxml'
+      when 'LibXML::XML::Node'
+        return 'libxml'
+      when 'LibXML::XML::Node::Set'
+	return 'libxml'
+      when 'REXML::Element'
+        return 'rexml'
+      when 'REXML::Document'
+        return 'rexml'
+      end
+    end
+  end
+end

data/lib/oai.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'date'
+
+# Sub projects (client, provider) require their own libraries so the user
+# can selectively load them.
+require 'oai/client'
+require 'oai/provider'
+