bento_search 1.5.0 → 2.0.0.rc1

data/app/search_engines/bento_search/doaj_articles_engine.rb

@@ -4,10 +4,10 @@ require 'http_client_patch/include_client'
 require 'json'
 
 module BentoSearch
-  # DOAJ Articles search. 
+  # DOAJ Articles search.
   # https://doaj.org/api/v1/docs
   #
-  # Phrase searches with double quotes are respected. 
+  # Phrase searches with double quotes are respected.
   #
   # Supports #get by unique_id feature
   #
@@ -16,7 +16,7 @@ module BentoSearch
     include ActionView::Helpers::SanitizeHelper
 
 
-    class_attribute :http_timeout
+    class_attribute :http_timeout, instance_writer: false
     self.http_timeout = 10
 
     extend HTTPClientPatch::IncludeClient
@@ -36,7 +36,7 @@ module BentoSearch
         Rails.logger.debug("DoajEngine: requesting #{query_url}")
         response = http_client.get( query_url )
         json = JSON.parse(response.body)
-      rescue TimeoutError, HTTPClient::TimeoutError,
+      rescue BentoSearch::RubyTimeoutClass, HTTPClient::TimeoutError,
              HTTPClient::ConfigurationError, HTTPClient::BadResponseError,
              JSON::ParserError  => e
         results.error ||= {}
@@ -77,7 +77,7 @@ module BentoSearch
     def args_to_search_url(arguments)
       query = if arguments[:query].kind_of?(Hash)
         # multi-field query
-        arguments[:query].collect {|field, query| fielded_query(query, field)}.join(" ")
+        arguments[:query].collect {|field, query_value| fielded_query(query_value, field)}.join(" ")
       else
         fielded_query(arguments[:query], arguments[:search_field])
       end
@@ -85,7 +85,7 @@ module BentoSearch
       # We need to escape this for going in a PATH component,
       # not a query. So space can't be "+", it needs to be "%20",
       # and indeed DOAJ API does not like "+".
-      # 
+      #
       # But neither CGI.escape nor URI.escape does quite
       # the right kind of escaping, seems to work out
       # if we do CGI.escape but then replace '+'
@@ -98,7 +98,7 @@ module BentoSearch
       if arguments[:per_page]
         query_args["pageSize"]  = arguments[:per_page]
       end
-      
+
       if arguments[:page]
         query_args["page"]      = arguments[:page]
       end
@@ -115,14 +115,14 @@ module BentoSearch
       return url
     end
 
-    # Prepares a DOAJ API (elastic search) query component for 
+    # Prepares a DOAJ API (elastic search) query component for
     # given textual query in a given field (or default non-fielded search)
     #
     # Separates query string into tokens (bare words and phrases),
     # so they can each be made mandatory for ElasticSearch. Default
     # DOAJ API makes them all optional, with a very low mm, which
     # leads to low-precision odd looking results for standard use
-    # cases. 
+    # cases.
     #
     # Escapes all remaining special characters as literals (not including
     # double quotes which can be used for phrases, which are respected. )
@@ -133,7 +133,7 @@ module BentoSearch
     #
     # The "+" prefixed before field-name is to make sure all separate
     # fields are also mandatory when doing multi-field searches. It should
-    # make no difference for a single-field search. 
+    # make no difference for a single-field search.
     def fielded_query(query, field = nil)
       if field.present?
         "+#{field}:(#{prepare_mandatory_terms(query)})"
@@ -143,12 +143,12 @@ module BentoSearch
     end
 
     # Takes a query string, prepares an ElasticSearch query
-    # doing what we want: 
+    # doing what we want:
     #   * tokenizes into bare words and double-quoted phrases
     #   * Escapes other punctuation to be literal not ElasticSearch operator.
     #     (Does NOT do URI escaping)
-    #   * Makes each token mandatory with an ElasticSearch "+" operator prefixed. 
-    def prepare_mandatory_terms(query)      
+    #   * Makes each token mandatory with an ElasticSearch "+" operator prefixed.
+    def prepare_mandatory_terms(query)
       # use string split with regex to too-cleverly split into space
       # seperated terms and phrases, keeping phrases as unit.
       terms = query.split %r{[[:space:]]+|("[^"]+")}
@@ -174,13 +174,13 @@ module BentoSearch
 
       item.start_page = bibjson["start_page"]
       item.end_page   = bibjson["end_page"]
-      
+
       item.year       = bibjson["year"]
       if (year = bibjson["year"].to_i) && (month = bibjson["month"].to_i)
         if year != 0 && month != 0
           item.publication_date = Date.new(bibjson["year"].to_i, bibjson["month"].to_i)
         end
-      end      
+      end
 
       item.abstract   = sanitize(bibjson["abstract"]) if bibjson.has_key?("abstract")
 
@@ -222,9 +222,9 @@ module BentoSearch
     # punctuation that needs to be escaped and how to escape (backslash)
     # for ES documented here: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html
     #
-    # We do not escape double quotes, want to allow them for phrases. 
+    # We do not escape double quotes, want to allow them for phrases.
     #
-    # This method does NOT return URI-escaped, it returns literal, escaped for ES. 
+    # This method does NOT return URI-escaped, it returns literal, escaped for ES.
     def escape_query(q)
       q.gsub(/([\+\-\=\&\|\>\<\!\(\)\{\}\[\]\^\~\*\?\:\\\/])/) {|m| "\\#{$1}"}
     end
@@ -242,7 +242,7 @@ module BentoSearch
       { nil                     => {:semantic => :general},
         "bibjson.title"         => {:semantic => :title},
         # Using 'exact' seems to produce much better results for
-        # author, don't entirely understand what's up. 
+        # author, don't entirely understand what's up.
         "bibjson.author.name"   => {:semantic => :author},
         "publisher"             => {:semantic => :publisher},
         "bibjson.subject.term"  => {:semantic => :subject},
@@ -263,7 +263,7 @@ module BentoSearch
 
     def sort_definitions
       # Don't believe DOAJ supports sorting by author
-      {        
+      {
         "relevance" => {:implementation => nil}, # default
         "title" => {:implementation => "title:asc"},
         # We don't quite have publication date sorting, but we'll use
@@ -276,4 +276,4 @@ module BentoSearch
     end
 
   end
-end
+end

data/app/search_engines/bento_search/ebsco_host_engine.rb

@@ -131,14 +131,14 @@ class BentoSearch::EbscoHostEngine
     url = query_url(args)
 
     Rails.logger.debug("EbscoHostEngine Search for: #{url}")
-  
+
     results = BentoSearch::Results.new
     xml, response, exception = nil, nil, nil
 
     begin
       response = http_client.get(url)
       xml = Nokogiri::XML(response.body)
-    rescue TimeoutError, HTTPClient::ConfigurationError, HTTPClient::BadResponseError, Nokogiri::SyntaxError  => e
+    rescue BentoSearch::RubyTimeoutClass, HTTPClient::ConfigurationError, HTTPClient::BadResponseError, Nokogiri::SyntaxError  => e
         exception = e
     end
     # error handle
@@ -361,7 +361,7 @@ class BentoSearch::EbscoHostEngine
     query = if args[:query].kind_of?(Hash)
       # multi-field query
       args[:query].collect {|field, query| fielded_query(query, field)}.join(" AND ")
-    else 
+    else
       fielded_query(args[:query], args[:search_field])
     end
 

data/app/search_engines/bento_search/eds_engine.rb

@@ -7,145 +7,144 @@ require 'http_client_patch/include_client'
 
 
 #
-# For EBSCO Discovery Service. You will need a license to use. 
+# For EBSCO Discovery Service. You will need a license to use.
 #
 # == Required Configuration
 #
-# user_id, password: As given be EBSCO for access to EDS API (may be an admin account in ebscoadmin? Not sure). 
+# user_id, password: As given be EBSCO for access to EDS API (may be an admin account in ebscoadmin? Not sure).
 # profile: As given by EBSCO, might be "edsapi"?
 #
 # == Highlighting
 #
-# EDS has a query-in-context highlighting feature. It is used by defualt, set 
-# config 'highlighting' to false to disable. 
+# EDS has a query-in-context highlighting feature. It is used by defualt, set
+# config 'highlighting' to false to disable.
 # If turned on, you may get <b class="bento_search_highlight"> tags
-# in title and abstract output if it's on, marked html_safe.  
+# in title and abstract output if it's on, marked html_safe.
 #
 #
 # == Linking
 #
 # The link to record in EBSCO interface delivered as "PLink" will be listed
-# as record main link. 
+# as record main link. If the record includes a node at `./FullText/Links/Link/Type[text() = 'pdflink']`,
+# the `plink` will be marked as fulltext. (There may be other cases of fulltext, but
+# this seems to be all EDS API tells us.)
 #
 # Any links listed under <CustomLinks> will be listed as other_links, using
-# configured name provided by EBSCO for CustomLink.
+# configured name provided by EBSCO for CustomLink. Same with links listed
+# as `<Item><Group>URL</Group>`.
 #
-# EDS Response does not have sufficient metadata for us to generate an OpenURL
-# ourselves. However, in our testing, the first/only CustomLink was an
-# an OpenURL. If configuration.assume_first_custom_link_openurl is
-# true (as is default), it will be used to create an OpenURL link. However, in
-# our testing, many records don't have this at all. **Note** You want 
-# to configure your profile so OpenURLs are ALWAYS included for all records, not
-# just records with no EBSCO fulltext, to ensure bento_search can get the
-# openurl. http://support.ebsco.com/knowledge_base/detail.php?id=1111 (May
-# have to ask EBSCO support for help, it's confusing!). 
+# As always, you can customize links and other_links with Item Decorators.
 #
-# TODO: May have to add configuration code to pull the OpenURL link out by
-# it's configured name or label, not assume first one is it. 
+# == Custom Data
 #
-# As always, you can customize links and other_links with Item Decorators. 
+# If present, there is a custom_data[:holdings] value, an array of
+# BentoSearch::EdsEngine::Holding objects, each of which has a #location
+# and #call_number. There will usually (always?) be at most 1 item in the
+# array, as far as we can tell from how EDS works.
 #
 # == Technical Notes and Difficulties
 #
-# This API is enormously difficult to work with. Also the response is very odd
-# to deal with and missing some key elements. We quite possibly got something
-# wrong or non-optimal in this implementation, but we did our best. 
+# This API is pretty difficult to work with, and the response has many
+# idiosyncratic undocumented parts.  We think we are currently
+# getting fairly complete citation detail out, at least for articles, but may be missing
+# some on weird edge cases, books/book chapters, etc)
 #
 # Auth issues may make this slow -- you need to spend a (not too speedy) HTTP
 # request making a session for every new end-user -- as we have no way to keep
-# track of end-users, we do it on every request in this implementation. 
+# track of end-users, we do it on every request in this implementation.
 #
-# Responses don't include much metadata -- we don't actually have journal title,
-# volume, issue, etc.  We probably _could_ parse it out of the OpenURL that's
-# there depending on your profile configuration, but we're not right now.
-# Instead we're using the chunk of user-displayable citation/reference it does
-# give us (which is very difficult to parse into something usable already),
-# and a custom Decorator to display that instead of normalized citation
-# made from individual elements. 
-#
-# EBSCO says they plan to improve some of these issues in a September 2012 release. 
+# An older version of the EDS API returned much less info, and we tried
+# to scrape out what we could anyway. Much of this logic is still there
+# as backup. In the older version, not enough info was there for an
+# OpenURL link, `configuration.assume_first_custom_link_openurl` was true
+# by default, and used to create an OpenURL link. It now defaults to false,
+# and should no longer be neccessary.
 #
 # Title and abstract data seems to be HTML with tags and character entities and
-# escaped special chars. We're trusting it and passing it on as html_safe. 
+# escaped special chars. We're trusting it and passing it on as html_safe.
 #
 # Paging can only happen on even pages, with 'page' rather than 'start'. But
-# you can pass in 'start' to bento_search, it'll be converted to closest page. 
+# you can pass in 'start' to bento_search, it'll be converted to closest page.
 #
 # == Authenticated Users
 #
-# EDS allows searches by unauthenticated users, but the results come back with 
+# EDS allows searches by unauthenticated users, but the results come back with
 # weird blank hits. In such a case, the BentoSearch adapter will return
 # records with virtually no metadata, but a title e
 # (I18n at bento_search.eds.record_not_available ). Also no abstracts
-# are available from unauth search. 
+# are available from unauth search.
 #
 # By default the engine will search as 'guest' unauth user. But config
 # 'auth' key to true to force all searches to auth (if you are protecting your
-# app) or pass :auth => true as param into #search method.  
+# app) or pass :auth => true as param into #search method.
 #
 # == Source Types
 # # What the EBSCO 'source types' mean: http://suprpot.ebsco.com/knowledge_base/detail.php?id=5382
 #
-# But "Dissertations" not "Dissertations/Theses". "Music Scores" not "Music Score". 
+# But "Dissertations" not "Dissertations/Theses". "Music Scores" not "Music Score".
 
 #
 # == EDS docs:
-# 
-# * Console App to demo requests: https://eds-api.ebscohost.com/Console   
+#
+# * Console App to demo requests: <
 # * EDS Wiki: http://edswiki.ebscohost.com/EDS_API_Documentation
 # * You'll need to request an account to the EDS wiki, see: http://support.ebsco.com/knowledge_base/detail.php?id=5990
-# 
+#
 
 class BentoSearch::EdsEngine
   include BentoSearch::SearchEngine
-  
+
   # Can't change http timeout in config, because we keep an http
-  # client at class-wide level, and config is not class-wide. 
-  # Change this 'constant' if you want to change it, I guess. 
+  # client at class-wide level, and config is not class-wide.
+  # We used to keep in constant, but that's not good for custom setting,
+  # we now use class_attribute, but in a weird backwards-compat way for
+  # anyone who might be using the constant.
   HttpTimeout = 4
-  extend HTTPClientPatch::IncludeClient  
+
+  class_attribute :http_timeout, instance_writer: false
+  def self.http_timeout
+    defined?(@http_timeout) ? @http_timeout : HttpTimeout
+  end
+
+
+  extend HTTPClientPatch::IncludeClient
   include_http_client do |client|
-    client.connect_timeout = client.send_timeout = client.receive_timeout = HttpTimeout
+    client.connect_timeout = client.send_timeout = client.receive_timeout = http_timeout
   end
-    
+
   AuthHeader          = "x-authenticationToken"
   SessionTokenHeader  = "x-sessionToken"
 
   @@remembered_auth = nil
   @@remembered_auth_lock = Mutex.new
   # Class variable to save current known good auth
-  # uses a mutex to be threadsafe. sigh. 
+  # uses a mutex to be threadsafe. sigh.
   def self.remembered_auth
-    @@remembered_auth_lock.synchronize do      
+    @@remembered_auth_lock.synchronize do
       @@remembered_auth
     end
   end
-  # Set class variable with current known good auth. 
-  # uses a mutex to be threadsafe. 
+  # Set class variable with current known good auth.
+  # uses a mutex to be threadsafe.
   def self.remembered_auth=(token)
     @@remembered_auth_lock.synchronize do
       @@remembered_auth = token
     end
   end
-  
+
   # an object that includes some Rails helper modules for
-  # text handling. 
+  # text handling.
   def helper
-    unless @helper
-      @helper = Object.new
-      @helper.extend ActionView::Helpers::TextHelper # for truncate
-      @helper.extend ActionView::Helpers::OutputSafetyHelper # for safe_join
-    end
-    return @helper
+    @helper ||= Helper.new
   end
-  
-  
+
+
   def self.required_configuration
     %w{user_id password profile}
   end
-  
+
   # From config or args, args over-ride config
-  def authenticated_end_user?(args)    
+  def authenticated_end_user?(args)
     config = configuration.auth ? true : false
     arg = args[:auth]
     if ! arg.nil?
@@ -156,164 +155,269 @@ class BentoSearch::EdsEngine
       false
     end
   end
-  
+
   def construct_search_url(args)
     query = "AND,"
     if args[:search_field]
       query += "#{args[:search_field]}:"
     end
     # Can't have any commas in query, it turns out, although
-    # this is not documented. 
+    # this is not documented.
     query += args[:query].gsub(",", " ")
-    
+
     url = "#{configuration.base_url}search?view=detailed&query=#{CGI.escape query}"
-    
+
     url += "&searchmode=#{CGI.escape configuration.search_mode}"
-    
+
     url += "&highlight=#{configuration.highlighting ? 'y' : 'n' }"
-    
+
     if args[:per_page]
       url += "&resultsperpage=#{args[:per_page]}"
     end
     if args[:page]
       url += "&pagenumber=#{args[:page]}"
     end
-    
+
     if args[:sort]
       if (defn = self.sort_definitions[args[:sort]]) &&
            (value = defn[:implementation] )
         url += "&sort=#{CGI.escape value}"
       end
     end
-    
+
     if configuration.only_source_types.present?
       # facetfilter=1,SourceType:Research Starters,SourceType:Books
       url += "&facetfilter=" + CGI.escape("1," + configuration.only_source_types.collect {|t| "SourceType:#{t}"}.join(","))
     end
-    
-    
+
+
     return url
   end
-  
-  
-  
+
+
+
   def search_implementation(args)
     results = BentoSearch::Results.new
-    
+
     end_user_auth = authenticated_end_user? args
-    
+
     begin
       with_session(end_user_auth) do |session_token|
-                        
+
         url = construct_search_url(args)
-             
-        
-        
+
         response = get_with_auth(url, session_token)
-        
+
         results = BentoSearch::Results.new
-        
-        if (hits_node = at_xpath_text(response, "./SearchResponseMessageGet/SearchResult/Statistics/TotalHits"))          
+
+        if (hits_node = at_xpath_text(response, "./SearchResponseMessageGet/SearchResult/Statistics/TotalHits"))
           results.total_items = hits_node.to_i
         end
-        
+
         response.xpath("./SearchResponseMessageGet/SearchResult/Data/Records/Record").each do |record_xml|
           item = BentoSearch::ResultItem.new
-          
+
           item.title   = prepare_eds_payload( element_by_group(record_xml, "Ti"), true )
-          
+
           # To get a unique id, we need to pull out db code and accession number
-          # and combine em with colon, accession number is not unique by itself. 
+          # and combine em with colon, accession number is not unique by itself.
           db           = record_xml.at_xpath("./Header/DbId").try(:text)
           accession    = record_xml.at_xpath("./Header/An").try(:text)
           if db && accession
             item.unique_id    = "#{db}:#{accession}"
           end
-          
-          
+
+
           if item.title.nil? && ! end_user_auth
             item.title = I18n.translate("bento_search.eds.record_not_available")
           end
-          
+
           item.abstract = prepare_eds_payload( element_by_group(record_xml, "Ab"), true )
 
-          # Believe it or not, the authors are encoded as an escaped
-          # XML-ish payload, that we need to parse again and get the
-          # actual authors out of. WTF. Thanks for handling fragments
-          # nokogiri. 
-          author_mess = element_by_group(record_xml, "Au")
-          # only SOMETIMES does it have XML tags, other times it's straight text.
-          # ARGH.           
-          author_xml = Nokogiri::XML::fragment(author_mess)
-          searchLinks = author_xml.xpath(".//searchLink")
-          if searchLinks.size > 0
-            author_xml.xpath(".//searchLink").each do |author_node|
-              item.authors << BentoSearch::Author.new(:display => author_node.text)
+          # Much better way to get authors out of EDS response now...
+          author_full_names = record_xml.xpath("./RecordInfo/BibRecord/BibRelationships/HasContributorRelationships/HasContributor/PersonEntity/Name/NameFull")
+          author_full_names.each do |name_full_xml|
+            if name_full_xml && (text = name_full_xml.text).present?
+              item.authors << BentoSearch::Author.new(:display => text)
             end
-          else
-            item.authors << BentoSearch::Author.new(:display => author_xml.text)
           end
-          
-          
+
+          if item.authors.blank?
+            # Believe it or not, the authors are encoded as an escaped
+            # XML-ish payload, that we need to parse again and get the
+            # actual authors out of. WTF. Thanks for handling fragments
+            # nokogiri.
+            author_mess = element_by_group(record_xml, "Au")
+            # only SOMETIMES does it have XML tags, other times it's straight text.
+            # ARGH.
+            author_xml = Nokogiri::XML::fragment(author_mess)
+            searchLinks = author_xml.xpath(".//searchLink")
+            if searchLinks.size > 0
+              author_xml.xpath(".//searchLink").each do |author_node|
+                item.authors << BentoSearch::Author.new(:display => author_node.text)
+              end
+            else
+              item.authors << BentoSearch::Author.new(:display => author_xml.text)
+            end
+          end
+
           # PLink is main inward facing EBSCO link, put it as
-          # main link. 
+          # main link.
           if direct_link = record_xml.at_xpath("./PLink")
-              item.link = direct_link.text
+            item.link = direct_link.text
+
+            if record_xml.at_xpath("./FullText/Links/Link/Type[text() = 'pdflink']")
+              item.link_is_fulltext = true
+            end
           end
-          
+
+
           # Other links may be found in CustomLinks, it seems like usually
           # there will be at least one, hopefully the first one is the OpenURL?
-          record_xml.xpath("./CustomLinks/CustomLink").each do |custom_link|
+          #byebug if configuration.id == "articles"
+          record_xml.xpath("./CustomLinks/CustomLink|./FullText/CustomLinks/CustomLink").each do |custom_link|
+            # If it's in FullText section, give it a rel=alternate
+            # to indicate it's fulltext
+            rel = (custom_link.parent.parent.name.downcase == "fulltext") ? "alternate" : nil
+
             item.other_links << BentoSearch::Link.new(
               :url => custom_link.at_xpath("./Url").text,
-              :label => custom_link.at_xpath("./Name").text
+              :rel => rel,
+              :label => custom_link.at_xpath("./Text").try(:text).presence || custom_link.at_xpath("./Name").try(:text).presence || "Link"
               )
           end
-          
+
+          # More other links in 'URL' Item, in unpredictable format sometimes being
+          # embedded XML. Really EBSCO?
+          record_xml.xpath("./Items/Item[child::Group[text()='URL']]").each do |url_item|
+            data_element = url_item.at_xpath("./Data")
+            next unless data_element
+
+            # SOMETIMES the url and label are in an embedded escaped XML element...
+            if data_element.text.strip.start_with?("<link")
+              # Ugh, once unescpaed it has bare '&' in URL queries sometimes, which
+              # is not actually legal XML anymore, but Nokogiri::HTML parser will
+              # let us get away with it, but then doesn't put the actual text
+              # inside the 'link' item, but inside the <link> tag since it knows
+              # an HTML link tag has no content. Really EDS.
+              node = Nokogiri::HTML::fragment(data_element.text)
+              next unless link = node.at_xpath("./link")
+              next unless link["linkterm"].presence || link["linkTerm"].presence
+
+              item.other_links << BentoSearch::Link.new(
+                :url => link["linkterm"] || link["linkTerm"],
+                :label => helper.strip_tags(data_element.text).presence || "Link"
+                )
+            else
+              # it's just a straight URL in data element, with only label we've
+              # got in <label> element.
+              next unless data_element.text.strip.present?
+
+              label_element = url_item.at_xpath("./Label")
+              label = label_element.try(:text).try { |s| helper.strip_tags(s) }.presence || "Link"
+
+              item.other_links << BentoSearch::Link.new(
+                :url => data_element.text,
+                :label => label
+              )
+            end
+          end
+
+
           if (configuration.assume_first_custom_link_openurl &&
             (first = record_xml.xpath "./CustomLinks/CustomLink" ) &&
             (node = first.at_xpath "./Url" )
           )
-          
+
             openurl = node.text
-            
+
             index = openurl.index('?')
-            item.openurl_kev_co = openurl.slice index..(openurl.length) if index            
+            item.openurl_kev_co = openurl.slice index..(openurl.length) if index
           end
 
-          # Format. 
+          # Format.
           item.format_str = at_xpath_text record_xml, "./Header/PubType"
           # Can't find a list of possible PubTypes to see what's there to try
-          # and map to our internal controlled vocab. oh wells. 
-          
-          
-          
+          # and map to our internal controlled vocab. oh wells.
+
+          item.doi = at_xpath_text record_xml, "./RecordInfo/BibRecord/BibEntity/Identifiers/Identifier[child::Type[text()='doi']]/Value"
+
+          item.start_page = at_xpath_text(record_xml, "./RecordInfo/BibRecord/BibEntity/PhysicalDescription/Pagination/StartPage")
+          total_pages = at_xpath_text(record_xml, "./RecordInfo/BibRecord/BibEntity/PhysicalDescription/Pagination/PageCount")
+          if total_pages.to_i != 0 && item.start_page.to_i != 0
+            item.end_page = (item.start_page.to_i + total_pages.to_i - 1).to_s
+          end
+
+
+          # location/call number, probably only for catalog results. We only see one
+          # in actual data, but XML structure allows multiple, so we'll store it as multiple.
+          copy_informations = record_xml.xpath("./Holdings/Holding/HoldingSimple/CopyInformationList/CopyInformation")
+          if copy_informations.present?
+            item.custom_data[:holdings] =
+              copy_informations.collect do |copy_information|
+                Holding.new(:location => at_xpath_text(copy_information, "Sublocation"),
+                            :call_number => at_xpath_text(copy_information, "ShelfLocator"))
+              end
+          end
+
+
+
+          # For some EDS results, we have actual citation information,
+          # for some we don't.
+          container_xml = record_xml.at_xpath("./RecordInfo/BibRecord/BibRelationships/IsPartOfRelationships/IsPartOf/BibEntity")
+          if container_xml
+            item.source_title = at_xpath_text(container_xml, "./Titles/Title[child::Type[text()='main']]/TitleFull")
+            item.volume = at_xpath_text(container_xml, "./Numbering/Number[child::Type[text()='volume']]/Value")
+            item.issue = at_xpath_text(container_xml, "./Numbering/Number[child::Type[text()='issue']]/Value")
+
+            item.issn = at_xpath_text(container_xml, "./Identifiers/Identifier[child::Type[text()='issn-print']]/Value")
+
+            if date_xml = container_xml.at_xpath("./Dates/Date")
+              item.year = at_xpath_text(date_xml, "./Y")
+
+              date = at_xpath_text(date_xml, "./D").to_i
+              month = at_xpath_text(date_xml, "./M").to_i
+              if item.year.to_i != 0 && date != 0 && month != 0
+                item.publication_date = Date.new(item.year.to_i, month, date)
+              end
+            end
+          end
+
+          # EDS annoyingly repeats a monographic title in the same place
+          # we look for source/container title, take it away.
+          if item.start_page.blank? && helper.strip_tags(item.title) == item.source_title
+            item.source_title = nil
+          end
+
+          # Legacy EDS citation extracting. We don't really need this any more
+          # because EDS api has improved, but leave it in in case anyone using
+          # older versions needed it.
+
           # We have a single blob of human-readable citation, that's also
           # littered with XML-ish tags we need to deal with. We'll save
           # it in a custom location, and use a custom Decorator to display
           # it. Sorry it's way too hard for us to preserve <highlight>
           # tags in this mess, they will be lost. Probably don't
-          # need highlighting in source anyhow. 
+          # need highlighting in source anyhow.
           citation_mess = element_by_group(record_xml, "Src")
           # Argh, but sometimes it's in SrcInfo _without_ tags instead
-          if citation_mess          
+          if citation_mess
             citation_txt = Nokogiri::XML::fragment(citation_mess).text
             # But strip off some "count of references" often on the end
-            # which are confusing and useless. 
+            # which are confusing and useless.
             item.custom_data["citation_blob"] = citation_txt.gsub(/ref +\d+ +ref\.$/, '')
           else
             # try another location
             item.custom_data["citation_blob"] = element_by_group(record_xml, "SrcInfo")
           end
-          
-                              
+
           item.extend CitationMessDecorator
-          
+
           results << item
-        end        
+        end
       end
-      
-      return results      
+
+      return results
     rescue EdsCommException => e
       results.error ||= {}
       results.error[:exception] = e
@@ -321,137 +425,137 @@ class BentoSearch::EdsEngine
       results.error[:http_body] = e.http_body
       return results
     end
-    
+
   end
-  
+
   # Difficult to get individual elements out of an EDS XML <Record>
-  # response, requires weird xpath, so we do it for you. 
+  # response, requires weird xpath, so we do it for you.
   # element_by_group(nokogiri_element, "Ti")
   #
   # Returns string or nil
   def element_by_group(noko, group)
     at_xpath_text(noko, "./Items/Item[child::Group[text()='#{group}']]/Data")
   end
-  
+
   # Wraps calls to the EDS api with CreateSession and EndSession requests
   # to EDS. Will pass sessionID in yield from block.
   #
   # Second optional arg is whether this is an authenticated user, else
-  # guest access will be used. 
+  # guest access will be used.
   #
   #     with_session(true) do |session_token|
   #       # can make more requests using session_token,
-  #       # EndSession will be called for you at end of block. 
+  #       # EndSession will be called for you at end of block.
   #     end
   def with_session(auth = false, &block)
-    auth_token = self.class.remembered_auth    
+    auth_token = self.class.remembered_auth
     if auth_token.nil?
       auth_token = self.class.remembered_auth = get_auth_token
     end
-    
-            
-    create_url = "#{configuration.base_url}createsession?profile=#{configuration.profile}&guest=#{auth ? 'n' : 'y'}"    
-    response_xml = get_with_auth(create_url)    
-    
+
+
+    create_url = "#{configuration.base_url}createsession?profile=#{configuration.profile}&guest=#{auth ? 'n' : 'y'}"
+    response_xml = get_with_auth(create_url)
+
     session_token = nil
-    unless response_xml && (session_token = at_xpath_text(response_xml, "//SessionToken"))  
-      e = EdsCommException.new("Could not get SessionToken")      
+    unless response_xml && (session_token = at_xpath_text(response_xml, "//SessionToken"))
+      e = EdsCommException.new("Could not get SessionToken")
     end
-                
-    begin    
+
+    begin
       block.yield(session_token)
-    ensure      
-      if auth_token && session_token   
+    ensure
+      if auth_token && session_token
         end_url = "#{configuration.base_url}endsession?sessiontoken=#{CGI.escape session_token}"
-        response_xml = get_with_auth(end_url)        
+        response_xml = get_with_auth(end_url)
       end
     end
-    
+
   end
-  
-  # if the xpath responds, return #text of it, else nil. 
+
+  # if the xpath responds, return #text of it, else nil.
   def at_xpath_text(noko, xpath)
     node = noko.at_xpath(xpath)
-    
+
     if node.nil?
       return node
     else
       return node.text
     end
   end
-  
+
   # If EDS has put highlighting tags
   # in a field, we need to HTML escape the literal values,
   # while still using the highlighting tokens to put
   # HTML tags around highlighted terms.
   #
   # Second param, if to assume EDS literals are safe HTML, as they
-  # seem to be. 
+  # seem to be.
   def prepare_eds_payload(str, html_safe = false)
     return str if str.blank?
-    
+
     unless configuration.highlighting
-      str = str.html_safe if html_safe  
+      str = str.html_safe if html_safe
       return str
     end
-        
-    parts = 
+
+    parts =
     str.split(%r{(</?highlight>)}).collect do |substr|
       case substr
       when "<highlight>" then "<b class='bento_search_highlight'>".html_safe
       when "</highlight>" then "</b>".html_safe
-      # Yes, EDS gives us HTML in the literals, we're choosing to trust it. 
+      # Yes, EDS gives us HTML in the literals, we're choosing to trust it.
       else substr.html_safe
       end
     end
-        
-    return helper.safe_join(parts, '')        
+
+    return helper.safe_join(parts, '')
   end
-  
+
   # Give it a url pointing at EDS API.
-  # Second arg must be a session_token if EDS request requires one. 
-  # It will 
+  # Second arg must be a session_token if EDS request requires one.
+  # It will
   # * Make a GET request
   # * with memo-ized auth token added to headers
   # * for XML, with all namespaces removed!
   # * Parse JSON into a hash and return hash
   # * Try ONCE more to get if EBSCO says bad auth token
   # * Raise an EdsCommException if can't auth after second try,
-  #   or other error message, or JSON can't be parsed. 
+  #   or other error message, or JSON can't be parsed.
   def get_with_auth(url, session_token = nil)
     auth_token = self.class.remembered_auth
     unless auth_token
       auth_token = self.class.remembered_auth = get_auth_token
     end
-    
+
     response = nil
     response_xml = nil
     caught_exception = nil
-                
+
     begin
       headers = {AuthHeader => auth_token, 'Accept' => 'application/xml'}
       headers[SessionTokenHeader] = session_token if session_token
-      
+
       s_time = Time.now
       response = http_client.get(url, nil, headers)
       Rails.logger.debug("EDS timing GET: #{Time.now - s_time}:#{url}")
-      
+
       response_xml = Nokogiri::XML(response.body)
       response_xml.remove_namespaces!
-      
+
       if (at_xpath_text(response_xml, "//ErrorNumber") == "104") || (at_xpath_text(response_xml, "//ErrorDescription") == "Auth Token Invalid")
         # bad auth, try again just ONCE
         Rails.logger.debug("EDS auth failed, getting auth again")
-        
+
         headers[AuthHeader] = self.class.remembered_auth = get_auth_token
         response = http_client.get(url, nil, headers)
         response_xml = Nokogiri::XML(response.body)
-        response_xml.remove_namespaces!        
-      end            
-    rescue TimeoutError, HTTPClient::ConfigurationError, HTTPClient::BadResponseError, Nokogiri::SyntaxError => e
+        response_xml.remove_namespaces!
+      end
+    rescue BentoSearch::RubyTimeoutClass, HTTPClient::ConfigurationError, HTTPClient::BadResponseError, Nokogiri::SyntaxError => e
       caught_exception = e
     end
-    
+
     if response.nil? || response_xml.nil? || caught_exception ||  (! HTTP::Status.successful? response.status)
       exception = EdsCommException.new("Error fetching URL: #{caught_exception.message if caught_exception} : #{url}")
       if response
@@ -460,68 +564,68 @@ class BentoSearch::EdsEngine
       end
       raise exception
     end
-        
+
     return response_xml
   end
-  
-  
-  # Has to make an HTTP request to get EBSCO's auth token. 
+
+
+  # Has to make an HTTP request to get EBSCO's auth token.
   # returns the auth token. We aren't bothering to keep
   # track of the expiration ourselves, can't neccesarily trust
-  # it anyway. 
+  # it anyway.
   #
-  # Raises an EdsCommException on error. 
-  def get_auth_token    
+  # Raises an EdsCommException on error.
+  def get_auth_token
     # Can't send params as form-encoded, actually need to send a JSON or XML
-    # body, argh. 
-    
+    # body, argh.
+
     body = <<-EOS
       {
         "UserId":"#{configuration.user_id}",
         "Password":"#{configuration.password}"
       }
     EOS
-    
+
     s_time = Time.now
     response = http_client.post(configuration.auth_url, body, {'Accept' => "application/json", "Content-type" => "application/json"})
-    Rails.logger.debug("EDS timing AUTH: #{Time.now - s_time}s")    
-    
+    Rails.logger.debug("EDS timing AUTH: #{Time.now - s_time}s")
+
     unless HTTP::Status.successful? response.status
       raise EdsCommException.new("Could not get auth", response.status, response.body)
     end
-        
+
     response_hash = nil
     begin
       response_hash = MultiJson.load response.body
     rescue MultiJson::DecodeError
     end
-  
+
     unless response_hash.kind_of?(Hash) && response_hash.has_key?("AuthToken")
       raise EdsCommException.new("AuthToken not found in auth response", response.status, response.body)
     end
-    
-    return response_hash["AuthToken"]        
+
+    return response_hash["AuthToken"]
   end
-  
+
   def self.default_configuration
     {
       :auth_url => 'https://eds-api.ebscohost.com/authservice/rest/uidauth',
       :base_url => "http://eds-api.ebscohost.com/edsapi/rest/",
       :highlighting => true,
       :truncate_highlighted => 280,
-      :assume_first_custom_link_openurl => true,
+      :assume_first_custom_link_openurl => false,
       :search_mode => 'all' # any | bool | all | smart ; http://support.epnet.com/knowledge_base/detail.php?topic=996&id=1288&page=1
     }
   end
-  
-  def sort_definitions       
-    {        
+
+  def sort_definitions
+    {
       "date_desc"     => {:implementation => "date"},
       "relevance"     => {:implementation => "relevance" }
       #       "date_asc"      => {:implementaiton => "date2"}
     }
   end
-  
+
   def search_field_definitions
     {
       "TX" => {:semantic => :general},
@@ -534,11 +638,11 @@ class BentoSearch::EdsEngine
       "IB" => {:semantic => :isbn},
     }
   end
-  
-  # an exception talking to EDS api. 
+
+  # an exception talking to EDS api.
   # there's a short reason in #message, but also
   # possibly an http_status and http_body copied
-  # from error EDS response. 
+  # from error EDS response.
   class EdsCommException < ::BentoSearch::FetchError
     attr_accessor :http_status, :http_body
     def initialize(message, status = nil, body = nil)
@@ -547,16 +651,32 @@ class BentoSearch::EdsEngine
       self.http_body = body
     end
   end
-  
-  
+
+
   # A built-in decorator alwasy applied, that over-rides
   # the ResultItem#published_in display method to use our mess blob
   # of human readable citation, since we don't have individual elements
-  # to create it from in a normalized way. 
+  # to create it from in a normalized way.
   module CitationMessDecorator
     def published_in
       custom_data["citation_blob"]
     end
   end
-  
+
+  # a class that includes some Rails helper modules for
+  # text handling.
+  class Helper
+    include ActionView::Helpers::SanitizeHelper # for strip_tags
+    include ActionView::Helpers::TextHelper # for truncate
+    include ActionView::Helpers::OutputSafetyHelper # for safe_join
+  end
+
+  class Holding
+    attr_reader :location, :call_number
+    def initialize(args)
+      @location = args[:location]
+      @call_number = args[:call_number]
+    end
+  end
+
 end