exlibris-primo 0.0.4 → 0.1.0

data/README.rdoc

@@ -1,3 +1,31 @@
 = Exlibris::Primo
 
-This project rocks and uses MIT-LICENSE.
+Exlibris::Primo offers a set of libraries for interacting with the ExLibris Primo APIs.
+
+== Exlibris::Primo::Searcher
+The Exlibris::Primo::Searcher class performs a search against Primo for given parameters
+and exposes the set of holdings (availibrary elements), rsrcs, tocs, and related links (addlink elements).
+
+== Example of Exlibris::Primo::Searcher in action
+  setup = {
+    :base_url => "http://primo.institution.edu", :vid => "VID", :institution => "INSTITUTION",
+    :config => {
+      "libraries" => 
+        {"library_code1" => "library_display_1", "library_code2" => "library_display_1"}, 
+      "statuses" => 
+        {"status_code1" => "status_display_1", "status_code2" => "status_display_2"}}
+  }
+  params = {
+     :primo_id => primo_id,
+     :isbn => isbn, 
+     :issn => issn,
+     :title => title,
+     :author => author,
+     :genre => genre
+  }
+  searcher = Exlibris::Primo::Searcher.new(setup, params)
+  count = search.count
+  holdings = searcher.holdings
+  rsrcs = searcher.rsrcs
+  tocs = searcher.tocs
+  related_links = searcher.related_links

data/lib/exlibris/primo/holding.rb

@@ -1,40 +1,46 @@
-# == Overview
-# Exlibris::Primo::Holding represents a Primo holding.
-# This class should be extended to create Primo source objects for 
-# expanding holdings information, linking to Primo sources, and storing 
-# additional metadata based on those sources.
-#
-# == 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 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
-#
-# 4.  The following instance variables will be saved in the view_data and will be available
-#     to a local holding partial:
-#     @record_id, @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
-#
-# 5.  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.
-#
-# == Examples
-# Example of Primo source implementations are:
-# * Exlibris::Primo::Source::Aleph
 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
+    #
+    # 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.
+    #
+    # == Examples
+    # Example of Primo source implementations are:
+    # * 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, 
@@ -149,12 +155,14 @@ module Exlibris
         end
       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
       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]
@@ -178,4 +186,4 @@ module Exlibris
       end
     end
   end
-end
+end

data/lib/exlibris/primo/related_link.rb

@@ -1,5 +1,6 @@
 module Exlibris
   module Primo
+    # == Overview
     # Class for handling Primo related links from links/addlink
     class RelatedLink
       @base_attributes = [ :record_id, :addlink, :url, :display,  :notes ]

data/lib/exlibris/primo/rsrc.rb

@@ -1,5 +1,6 @@
 module Exlibris
   module Primo
+    # == Overview
     # Class for handling Primo Rsrcs from links/linktorsrc
     class Rsrc
       @base_attributes = [ :record_id, :linktorsrc, :v, :url, :display, :institution_code, :origin, :notes ]

data/lib/exlibris/primo/searcher.rb

@@ -1,15 +1,18 @@
-# == Overview
-# Searcher searches Primo for records.
-# Searcher must have sufficient metadata to make 
-# the request. Sufficient means either:
-#     * We have a Primo doc id
-#     * We have either an isbn OR an issn
-#     * We have a title AND an author AND a genre
-# If none of these criteria are met, Searcher.search
-# will raise a RuntimeException. 
-
 module Exlibris
   module Primo
+    # == Overview
+    # Exlibris::Primo::Searcher searches Primo for records.
+    # Exlibris::Primo::Searcher must have sufficient metadata to make 
+    # the request. Sufficient means either:
+    #     * We have a Primo doc id
+    #     * We have either an isbn OR an issn
+    #     * We have a title AND an author AND a genre
+    # If none of these criteria are met, Exlibris::Primo::Searcher.search
+    # will log a warning in the Rails log.
+    # Exlibris::Primo::Searcher will populate the following instance variables
+    # accessible through readers:
+    #   :count, :holdings, :rsrcs, :tocs, :related_links
+    # The reader :response makes the full xml result available as a Nokogiri::XML::Document.
     class Searcher
       #@required_setup = [ :base_url ]
       #@setup_default_values = { :vid => "DEFAULT", :config => {} }
@@ -21,11 +24,12 @@ module Exlibris
       SEARCH_NS = {'search' => 'http://www.exlibrisgroup.com/xsd/jaguar/search'}
     
       # Instantiates the object and performs the search for based on the input search criteria.
-      # setup parameter requires { :base_url => http://primo.server.institution.edu }
+      # :setup parameter requires { :base_url => http://primo.institution.edu }
       # Other optional parameters are :vid => "view_id", :config => { Hash of primo config settings}
-      # search_params are a sufficient combination of 
-      # { :primo_id => "primo_1", :isbn => "ISBN", :issn => "ISSN", 
-      #   :title => "=Title", :author => "Author", :genre => "Genre" }
+      # Hash of config settings are 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"}}
+      # :search_params are a sufficient combination of 
+      #   { :primo_id => "primo_1", :isbn => "ISBN", :issn => "ISSN", :title => "Title", :author => "Author", :genre => "Genre" }
       def initialize(setup, search_params)
         @holdings = []
         @rsrcs = []

data/lib/exlibris/primo/source/aleph.rb

@@ -1,9 +1,9 @@
-# == Overview
-# Aleph is an Exlibris::Primo::Holding that provides a link to Aleph
-# and a request button based on config settings in the primo_config file.
 module Exlibris
   module Primo
     module Source
+      # == Overview
+      # Exlibris::Primo::Source::Aleph is an Exlibris::Primo::Holding that provides a link to Aleph
+      # and a request button based on config settings in the Primo config file.
       class Aleph < Exlibris::Primo::Holding
         @attribute_aliases = Exlibris::Primo::Holding.attribute_aliases.merge({
           :aleph_doc_library => :original_source_id, :aleph_sub_library => :library,

data/lib/exlibris/primo/toc.rb

@@ -1,5 +1,6 @@
 module Exlibris
   module Primo
+    # == Overview
     # Class for handling Primo TOCs from links/linktotoc
     class Toc
       @base_attributes = [ :record_id, :linktotoc, :url, :display,  :notes ]

data/lib/exlibris/primo/version.rb

@@ -1,5 +1,5 @@
 module Exlibris
   module Primo
-    VERSION = "0.0.4"
+    VERSION = "0.1.0"
   end
 end

data/lib/exlibris/primo/web_service.rb

@@ -1,16 +1,18 @@
-# Module for calling Primo Web Services
-# Please note the following:
-# * Be sure to configure the Primo Back Office with the relevant IPs to enable interaction via the Web Services
-# * This module does not parse the response but instead stores it as an Nokogiri::XML::Document for the calling classes to parse
 module Exlibris
   module Primo
+    # == Overview
+    # Module for calling Primo Web Services
+    # Please note the following:
+    # * Be sure to configure the Primo Back Office with the relevant IPs to enable interaction via the Web Services
+    # * This module does not parse the response but instead stores it as an Nokogiri::XML::Document for the calling classes to parse
     module WebService
       require 'nokogiri'
       require 'rexml/document'
 
       # WebServiceBase is the base class for all Primo Web Services
       # It can be extended but is not intended for use by itself
-      # To call a PrimoWebService must explicity call the method make_call.
+      # To call a PrimoWebService implementing classes must explicity 
+      # call the method make_call.
       class WebServiceBase
         attr_reader :response, :error
 
@@ -113,14 +115,10 @@ module Exlibris
       end
 
       # SearchBrief does a brief result search through the Primo APIs
-      # Not all options are currently supported
+      # Not all Primo API options are currently supported
       # Supported search params are
-      #   :isbn
-      #   :issn
-      #   :title
-      #   :author
-      #   :genre
-      # e.g. {:isbn => "0143039008", :title => "Travels with My Aunt"}
+      #   :isbn, :issn, :title :author, :genre
+      #   e.g. {:isbn => "0143039008", :title => "Travels with My Aunt"}
       # Invalid params will raise an exception
       class SearchBrief < Search
         def initialize(search_params, base_url, options={})
@@ -130,8 +128,8 @@ module Exlibris
         end
       end
 
-      # GetRecord get a primo record based on doc id
-      # Not all options are currently supported
+      # GetRecord get a Primo record based on doc id
+      # Not all Primo API options are currently supported
       class GetRecord < Search
         def initialize(doc_id, base_url, options={})
           additional_input=[]

data/test/dummy/log/test.log

@@ -1646,3 +1646,59 @@
    (0.1ms)  rollback transaction
    (0.0ms)  begin transaction
    (0.1ms)  rollback transaction
+   (1.5ms)  begin transaction
+   (0.0ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.0ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.0ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction
+   (0.0ms)  begin transaction
+   (0.1ms)  rollback transaction

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exlibris-primo
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-29 00:00:00.000000000 Z
+date: 2012-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &2160416640 !ruby/object:Gem::Requirement
+  requirement: &2152708140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 3.2.0
   type: :runtime
   prerelease: false
-  version_requirements: *2160416640
+  version_requirements: *2152708140
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2160416180 !ruby/object:Gem::Requirement
+  requirement: &2152707580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2160416180
+  version_requirements: *2152707580
 - !ruby/object:Gem::Dependency
   name: soap4r-ruby1.9
-  requirement: &2160415640 !ruby/object:Gem::Requirement
+  requirement: &2152706900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2160415640
+  version_requirements: *2152706900
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &2160415060 !ruby/object:Gem::Requirement
+  requirement: &2152706260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2160415060
+  version_requirements: *2152706260
 description: Library to work with Exlibris' Primo discovery system.
 email:
 - scotdalton@gmail.com