exlibris-primo 0.1.5 → 1.0.0

data/lib/exlibris/primo/chain_gang/user.rb

@@ -0,0 +1,18 @@
+module Exlibris
+  module Primo
+    module ChainGang
+      module User
+        attr_reader :user_id
+
+        # 
+        # Set the user id
+        # 
+        def user_id!(user_id)
+          @user_id = user_id
+          self
+        end
+        alias :user_id= :user_id!
+      end
+    end
+  end
+end

data/lib/exlibris/primo/config.rb

@@ -0,0 +1,69 @@
+module Exlibris
+  module Primo
+    #
+    # Specify global configuration settings for
+    #
+    module Config
+      class << self
+        include WriteAttributes
+        attr_accessor :base_url, :institution, :institutions, :libraries, :availability_statuses, :sources, 
+          :facet_labels, :facet_top_level, :facet_collections, :facet_resource_types, :load_time
+
+        def load_yaml file
+          write_attributes YAML.load_file(file)
+          self.load_time = Time.now
+        end
+      end
+
+      #
+      # These attributes default to the global config settings if not 
+      # specified locally.
+      #
+      module Attributes
+        def config
+          @config ||= Config
+        end
+
+        def base_url
+          @base_url ||= String.new config.base_url.to_s
+        end
+
+        def institution
+          @institution ||= String.new config.institution.to_s
+        end
+
+        def institutions
+          @institutions ||= (config.institutions) ? config.institutions.dup : {}
+        end
+
+        def libraries
+          @libraries ||= (config.libraries) ? config.libraries.dup : {}
+        end
+
+        def availability_statuses
+          @availability_statuses ||= (config.availability_statuses) ? config.availability_statuses.dup : {}
+        end
+
+        def sources
+          @sources ||= (config.sources) ? config.sources.dup : {}
+        end
+
+        def facet_labels
+          @facet_labels ||= (config.facet_labels) ? config.facet_labels.dup : {}
+        end
+
+        def facet_top_level
+          @facet_top_level ||= (config.facet_top_level) ? config.facet_top_level.dup : {}
+        end
+
+        def facet_collections
+          @facet_collections ||= (config.facet_collections) ? config.facet_collections.dup : {}
+        end
+
+        def facet_resource_types
+          @facet_resource_types ||= (config.facet_resource_types) ? config.facet_resource_types.dup : {}
+        end
+      end
+    end
+  end
+end

data/lib/exlibris/primo/eshelf.rb

@@ -1,81 +1,134 @@
 module Exlibris
   module Primo
-    # == Overview
-    # Exlibris::Primo::EShelf provides access to the Primo Eshelf for a given user.
-    # An instance of Exlibris::Primo::EShelf can be created by passing
-    # in a hash with setup parameters, a user_id and an institution.
-    # Valid setup parameters include:
-    #   :base_url, :resolver_base_url, :vid, :config
     #
-    # == Examples of usage
-    #   Exlibris::Primo::EShelf.new({ :base_url => "http://primo.institution.edu", :vid => "VID", :resolver_base_url => "http://resolver.institution.edu"} , "USER_ID", "PRIMO").count
-    #   Exlibris::Primo::EShelf.new(@eshelf_setup, @valid_user_id, @valid_institute).basket_id
+    # Manipulate a user's Primo eshelf using Exlibris::Primo::Eshelf
+    #
+    #     eshelf = Eshelf.new.base_url!("http://primo.library.edu").institution!("PRIMO").user_id!("USER_ID")
+    #     eshelf.records #=> Array for Primo records
+    #
     class EShelf
-      
-      #Namespaces
-      SEAR_NS = {'sear' => 'http://www.exlibrisgroup.com/xsd/jaguar/search'}
-      PRIM_NS = {'prim' => 'http://www.exlibris.com/primo/xsd/primoeshelffolder'}
-      PRIM_BIB_NS = {'bib' => 'http://www.exlibrisgroup.com/xsd/primo/primo_nm_bib'}
-      
-      def initialize(setup, user_id, institution)
-        @base_url = setup[:base_url]
-        raise_required_setup_parameter_error :base_url if @base_url.nil?
-        @resolver_base_url = setup[:resolver_base_url]
-        @vid = setup.fetch(:vid, "DEFAULT")
-        raise_required_setup_parameter_error :vid if @vid.nil?
-        @config = setup.fetch(:config, {})
-        raise_required_setup_parameter_error :config if @config.nil?
-        @user_id = user_id
-        raise_required_setup_parameter_error :user_id if @user_id.nil?
-        @institution = institution
-        raise_required_setup_parameter_error :institution if @institution.nil?
-        @records = []
+      include Config::Attributes
+      include ChainGang::Base
+      include ChainGang::User
+      include RequestAttributes
+      include WriteAttributes
+
+      attr_reader :user_id
+
+      def initialize *args
+        super
       end
-    
-      # Call Web Service to get Eshelf contents and return
+
+      #
+      # Call web service to get Eshelf contents and return
+      #
       def eshelf
-        @eshelf ||= Exlibris::Primo::WebService::GetEShelf.new(@user_id, @institution, @base_url).response
+        @eshelf ||= 
+          Exlibris::Primo::WebService::Request::GetEshelf.new(user_request_attributes).call
       end
-      
-      # Call Web Service to get Eshelf structure and return
-      def eshelfStructure
-        @eshelfStructure ||= Exlibris::Primo::WebService::GetEShelfStructure.new(@user_id, @institution, @base_url).response
+
+      #
+      # Call web service to get Eshelf structure and return
+      #
+      def eshelf_structure
+        @eshelf_structure ||= 
+          Exlibris::Primo::WebService::Request::GetEshelfStructure.new(user_request_attributes).call
       end
-      
-      # Fetch the number of records in user's Eshelf
-      def count
-        @count ||= Integer(eshelf.at("//sear:DOCSET", SEAR_NS)["TOTALHITS"])
+
+      #
+      # Get the number of records in user's eshelf
+      #
+      def size
+        @size ||= eshelf.size
       end
-    
-      # Fetch all records from user's Eshelf as an array of Primo Record objects
-      def records    
-        eshelf.search("//sear:DOC", SEAR_NS).each { |doc|
-          @records.push(Record.new({ :base_url => @base_url, :resolver_base_url => @resolver_base_url, :vid => @vid, :record => doc.at("//bib:record", PRIM_BIB_NS), :institution => @institution }))
-        } if @records.empty?
-        return @records
+
+      #
+      # Get all the records from user's eshelf as an array of Primo Record objects
+      #
+      def records
+        @records ||= eshelf.records
       end
-      
-      # Fetch default basket id from eshelf structure web service call
+
+      #
+      # Get the default basket id from eshelf structure web service call
+      #
       def basket_id
-        @basket_id ||= eshelfStructure.at(
-          "//prim:eshelf_folders//prim:eshelf_folder[./prim:folder_name='Basket']", PRIM_NS).
-          get_attribute("folder_id") unless eshelfStructure.at("//prim:eshelf_folders//prim:eshelf_folder[./prim:folder_name='Basket']", PRIM_NS).nil?
+        @basket_id ||= eshelf_structure.basket_id
       end
-      
-      # Call Web Service to add records to remote Eshelf
-      def add_records(doc_ids, folder_id)
-        Exlibris::Primo::WebService::AddToEShelf.new(doc_ids, folder_id, @user_id, @institution, @base_url) unless doc_ids.empty?
+
+      #
+      # Get the folder id from eshelf structure web service call
+      # for the given folder name.
+      #
+      def folder_id(folder_name)
+        eshelf_structure.folder_id(folder_name)
       end
 
-      # Call Web Service to remove records from remote EShelf
-      def remove_records(doc_ids, folder_id)
-        Exlibris::Primo::WebService::RemoveFromEShelf.new(doc_ids, folder_id, @user_id, @institution, @base_url) unless doc_ids.empty?
+      #
+      # Call web service to add records to eshelf
+      #
+      def add_records(record_ids, folder_id)
+        record_ids.each do |record_id|
+          add_record record_id, folder_id
+        end
+        reset_eshelf
       end
-      
-      private
-      def raise_required_setup_parameter_error(parameter)
-        raise ArgumentError.new("Error in #{self.class}. Missing required setup parameter: #{parameter}.")
+
+      #
+      # Call web service to add record to eshelf
+      #
+      def add_record(record_id, folder_id)
+        Exlibris::Primo::WebService::Request::AddToEshelf.new(
+          user_request_attributes.merge :folder_id => folder_id, :doc_id => record_id).call
+        reset_eshelf
+      end
+
+      #
+      # Call web service to remove records from the eshelf
+      #
+      def remove_records(record_ids, folder_id)
+        record_ids.each do |record_id|
+          remove_record record_id, folder_id
+        end
+        reset_eshelf
+      end
+
+      #
+      # Call web service to remove a record from eshelf
+      #
+      def remove_record(record_id, folder_id)
+        Exlibris::Primo::WebService::Request::RemoveFromEshelf.new(
+          user_request_attributes.merge :folder_id => folder_id, :doc_id => record_id).call
+        reset_eshelf
+      end
+
+      #
+      # Call web service to add folder to eshelf
+      #
+      def add_folder(folder_name, parent_id)
+        Exlibris::Primo::WebService::Request::AddFolderToEshelf.new(
+          user_request_attributes.merge :folder_name => folder_name, :parent_folder => parent_id).call
+        reset_eshelf
+      end
+
+      #
+      # Call web service to remove folder from eshelf
+      #
+      def remove_folder(folder_id)
+        Exlibris::Primo::WebService::Request::RemoveFolderFromEshelf.new(
+          user_request_attributes.merge :folder_id => folder_id).call
+        reset_eshelf
+      end
+
+      # Reset eshelf instance variables
+      def reset_eshelf
+        @eshelf = nil
+        @eshelf_structure = nil
+        @size = nil
+        @records = nil
+        @basket_id = nil
       end
+      private :reset_eshelf
     end
   end
 end

data/lib/exlibris/primo/facet.rb

@@ -0,0 +1,40 @@
+module Exlibris
+  module Primo
+    # 
+    # Primo facet holds the name of the facet
+    # and size (often approximate).
+    # 
+    class Facet
+      include Config::Attributes
+      include WriteAttributes
+      include XmlUtil
+
+      attr_accessor :accurate
+      alias accurate? accurate
+
+      def initialize *args
+        @raw_xml = args.last.delete(:raw_xml)
+        super
+      end
+
+      def name
+        @name = xml.root["NAME"]
+      end
+
+      def display_name
+        @display_name ||= (config.facet_labels[name] || name)
+      end
+
+      def size
+        @size = Integer(xml.root["COUNT"])
+      end
+      alias :count :size
+
+      def facet_values
+        @facet_values ||= xml.root.search("//FACET_VALUES").collect do |facet_value|
+          FacetValue.new(:raw_xml => facet_value.to_xml, :facet => self)
+        end
+      end
+    end
+  end
+end

data/lib/exlibris/primo/facet_value.rb

@@ -0,0 +1,40 @@
+module Exlibris
+  module Primo
+    require 'iso-639'
+    #
+    # Primo facet value that holds the name of the value
+    # and the number of records that limiting by this facet
+    # value would return.
+    #
+    class FacetValue
+      include Config::Attributes
+      include WriteAttributes
+      include XmlUtil
+
+      attr_accessor :facet
+
+      def initialize *args
+        @raw_xml = args.last.delete(:raw_xml)
+        super
+      end
+
+      def name
+        @name ||= xml.root["KEY"]
+      end
+
+      def display_name
+        return @display_name ||= (ISO_639.find(name).english_name || name) if facet.name.eql? "lang"
+        return @display_name ||= (config.libraries[name] || name) if facet.name.eql? "library"
+        return @display_name ||= (config.facet_top_level[name] || name) if facet.name.eql? "tlevel"
+        return @display_name ||= (config.facet_collections[name] || name) if facet.name.eql? "domain"
+        return @display_name ||= (config.facet_resource_types[name] || name) if facet.name.eql? "rtype"
+        @display_name ||= name
+      end
+
+      def size
+        @size = Integer(xml.root["VALUE"])
+      end
+      alias :count :size
+    end
+  end
+end

data/lib/exlibris/primo/holding.rb

@@ -1,135 +1,83 @@
 module Exlibris
   module Primo
-    # == Overview
-    # Exlibris::Primo::Holding represents a Primo availibrary entry.
-    # An instance of Exlibris::Primo::Holding can be created by passing
-    # in a set of parameters containing the data for the holding.
-    # Valid parameters include:
-    #   :record_id, :title, :author, :source_id, :original_source_id, :source_record_id, 
-    #   :availlibrary,:institution_code, :library_code,  :status_code, :id_one, :id_two, 
-    #   :origin, :display_type, :coverage, :notes, :url, :request_url, :source_data
-    # When creating an instance of Exlibris::Primo::Holding, calling
-    # classes may send in a :config hash that contains config mappings
-    # for decoding libraries and statuses. The :config hash should be
-    # of the form 
-    #   {"libraries" => {"library_code1" => "library_display_1", "library_code2" => "library_display_1"}, "statuses" => {"status_code1" => "status_display_1", "status_code2" => "status_display_2"}}
-    # The config can also include information about Primo::Source classes in the form:
-    #   "sources" => {"source_id1" => {"class_name" => "SourceKlassName", "source_config1" => "source_config_one"}}
-    # Primo::Source classes can be used to represent a Primo source for expanding holdings 
-    # information, linking to Primo sources, and storing additional metadata based on those sources.  
-    # In order to create a source class, implementations should extend Exlibris::Primo::Holding.
-    #
-    # == Tips on Extending
-    # When extending the class, a few basics guidelines should be observed.
-    # 1.  A Exlibris::Primo::Holding is initialized from random Hash of parameters.
-    #     Instance variables are created from these parameters for use in the class.
-    #
-    # 2.  A Exlibris::Primo::Holding can also be initialized from an input 
-    #     Exlibris::Primo::Holding by specifying the reserved
-    #     parameter name :holding, i.e. :holding => input_holding.
-    #     If the input holding has instance variables that are also specified in
-    #     the random Hash, the value in the Hash takes precedence.
+
     #
-    # 3.  The following methods are available for overriding:
-    #     expand -    expand holdings information based on data source. default: [self]
-    #     dedup? -    does this data source contain duplicate holdings that need to be deduped? default: false
+    # Primo Holding.
     #
-    # 4.  Additional source data should be saved in the @source_data instance variable.
-    #     @source_data is a hash that can contain any number of string elements,
-    #     perfect for storing local source information.
+    # Object representing a holding in Primo.
+    # 
+    # Primo holdings can be extended to create Primo source holdings.
+    # create a local class representing the source in the
+    # module Exlibris::Primo::Source which extends Exlibris::Primo::Holding.
+    # Two methods are then available for overriding:
+    #     :expand -   expand holdings based on information from the source
+    #                 default: [self]
+    #     :dedup? -   if this data source contain duplicate holdings that need to be deduped, set to true
+    #                 default: false
     #
-    # == Examples
-    # Example of Primo source implementations are:
+    # ==Examples
+    # An examples of a customized source is:
     # * Exlibris::Primo::Source::Aleph
     class Holding
-      @base_attributes = [ :record_id, :title, :author, :source_id, :original_source_id, 
-        :source_record_id, :availlibrary, :institution_code, :institution, :library_code, 
-        :library, :status_code, :status, :id_one, :id_two, :origin, :display_type, :coverage,
-        :notes, :url, :request_url, :source_data ]
-      # Make sure attribute you're aliasing in in base_attributes
-      @attribute_aliases = { :collection => :id_one, :call_number => :id_two }
-      @required_parameters = [ :base_url, :record_id, :source_id, 
-        :original_source_id, :source_record_id, :availlibrary,
-        :institution_code, :library_code, :id_one, :id_two, :status_code ]
-      @parameter_default_values = { :vid => "DEFAULT", :config => {}, 
-        :max_holdings => 10, :coverage => [], :source_data => {} }
-      @decode_variables = { 
-        :institution => {}, 
-        :library => { :address => "libraries" },
-        :status => { :address => "statuses" }
-      }
-      class << self; attr_reader :base_attributes, :attribute_aliases, :required_parameters, :parameter_default_values, :decode_variables end
+      include Config::Attributes
+      include WriteAttributes
+
+      # Default values for the class.
+      def self.defaults
+        @defaults ||= { :coverage => [], :source_data => {} }
+      end
+
+      attr_accessor :availlibrary, :record_id, :original_id,
+        :title, :author, :display_type, :source_id, :original_source_id,
+        :source_record_id, :ils_api_id, :institution_code,
+        :library_code, :availability_status_code,
+        :collection, :call_number, :coverage, :notes,
+        :subfields, :source_class, :source_data
+
+      alias :status_code :availability_status_code
 
-      def initialize(parameters={})
-        # Set attr_readers
-        base_attributes = (self.class.base_attributes.nil?) ? 
-          Exlibris::Primo::Holding.base_attributes : self.class.base_attributes
-        base_attributes.each { |attribute|
-          self.class.send(:attr_reader, attribute)
-        }
-        # Defensive copy the holding parameter.
-        holding = parameters[:holding].clone unless parameters[:holding].nil?
-        raise "Initialization error in #{self.class}. Unexpected holding parameter: #{holding.class}." unless holding.kind_of? Holding or holding.nil?
-        # Copy the defensive copy of holding to self.
-        holding.instance_variables.each { |name| 
-          instance_variable_set((name).to_sym, holding.instance_variable_get(name)) 
-        } if holding.kind_of? Holding
-        # Add required instance variables, raising an exception if they're missing
-        # Params passed in overwrite instance variables copied from the holding
-        required_parameters = (self.class.required_parameters.nil?) ? 
-          Exlibris::Primo::Holding.required_parameters : self.class.required_parameters
-        required_parameters.each do |param|
-          instance_variable_set(
-            "@#{param}".to_sym, 
-            parameters.delete(param) { 
-              instance_variable_get("@#{param}") if instance_variable_defined?("@#{param}") }
-          )
-          raise_required_parameter_error param unless instance_variable_defined?("@#{param}")
+      # Initialize with a set of attributes and/or another :holding.
+      def initialize(attributes={})
+        # Get holding
+        holding = attributes.delete(:holding)
+        # Instantiate new holding from input holding
+        # if it exists.
+        unless holding.nil?
+          super holding.to_h.merge(attributes)
+        else
+          super self.class.defaults.merge(attributes)
         end
-        # Set additional instance variables from passed parameters
-        # Params passed in overwrite instance variables copied from the holding
-        parameters.each { |param, value| 
-          instance_variable_set("@#{param}".to_sym, value)
-        }
-        # If appropriate, add defaults to non-required elements
-        parameter_default_values = (self.class.parameter_default_values.nil?) ? 
-          Exlibris::Primo::Holding.parameter_default_values : self.class.parameter_default_values
-        parameter_default_values.each { |param, default|
-          instance_variable_set("@#{param}".to_sym, default) unless instance_variable_defined?("@#{param}")
-        }
-        # Set decoded fields
-        decode_variables = (self.class.decode_variables.nil?) ? 
-          Exlibris::Primo::Holding.decode_variables : self.class.decode_variables
-        decode_variables.each { |var, decode_params|
-          decode var, decode_params, true
-        }
-        # Deep link URL to record
-        @url = primo_url if @url.nil?
-        # Set source parameters
-        @source_config = @config["sources"][source_id] unless @config["sources"].nil?
-        @source_class = @source_config["class_name"] unless @source_config.nil?
-        @source_url = @source_config["base_url"] unless @source_config.nil?
-        @source_type = @source_config["type"] unless @source_config.nil?
-        @source_data = {
-          :source_class => @source_class,
-          :source_url => @source_url,
-          :source_type => @source_type
-        }
-        # Set aliases for convenience
-        attribute_aliases = (self.class.attribute_aliases.nil?) ? 
-          Exlibris::Primo::Holding.attribute_aliases : self.class.attribute_aliases
-        attribute_aliases.each { |alias_name, method_name|
-          begin
-            self.class.send(:alias_method, alias_name.to_sym, method_name.to_sym)
-          rescue NameError => ne
-            raise NameError, "Error in #{self}. Make sure method, #{method_name}, is defined. You may need to add it to #{self} @base_attributes.\nRoot exception: #{ne.message}"
-          end
-        }
       end
-    
+
+      # Get the source config from the Primo config, based on source_id, if not already set.
+      def source_config
+        @source_config ||= sources[source_id]
+      end
+
+      # Get the class name from the Primo source config, if not already set.
+      def source_class
+        @source_class ||= source_config["class_name"] unless source_config.nil?
+      end
+
+      # Get the institution from the Primo config based on institution code, if not already set.
+      def institution
+        @institution ||= (institutions[institution_code] || institution_code)
+      end
+
+      # Get the library from the Primo config based on library code, if not already set.
+      def library
+        @library ||= (libraries[library_code] || library_code)
+      end
+
+      # Get the availability status from the Primo config based on availability status code, if not already set.
+      def availability_status
+        @availability_status ||= (availability_statuses[availability_status_code] || availability_status_code)
+      end
+      alias :availability :availability_status
+      alias :status :availability_status
+
       # Returns an array of self.
-      # Should be overridden by source subclasses to map multiple holdings
-      # to one availlibrary.
+      # Should be overridden by source subclasses if appropriate.
       def expand
         return [self]
       end
@@ -139,42 +87,23 @@ module Exlibris
       def dedup?
         return false
       end
-    
+
       # Return this holding as a new holdings subclass instance based on source
       def to_source
-        return self if @source_class.nil?
+        return self if source_class.nil?
         # Get source class in Primo::Source module
-        return Exlibris::Primo::Source.const_get(@source_class).new(:holding => self)
-      end
-
-      # Convenience method for making base attributes accessible via Hash-like syntax.
-      def [](key)
-        raise "Error in #{self.class}. #{key} doesn't exist or is restricted." unless self.class.base_attributes.include?(key)
-        method(key).call
+        return Exlibris::Primo::Source.const_get(source_class).new(:holding => self)
       end
 
-      protected
-      # Decode based on the pased in config
-      def decode(var, decode_params={}, refresh=false)
-        return instance_variable_get("@#{var}") unless (not instance_variable_defined?("@#{var}")) or refresh
-        code_sym = (decode_params[:code].nil?) ? "#{var}_code".to_sym : decode_params[:code]
-        code = instance_variable_get("@#{code_sym}")
-        config_sym = (decode_params[:config].nil?) ? :config : decode_params[:config]
-        config = instance_variable_get("@#{config_sym}")
-        address = (decode_params[:address].nil?) ? "#{var}s" : decode_params[:address]
-        instance_variable_set("@#{var}", 
-          (config[address].nil? or config[address][code].nil?) ? 
-            code : config[address][code]) unless code.nil?
-      end
-
-      # Returns Primo deep link URL to record
-      def primo_url
-        "#{@base_url}/primo_library/libweb/action/dlDisplay.do?docId=#{@record_id}&institution=#{@institution_code}&vid=#{@vid}"
-      end
- 
-      private
-      def raise_required_parameter_error(parameter)
-        raise "Initialization error in #{self.class}. Missing required parameter: #{parameter}."
+      # Return the attribute accessible instance variables as a hash.
+      def to_h
+        { :availlibrary => availlibrary, :record_id => record_id, :original_id => original_id, 
+          :title => title, :author => author, :display_type => display_type, :source_id => source_id,
+          :original_source_id => original_source_id, :source_record_id => source_record_id,
+          :ils_api_id => ils_api_id, :institution_code => institution_code, :library_code => library_code,
+          :availability_status_code => availability_status_code, :collection => collection,
+          :call_number => call_number, :coverage => coverage, :notes => notes, :subfields => subfields,
+          :source_id => source_id, :source_class => source_class, :source_data => source_data }
       end
     end
   end