exlibris-aleph 0.1.6 → 1.0.0

data/README.md

@@ -0,0 +1,89 @@
+# Exlibris::Aleph
+[![Gem Version](https://badge.fury.io/rb/exlibris-aleph.png)](http://badge.fury.io/rb/exlibris-aleph)
+[![Build Status](https://api.travis-ci.org/scotdalton/exlibris-aleph.png?branch=master)](https://travis-ci.org/scotdalton/exlibris-aleph)
+[![Dependency Status](https://gemnasium.com/scotdalton/exlibris-aleph.png)](https://gemnasium.com/scotdalton/exlibris-aleph)
+[![Code Climate](https://codeclimate.com/github/scotdalton/exlibris-aleph.png)](https://codeclimate.com/github/scotdalton/exlibris-aleph)
+[![Coverage Status](https://coveralls.io/repos/scotdalton/exlibris-aleph/badge.png?branch=master)](https://coveralls.io/r/scotdalton/exlibris-aleph)
+
+Exlibris::Aleph offers a set of libraries for interacting with the ExLibris Aleph ILS.
+
+## Exlibris::Aleph::Patron
+Exlibris::Aleph::Patron provides access to the Aleph Patron REST API.
+
+### Example of Exlibris::Aleph::Patron in action
+    patron = 
+      Exlibris::Aleph::Patron.
+        new(patron_id: "S0M31D", rest_url: "http://aleph.institution.edu")
+    patron.address # Returns a Hash of the of patron's address
+    patron.loans # Returns an Array of institution Hashes, each containing an Array of the patron's loans for that institution
+    patron.renew_loans # Renews all loans
+    patron.renew_loans("ADM5000000001") # Renews loan of item 00000001 in ADM50
+    patron.place_hold("ADM50", "SBLIB", "00000001", "00000001", {:pickup_location => "SBLIB"}) # Places hold on the specified item for pickup at SBLIB
+  
+## Exlibris::Aleph::Record
+Provides access to the Aleph Record REST API.
+
+### Example of Exlibris::Aleph::Record in action
+    record = 
+      Exlibris::Aleph::Record.
+        new(bib_library: "ADM50", record_id: "00000001", rest_url: "http://aleph.institution.edu")
+    record.bib # Returns a MARC::Record with bibliographic metadata
+    record.holdings # Returns and Array of MARC::Records respresenting the record's holdings
+    record.items # Returns and Array of Hashes representing the record's items
+
+## Exlibris::Aleph.configure
+Exlibris::Aleph can be configured at startup in an initializer.
+
+    # Placed this in an initializer.
+    Exlibris::Aleph.configure { |c|
+      c.base_url = "http://aleph.institution.edu"
+      c.tab_path = "/mnt/aleph_tab"
+      c.adms = ["ADM50", "ADM51"]
+    }
+
+It can also read from a yaml file.
+
+    # Placed this in an initializer.
+    Exlibris::Aleph.configure { |c|
+      config.load_yaml File.expand_path("#{File.dirname(__FILE__)}/../config/aleph.yml",  __FILE__)
+    }
+
+## Exlibris::Aleph::TabHelper
+Exlibris::Aleph::TabHelper provides a way to access the various tab settings for patrons, patron\_permissions, items, item_permission (both by item status and by item processing status), collections and pickup locations. It also provides convenience methods for common tasks like getting the pickup location for a given combination of item status, item process status and borrower status or getting an item's web text.  Support a 
+
+### Example of Exlibris::Aleph::TabHelper in action
+    # Placed this in an initializer.
+    Exlibris::Aleph.configure { |c|
+      c.tab_path = "/mnt/aleph_tab"
+      c.adms = ["ADM50", "ADM51"]
+    }
+
+    # Rake task to refresh the config yml files
+    rake exlibris:aleph:refresh
+
+    # Get an instance of TabHelper
+    helper = Exlibris::Aleph::TabHelper.instance
+    helper.sub_library_text("SBLIB") # Returns display text for the give code
+    helper.sub_library_adm("SBLIB") # Returns ADM for the give code
+    helper.item_pickup_locations({:adm_library_code => "ADM50", :sub_library_code => "SBLIB", :bor_status => "51"}) # Returns the pickup locations for the given parameters
+    helper.collection_text({:adm_library_code => "ADM50", :sub_library_code => "SBLIB", :collection_code => "MAIN"}) # Returns the collection display text for the give parameters
+    helper.item_web_text({:adm_library_code => "ADM50", :item_process_status => "Item Process Status"}) # Returns the web text for the given parameters
+    helper.item_web_text({:adm_library_code => "ADM50", :sub_library_code => "SBLIB", :item_process_status_code => "DP"}) # Returns the web text for the given parameters
+
+### Configure irrelevant sub libraries for TabHelper
+To configure the gem to ignore sub libraries pulled from Aleph but not relevant to working with permissions call the following setter with an array of sub library Aleph codes.
+
+    # Place this in an initializer to replace the current irrelevant sub libraries.
+    Exlibris::Aleph.configure { |c|
+      c.irrelevant_sub_libraries = ["IRRLIB1", "IRRLIB2"]
+    }
+
+## Exlibris::Aleph::BorAuth
+Exlibris::Aleph::BorAuth provides access to the BorAuth Aleph XService.
+
+### Example of Exlibris::Aleph::BorAuth in action
+    bor_auth = 
+      Exlibris::Aleph::BorAuth.
+        new("http://aleph.institution.edu", "ADM50", "SBLIB", "N", "S0M31D", "V3R1F1C@T10N")
+    permissions = bor_auth.permissions # Return a Hash of permissions based on the Exlibris::Aleph::BorAuth instance
+

data/Rakefile

@@ -20,9 +20,6 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-
-
-
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
@@ -34,5 +31,6 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
-
 task :default => :test
+
+require 'exlibris-aleph'

data/lib/exlibris-aleph.rb

@@ -1,21 +1,8 @@
-PATH = File.dirname(__FILE__) + "/exlibris/aleph/"
-[ 
-  'config/config_base',
-  'config/config_by_sub_library',
-  'config/pc_tab_exp_field_extended',
-  'config/tab15_by_item_process_status',
-  'config/tab15_by_item_status',
-  'config/tab31',
-  'config/tab37',
-  'config/tab40',
-  'config/tab_sub_library',
-  'config/tab_www_item_desc',
-  'tab_helper',
-  'rest',
-  'record',
-  'patron',
-  'bor_auth'
-].each do |library|
-  require PATH + library
-end
-require PATH + 'railtie' if defined?(Rails)
+# Leverage ActiveSupport core extensions
+require 'active_support/core_ext'
+require 'active_support/builder'
+require 'marc'
+require "require_all"
+require_all "#{File.dirname(__FILE__)}/exlibris/"
+# Install tasks
+Exlibris::Aleph::TaskInstaller.install_tasks

data/lib/exlibris/aleph.rb

@@ -0,0 +1,13 @@
+module Exlibris
+  module Aleph
+    class << self
+      def configure
+        yield config
+      end
+
+      def config
+        @config ||= Config
+      end
+    end
+  end
+end

data/lib/exlibris/aleph/abstract.rb

@@ -0,0 +1,28 @@
+module Exlibris
+  module Aleph
+    # 
+    # If a class is abstract, it can't be instantiated.
+    # 
+    module Abstract
+      def self.included(klass)
+        klass.class_eval do
+          extend ClassAttributes
+        end
+      end
+
+      module ClassAttributes
+        def abstract
+          @abstract ||= false
+        end
+        alias :abstract? :abstract
+
+        attr_writer :abstract
+        protected :abstract=
+      end
+
+      def initialize *args
+        raise NotImplementedError.new("Cannot instantiate #{self.class.name}.  It is abstract") if self.class.abstract?
+      end
+    end
+  end
+end

data/lib/exlibris/aleph/config.rb

@@ -0,0 +1,78 @@
+module Exlibris
+  module Aleph
+    
+    #
+    # Specify global configuration settings for
+    #
+    module Config
+      class << self
+        include WriteAttributes
+        attr_accessor :base_url, :rest_url, :adms, :refresh_time, :tab_path, 
+          :yml_path, :logger, :irrelevant_sub_libraries, :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
+
+        # Aleph base url
+        def base_url
+          @base_url ||= String.new config.base_url.to_s
+        end
+
+        # Aleph rest url
+        def rest_url
+          @rest_url ||= (config.rest_url) ? String.new(config.rest_url.to_s) : "#{base_url}:1891/rest-dlf"
+        end
+
+        # Refresh time for TabHelper
+        def refresh_time
+          @refresh_time ||= (config.refresh_time) ? config.refresh_time : lambda{1.day.ago}
+        end
+
+        # Aleph ADMs to parse
+        def adms
+          @adms ||= (config.adms) ? config.adms.collect{|adm| adm.downcase} : []
+        end
+
+        # Tab path for Aleph tables
+        def tab_path
+          @tab_path ||= File.join(config.tab_path)
+        end
+
+        # YAML path for persisting Aleph config
+        def yml_path
+          @yml_path ||= (File.join(config.yml_path) || File.join(tab_path, "..", "config", "aleph"))
+        end
+
+        def logger
+          @logger ||= (config.logger) ? config.logger : Logger.new(File.join(yml_path, "..", "..", "log", "exlibris_aleph.log"))
+        end
+
+        def irrelevant_sub_libraries
+          @irrelevant_sub_libraries ||= 
+            (config.irrelevant_sub_libraries) ? config.irrelevant_sub_libraries : 
+              [ "USR00", "HOME", "BOX", "ILLDT", "NYU51", "ALEPH", "USM50",
+                "MED", "HYL", "HIL", "LAM", "LAW", "LIT", "MUS", "WID", "EXL", "CIRC", "HILR", "HIL01",
+                "HYL01", "HYL02", "HYL03", "HYL04", "HYL05", "HYL06", "LAM01", "LAM02", "LAM03", "LAW01",
+                "LAW02", "LAW03", "LIT01", "LIT02", "MED01", "MED02", "MUS01", "MUS02", "WID01", "WID02",
+                "WID03", "WID04", "WID05", "U60WD", "U60HL", "U60LA", "U70WD", "CBAB", "BCU", "MBAZU", "USM51",
+                "ELEC5", "GDOC5", "EDUC5", "LINC5", "RRLIN", "OU511", "OR512", "OR513", "OR514", "OR515", "U61ED",
+                "U61EL", "U61LN", "S61GD", "USM53", "ELEC7", "GDOC7", "EDUC7", "LINC7", "USM54", "ELEC4", "USM55",
+                "CUN50", "CLEC5", "CDOC5", "CDUC5", "CINC5", "UNI50", "NARCV", "NELEC", "NRLEC", "NGDOC", "NRDOC",
+                "NEDUC", "NHLTH", "NLINC", "NLAW", "NMUSI", "NSCI", "NUPTN" ]
+        end
+      end
+    end
+  end
+end

data/lib/exlibris/aleph/patron.rb

@@ -2,84 +2,99 @@ module Exlibris
   module Aleph
     # ==Overview
     # Provides access to the Aleph Patron REST API.
-    class Patron < Rest
-      attr_reader :patron_id
-      
-      # Creates an instance of Exlibris::Aleph::Patron for the given :patron_id
-      def initialize(patron_id, uri)
-        @patron_id = patron_id
-        raise "Initialization error in #{self.class}. Missing patron id." if @patron_id.nil?
-        super(uri)
-        @uri = @uri+ "/patron/#{patron_id}"
-      end
+    class Patron < Rest::Base
+      attr_accessor :patron_id
 
       # Place a hold on the specificed item.
-      # Raises an error if there was a problem placing the hold.
-      # Returns a HTTParty::Response.
+      # Returns a Hash, including the "note" returned from the underlying API.
+      # Raises an exception if the response is not valid XML or there are errors.
       def place_hold(adm_library, bib_library, bib_id, item_id, params)
-        pickup_location = params[:pickup_location]
-        raise "Error in place hold.  Missing pickup location." if pickup_location.nil?
-        last_interest_date = params.fetch(:last_interest_date, "")
-        start_interest_date = params.fetch(:start_interest_date, "")
-        sub_author = params.fetch(:sub_author, "")
-        sub_title = params.fetch(:sub_title, "")
-        pages = params.fetch(:pages, "")
-        note_1 = params.fetch(:note_1, "")
-        note_2 = params.fetch(:note_2, "")
-        rush = params.fetch(:rush, "N")
-        body_str = "<hold-request-parameters>"
-        body_str << "<pickup-location>#{pickup_location}</pickup-location>"
-        body_str << "<last-interest-date>#{last_interest_date}</last-interest-date>"
-        body_str << "<start-interest-date>#{start_interest_date}</start-interest-date>"
-        body_str << "<sub-author>#{sub_author}</sub-author>"
-        body_str << "<sub-title>#{sub_title}</sub-title>"
-        body_str << "<pages>#{pages}</pages>"
-        body_str << "<note-1>#{note_1}</note-1>"
-        body_str << "<note-2>#{note_2}</note-2>"
-        body_str << "<rush>#{rush}</rush>"
-        body_str << "</hold-request-parameters>"
-        options = { :body => "post_xml=#{body_str}"}
-        @response = self.class.put(@uri+ "/record/#{bib_library}#{bib_id}/items/#{item_id}/hold", options)
-        raise "Error placing hold through Aleph REST APIs. #{error}" unless error.nil?
-        return @response
+        options = { :body => "post_xml=#{place_hold_xml(params)}"}
+        self.response = self.class.put("#{patron_url}/record/#{bib_library}#{bib_id}/items/#{item_id}/hold", options)
+        raise_error_if("Error placing hold through Aleph REST APIs. #{error}") {
+          (response.parsed_response["put_item_hold"].nil? or response.parsed_response["put_item_hold"]["create_hold"].nil?)
+        }
+        response.parsed_response["put_item_hold"]["create_hold"]
       end
 
-      # Call the patronInformation/address Aleph Patron REST API
-      # Returns a HTTParty::Response.
-      def address()
-        @response = self.class.get(@uri+ "/patronInformation/address")
-        return "Error getting patron's address through Aleph REST APIs. #{error}" unless error.nil?
-        return @response
+      # Returns a Hash representing the patron's address information.
+      # Every method call refreshes the data from the underlying API.
+      # Raises an exception if the response is not valid XML or there are errors.
+      def address
+        self.response = self.class.get("#{patron_url}/patronInformation/address")
+        raise_error_if("Error getting patron address through Aleph REST APIs.") {
+          (response.parsed_response["get_pat_adrs"].nil? or response.parsed_response["get_pat_adrs"]["address_information"].nil?)
+        }
+        response.parsed_response["get_pat_adrs"]["address_information"]
       end
 
-      # Call the circulationActions/loans Aleph Patron REST API
-      # Returns a HTTParty::Response.
-      def loans()
-        @response = self.class.get(@uri+ "/circulationActions/loans?view=full")
-        raise "Error getting loans through Aleph REST APIs. #{error}" unless error.nil?
-        return @response
+      # Returns an Array of institutions. 
+      # Each institution is a Hash containing an array of loans for that institution.
+      # Every method call refreshes the data from the underlying API.
+      # Raises an exception if the response is not valid XML or there are errors.
+      def loans
+        self.response = self.class.get("#{patron_url}/circulationActions/loans?view=full")
+        raise_error_if("Error getting loans through Aleph REST APIs.") {
+          (response.parsed_response["pat_loan_list"].nil? or response.parsed_response["pat_loan_list"]["loans"].nil?)
+        }
+        [response.parsed_response["pat_loan_list"]["loans"]["institution"]].flatten
       end
 
       # Renew the specified item.
       # Will renew all if item not specified.
-      # Returns a HTTParty::Response.
+      # Returns an Array of institutions. 
+      # Each institution is a Hash containing an array of loan renewals for that institution.
+      # Raises an exception if the response is not valid XML or there are errors.
       def renew_loans(item_id="")
-        @response = self.class.post(@uri+ "/circulationActions/loans/#{item_id}")
-        raise "Error renewing loan(s) through Aleph REST APIs. #{error}" unless error.nil?
-        return @response
+        self.response = self.class.post("#{patron_url}/circulationActions/loans/#{item_id}")
+        raise_error_if("Error renewing loans through Aleph REST APIs.") {
+          (response.parsed_response["renew_loan"].nil? or response.parsed_response["renew_loan"]["renewals"].nil?)
+        }
+        [response.parsed_response["renew_loan"]["renewals"]["institution"]].flatten
       end
-      
+
       # Returns the note associated with the request.
       def note
-        return (not @response.first.last.kind_of?(Hash) or @response.first.last["create_hold"].nil?) ? "" : ": #{@response.first.last["create_hold"]["note"]["__content__"]}" if @response.instance_of?(Hash)
+        return (not response.first.last.kind_of?(Hash) or response.first.last["create_hold"].nil?) ? "" : ": #{response.first.last["create_hold"]["note"]["__content__"]}" if response.instance_of?(Hash)
       end
-      
+
       # Returns the error associated with the request.
       # Returns nil if no error.
       def error
         return nil if reply_code == "0000"
         return "#{reply_text}#{note}"
       end
+
+      def patron_url
+        @patron_url ||= "#{rest_url}/patron/#{patron_id}"
+      end
+      private :patron_url
+
+      def place_hold_xml(params)
+        pickup_location = params[:pickup_location]
+        last_interest_date = params.fetch(:last_interest_date, "")
+        start_interest_date = params.fetch(:start_interest_date, "")
+        sub_author = params.fetch(:sub_author, "")
+        sub_title = params.fetch(:sub_title, "")
+        pages = params.fetch(:pages, "")
+        note_1 = params.fetch(:note_1, "")
+        note_2 = params.fetch(:note_2, "")
+        rush = params.fetch(:rush, "N")
+        build_xml { |xml|
+          xml.send(:"hold-request-parameters") {
+            xml.send :"pickup-location", pickup_location
+            xml.send :"last-interest-date", last_interest_date
+            xml.send :"start-interest-date", start_interest_date
+            xml.send :"sub-author", sub_author
+            xml.send :"sub-title", sub_title
+            xml.send :"pages", pages
+            xml.send :"note-1", note_1
+            xml.send :"note-2", note_2
+            xml.send :"rush", rush
+          }
+        }
+      end
+      private :place_hold_xml
     end
   end
 end

data/lib/exlibris/aleph/record.rb

@@ -1,64 +1,58 @@
 module Exlibris
   module Aleph
+    require 'marc'
     # ==Overview
     # Provides access to the Aleph Record REST API.
-    class Record < Rest
-      attr_reader :bib_library, :record_id
+    class Record < Rest::Base
+      attr_accessor :bib_library, :record_id
 
-      # Creates an instance of Exlibris::Aleph::Record for the given :bib_library and :record_id
-      def initialize(bib_library, record_id, uri)
-        @record_id = record_id
-        raise "Initialization error in #{self.class}. Missing record id." if @record_id.nil?
-        @bib_library = bib_library
-        raise "Initialization error in #{self.class}. Missing bib library." if @bib_library.nil?
-        super(uri)
-        @uri = @uri+ "/record/#{bib_library}#{record_id}"
-        # Format :xml parses response as a hash.
-        # Eventually I'd like this to be the default since it raises exceptions for invalid XML.
-        # self.class.format :xml
-        # Format :html does no parsing, just passes back raw XML for parsing by client
-        self.class.format :html
+      def initialize(*args)
+        super
       end
 
-      # Returns an XML string representation of a bib.  
+      # Returns a MARC::Record that contains the bib data
       # Every method call refreshes the data from the underlying API.
-      # Raises and exception if there are errors.
-      # Returns a HTTParty::Response.
+      # Raises an exception if the response is not valid XML or there are errors.
       def bib
-        @response = self.class.get(@uri+ "?view=full")
-        raise "Error getting bib from Aleph REST APIs. #{error}" unless error.nil?
-        return @response
+        self.response = self.class.get("#{record_url}?view=full")
+        raise_error_if("Error getting bib from Aleph REST APIs.") {
+          (response.parsed_response["get_record"].nil? or response.parsed_response["get_record"]["record"].nil?)
+        }
+        MARC::XMLReader.new(StringIO.new(xml(xml: response.body).at_xpath("get-record/record").to_xml(xml_options).strip)).first
       end
 
-      # Returns an array of items. Each item is represented as an HTTParty hash. 
+      # Returns an array of items. Each item is represented as a Hash.
       # Every method call refreshes the data from the underlying API.
       # Raises an exception if the response is not valid XML or there are errors.
-      # Returns a HTTParty::Response.
       def items
-        @items = []
-        self.class.format :xml
         # Since we're parsing xml, this will raise an error
         # if the response isn't xml.
-        @response = self.class.get(@uri+ "/items?view=full")
-        self.class.format :html
-        raise "Error getting items from Aleph REST APIs. #{error}" if not error.nil? or 
-          @response.nil? or @response["get_item_list"].nil? or @response["get_item_list"]["items"].nil?
-        item_list = @response["get_item_list"]["items"]["item"]
-        @items.push(item_list) if item_list.instance_of?(Hash)
-        item_list.each {|item|@items.push(item)} if item_list.instance_of?(Array)
-        # Rails.logger.warn("No items returned from Aleph in #{self.class}.") if @items.empty?
-        return @items
+        self.response = self.class.get("#{record_url}/items?view=full")
+        raise_error_if("Error getting items from Aleph REST APIs.") {
+          (response.parsed_response["get_item_list"].nil? or response.parsed_response["get_item_list"]["items"].nil?)
+        }
+        [response.parsed_response["get_item_list"]["items"]["item"]].flatten
       end
 
-      # Returns an XML string representation of holdings 
+      # Returns an array of holdings. Each holding is represented as a MARC::Record.
       # Every method call refreshes the data from the underlying API.
-      # Raises and exception if there are errors.
-      # Returns a HTTParty::Response.
+      # Raises an exception if there are errors.
       def holdings
-        @response = self.class.get(@uri+ "/holdings?view=full")
-        raise "Error getting holdings from Aleph REST APIs. #{error}" unless error.nil?
-        return @response
+        self.response = self.class.get("#{record_url}/holdings?view=full")
+        raise_error_if("Error getting holdings from Aleph REST APIs.") {
+          (response.parsed_response["get_hol_list"].nil? or response.parsed_response["get_hol_list"]["holdings"].nil?)
+        }
+        xml(xml: response.body).xpath("get-hol-list/holdings/holding").collect{ |holding|
+          # Change the tag name to record so that the MARC::XMLReader can parse it.
+          holding.name = "record"
+          MARC::XMLReader.new(StringIO.new(holding.to_xml(xml_options).strip)).first
+        }
+      end
+
+      def record_url
+        @record_url ||= "#{rest_url}/record/#{bib_library}#{record_id}"
       end
+      private :record_url
     end
   end
 end