oai 0.0.1 → 1.3.0

data/lib/oai/provider/response/list_metadata_formats.rb

@@ -0,0 +1,39 @@
+module OAI::Provider::Response
+  class ListMetadataFormats < RecordResponse
+    valid_parameters :identifier
+    
+    def to_xml
+      # Get a list of all the formats the provider understands.
+      formats = provider.formats.values
+      
+      # if it's a doc-specific request
+      if options.include?(:identifier)
+        id = extract_identifier(options[:identifier])
+        unless record = provider.model.find(id, options)
+          raise OAI::IdException.new
+        end
+      
+        # Remove any format that this particular record can't be provided in.
+        formats.reject! { |f| !record_supports(record, f.prefix) }
+      end
+      response do |r|
+        r.ListMetadataFormats do
+          formats.each do |format|
+            r.metadataFormat do 
+              r.metadataPrefix format.prefix
+              r.schema format.schema
+              r.metadataNamespace format.namespace
+            end
+          end
+        end
+      end
+    end
+    
+    def record_supports(record, prefix)
+      prefix == 'oai_dc' or 
+      record.respond_to?("to_#{prefix}") or
+      record.respond_to?("map_#{prefix}")
+    end
+    
+  end  
+end

data/lib/oai/provider/response/list_records.rb

@@ -0,0 +1,47 @@
+module OAI::Provider::Response
+
+  class ListRecords < RecordResponse
+    required_parameters :metadata_prefix
+    
+    def valid?
+      super && matching_granularity?
+    end
+    
+    def matching_granularity?
+      if options[:from].nil? == false && options[:until].nil? == false && options[:from].class.name != options[:until].class.name
+        raise OAI::ArgumentException.new, "The 'from' and 'until' options specified must have the same granularity"
+      else
+        true
+      end
+    end
+
+    def to_xml
+      result = provider.model.find(:all, options)
+      # result may be an array of records, or a partial result
+      records = result.respond_to?(:records) ? result.records : result
+
+      raise OAI::NoMatchException.new if records.nil? or records.empty?
+
+      response do |r|
+        r.ListRecords do
+          records.each do |rec|
+            r.record do
+              header_for rec
+              data_for rec unless deleted?(rec)
+              about_for rec unless deleted?(rec)
+            end
+          end
+
+          # append resumption token for getting next group of records
+          if result.respond_to?(:token)
+            r.target! << result.token.to_xml
+          end
+
+        end
+      end
+    end
+
+  end
+
+end
+

data/lib/oai/provider/response/list_sets.rb

@@ -0,0 +1,23 @@
+module OAI::Provider::Response
+  
+  class ListSets < Base
+    
+    def to_xml
+      raise OAI::SetException.new unless provider.model.sets
+
+      response do |r|
+        r.ListSets do
+          provider.model.sets.each do |set|
+            r.set do
+              r.setSpec set.spec
+              r.setName set.name
+              r.setDescription(set.description) if set.respond_to?(:description)
+            end
+          end
+        end
+      end
+    end
+
+  end  
+
+end

data/lib/oai/provider/response/record_response.rb

@@ -0,0 +1,103 @@
+module OAI::Provider::Response
+  class RecordResponse < Base
+    def self.inherited(klass)
+      klass.valid_parameters    :metadata_prefix, :from, :until, :set
+      klass.default_parameters  :metadata_prefix => "oai_dc",
+           :from => method(:default_from).to_proc,
+           :until => method(:default_until).to_proc
+    end
+
+    def self.default_from(response)
+      value = Time.parse(response.provider.model.earliest.to_s).utc
+      if response.options[:until]
+        u = parse_date(response.options[:until])
+        value = value.to_date if u.is_a? Date
+      end
+      value
+    end
+
+    def self.default_until(response)
+      value = Time.parse(response.provider.model.latest.to_s).utc
+      if response.options[:from]
+        f = parse_date(response.options[:from])
+        value = value.to_date if f.is_a? Date
+      end
+      value
+    end
+
+    # emit record header
+    def header_for(record)
+      param = Hash.new
+      param[:status] = 'deleted' if deleted?(record)
+      @builder.header param do
+        @builder.identifier identifier_for(record)
+        @builder.datestamp timestamp_for(record)
+        sets_for(record).each do |set|
+          @builder.setSpec set.spec
+        end
+      end
+    end
+    # metadata - core routine for delivering metadata records
+    #
+    def data_for(record)
+      @builder.metadata do
+        @builder.target! << provider.format(requested_format).encode(provider.model, record)
+      end
+    end
+
+    # about - core routine for delivering about records
+    #
+    def about_for(record)
+      return unless provider.model.respond_to? :about
+
+      about = provider.model.about(record)
+      return if about.nil?
+
+      unless about.is_a? Array
+        about = [about]
+      end
+
+      about.each do |a|
+        @builder.about do
+          @builder.target! << a
+        end
+      end
+    end
+
+    private
+
+    # Namespace syntax suggested in http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm
+    def identifier_for(record)
+      "#{provider.prefix}:#{record.send( provider.model.identifier_field )}"
+    end
+
+    def timestamp_for(record)
+      record.send(provider.model.timestamp_field).utc.xmlschema
+    end
+
+    def sets_for(record)
+      return [] unless record.respond_to?(:sets) and record.sets
+      record.sets.respond_to?(:each) ? record.sets : [record.sets]
+    end
+
+    def requested_format
+      format =
+      if options[:metadata_prefix]
+        options[:metadata_prefix]
+      elsif options[:resumption_token]
+        OAI::Provider::ResumptionToken.extract_format(options[:resumption_token])
+      end
+      raise OAI::FormatException.new unless provider.format_supported?(format)
+
+      format
+    end
+
+    def deleted?(record)
+      return record.deleted? if record.respond_to?(:deleted?)
+      return record.deleted if record.respond_to?(:deleted)
+      return record.deleted_at if record.respond_to?(:deleted_at)
+      false
+    end
+
+  end
+end

data/lib/oai/provider/response.rb

@@ -0,0 +1,133 @@
+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
+      @request_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
+        @builder.request(provider.url, (@request_options.merge(:verb => verb) unless self.class == Error))
+        yield @builder
+      end
+    end
+
+    protected
+
+    def self.parse_date(value)
+      return value if value.respond_to?(:strftime)
+
+      if value[-1] == "Z"
+        Time.strptime(value, "%Y-%m-%dT%H:%M:%S%Z").utc
+      else
+        Date.strptime(value, "%Y-%m-%d")
+      end
+    rescue ArgumentError => e
+      raise OAI::ArgumentException.new, "unparsable date: '#{value}'"
+    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}.gsub(/\s+/, ' ')
+      }
+    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?
+
+      # check if the request includes an argument and there are no valid
+      # arguments for that verb (Identify, for example).
+      raise OAI::ArgumentException.new if self.class.valid_options.nil? && !options.empty?
+
+      if self.class.required_options
+        return false unless (self.class.required_options - @options.keys).empty?
+      end
+      return false unless (@options.keys - self.class.valid_options).empty?
+      populate_defaults
+    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)
+      self.class.parse_date(value)
+    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
+
+    def verb
+      self.class.to_s.split('::').last
+    end
+
+  end
+
+end
+end
+end
+

data/lib/oai/provider/resumption_token.rb

@@ -0,0 +1,155 @@
+require 'time'
+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.
+  #
+  # OAI-PMH spec does not specify anything about resumptionToken format, they can
+  # be purely opaque tokens.
+  #
+  # Our implementation however encodes everything needed to construct the next page
+  # inside the resumption token.
+  #
+  # == The 'last' component: offset or ID/pk to resume from
+  #
+  # The `#last` component is an offset or ID to resume from. In the case of it being
+  # an ID to resume from, this assumes that ID's are sortable and results are returned
+  # in ID order, so that the 'last' ID can be used as the place to resume from.
+  #
+  # Originally it was assumed that #last was always an integer, but since existing
+  # implementations (like ActiveRecordWrapper) used it as an ID, and identifiers and
+  # primary keys are _not_ always integers (can be UUID etc), we have expanded to allow
+  # any string value.
+  #
+  # However, for backwards compatibility #last always returns an integer (sometimes 0 if
+  # actual last component is not an integer), and #last_str returns the full string version.
+  # Trying to change #last itself to be string broke a lot of existing code in this gem
+  # in mysterious ways.
+  #
+  # Also beware that in some cases the value 0/"0" seems to be a special value used
+  # to signify some special case. A lot of "code archeology" going on here after significant
+  # period of no maintenance to this gem.
+  class ResumptionToken
+    attr_reader :prefix, :set, :from, :until, :last, :last_str, :expiration, :total
+
+    # parses a token string and returns a ResumptionToken
+    def self.parse(token_string, expiration = nil, total = nil)
+      begin
+        options = {}
+        matches = /(.+):([^ :]+)$/.match(token_string)
+        options[:last] = matches.captures[1]
+
+        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, expiration, total)
+      rescue => err
+        raise OAI::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]
+      self.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)
+      self.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/ID
+    #
+    # Q: Why does it eliminate the offset/id "last" on the end? Doesn't fully
+    #    represent state without it, which is confusing. Not sure, but
+    #    other code seems to rely on it, tests break if not.
+    def to_s
+      encode_conditions.gsub(/:\w+?$/, '')
+    end
+
+    private
+
+    # take care of our logic to store an integer and a str version, for backwards
+    # compat where it was assumed to be an integer, as well as supporting string.
+    def last=(value)
+      @last = value.to_i
+      @last_str = value.to_s
+    end
+
+    def encode_conditions
+      return "" if last_str.nil? || last_str.to_s.strip.eql?("")
+
+      encoded_token = @prefix.to_s.dup
+      encoded_token << ".s(#{set})" if set
+      if self.from
+        if self.from.respond_to?(:utc)
+          encoded_token << ".f(#{self.from.utc.xmlschema})"
+        else
+          encoded_token << ".f(#{self.from.xmlschema})"
+        end
+      end
+      if self.until
+        if self.until.respond_to?(:utc)
+          encoded_token << ".u(#{self.until.utc.xmlschema})" 
+        else
+          encoded_token << ".u(#{self.until.xmlschema})" 
+        end
+      end
+      encoded_token << ":#{last_str}"
+    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