module RailsConnector

  # This module accesses the Infopark Search Engine Server.
  module SES

    autoload :VerityAccessor, "rails_connector/ses/verity_accessor"

    # This method enables Obj to perform searches using the SES Search Engine Server.
    def self.enable #:nodoc:
      ::Obj.extend Obj::ClassMethods
    end

    module Obj #:nodoc:
      # Extends the model class Obj with the class method find_with_ses.
      module ClassMethods
        # Queries the search engine and returns a SearchResult. The parameters
        # are passed on to a SearchRequest (a kind of DefaultSearchRequest by default).
        #
        # Exceptions:
        # * SearchError - The search engine reported an error.
        #
        def find_with_ses(query_string, options = {})
          SearchRequest.new(query_string, options).fetch_hits
        end
      end
    end

    class SearchError < StandardError # :nodoc:
    end

    # SearchResult is the list of hits in response to a search query. Since the
    # maximum number of hits to return has been specified, there might be more
    # hits available in the search engine.
    class SearchResult < Array
      # The total number of hits.
      attr_reader :total_hits

      def initialize(total_hits) # :nodoc:
        super()
        @total_hits = total_hits
      end
    end

    # A hit represents a found document for a particular search query.
    class Hit
      # The ID of the found Obj.
      attr_reader :id

      # The score of the hit.
      attr_reader :score

      # The raw result hash returned by the search engine, for a low-level access.
      # Don't use this unless you know what you're doing.
      # Be aware that this is not migration safe.
      attr_reader :doc

      def initialize(id, score, doc={}) # :nodoc:
        @id = id
        @score = score
        @doc = doc
      end

      # Returns the hit's corresponding Obj (or nil if none found in the database).
      def obj
        @obj ||= ::Obj.find(@id)
      rescue RailsConnector::ResourceNotFound
        nil
      end
    end
  end

end