epo-ops 0.1.6 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14d4527d80492bc9c65e4b9119155f8efbd5f306
-  data.tar.gz: 0ef4446294943bb1bcaf0af3bc34d3443c80d1fa
+  metadata.gz: e40ce1dbaed083f38c18e4e0f40f66f80381d270
+  data.tar.gz: 7a69709812e5be2687ff4ccae2d7aa69372e3bf2
 SHA512:
-  metadata.gz: 09e15e977dc99780a2519fec1b87328205b57aabc86fc02cfa26b755eae6680fc2c3cda513c53d357dac42a69315603a9b0108f0ceeab2b4d9459301ee5b9478
-  data.tar.gz: 2cb69673d63c1a3250a17002b110ada59db528837ae6adf36c9d2f728a8ed918e941f305c30ef3038787c2b7ed88811de5900e6bf5108d76ff181b2bfb03ff54
+  metadata.gz: 6092ddb5f55b92f9156c5360f1436d3242468c00f2e40b21fd9fe50240f4c333ce7d8562022cdb7af9eb6aca59236c22171b6b2d72a4dd628bb9558422c75bbe
+  data.tar.gz: f26525ce447f0882581228ea0bdc52c86a01aa90bd2b2be6f76e1b52c4f92ec00e59d3b6d3ffa785eb105ecb8122b6126ec7ade6f81bba20d4c9efdfaf701859

data/.gitignore

@@ -35,3 +35,6 @@ Gemfile.lock
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+# IDEs
+/.idea/

data/.travis.yml

@@ -1,5 +1,5 @@
 language: ruby
 rvm:
-  - 2.2.7
-  - 2.3.4
-  - 2.4.1
+  - "2.0.0"
+  - "2.1.0"
+  - "2.2.0"

data/README.md

@@ -4,15 +4,19 @@
 # epo-ops
 Ruby interface to the EPO Open Patent Services (OPS).
 
-You can play around with the API [here](https://developers.epo.org/).
-Documentation of it can be found [here](https://www.epo.org/searching-for-patents/technical/espacenet/ops.html) under `Downloads`.
+[Documentation can be found here](http://www.rubydoc.info/gems/epo-ops/)
+
+The EPO provides [playground](https://developers.epo.org/), where you can try
+out the methods. As well as [Documentation](https://www.epo.org/searching-for-patents/technical/espacenet/ops.html)
+of the different endpoints and detailed usage (see the 'Downloads' section).
 
 # Usage
 
-## Authentification
-In order to use this gem you need to register at the EPO for OAuth
-[here](https://developers.epo.org/user/register).
+## Authentication
+In order to use this gem you need to register at the [EPO for
+OAuth](https://developers.epo.org/user/register).
 Use your credentials by configuring
+
 ```ruby
 Epo::Ops.configure do |conf|
   conf.consumer_key = "YOUR_KEY"
@@ -20,15 +24,48 @@ Epo::Ops.configure do |conf|
 end
 ```
 
-## What works up to now
-* Search the EPO OPS register with `Epo::Ops::Register.search(query)`; use `Epo::Ops::SearchQueryBuilder` to build an appropriate request.
-* Get bibliographic info from the register, both for application and publication references (which you may retrieve with the search).
-* Bulk searching for all patents on a given date wih `Epo::Ops::Register::Bulk.all_queries(date)`. Note that patents are usually published on Wednesdays, if you find some on another weekday, please let us know.
-   This method currently returns all queries necessary to find all patents with `Epo::Ops::Register.search`
+## Quickstart
+### Search for Patents
+
+Get references to all Patents on a given date and IPC-class:
+
+```ruby
+Epo::Ops::Register.search("A", Date.new(2016,2 ,3))
+# or for all ipc classes
+Epo::Ops::Register.search(nil, Date.new(2016,2 ,3))
+```
+
+You can now retrieve the bibliographic entries of all these:
+
+```ruby
+references = Epo::Ops::Register.search(nil, Date.new(2016,2 ,3))
+references.map { |ref| Epo::Ops::Register.biblio(ref) }
+```
+This will return an object that helps parsing the result. See the documentation
+for more information
+
+Note that both operations take a considerable amount of time. Also you may not
+want to develop and test with many of these requests, as they can quite quickly
+excess the API limits. Also note that this methods use the `application`
+endpoint.
+
+## Custom Retrieval
 
-### #search
-Use the `SearchQueryBuilder` to set up the queries. By default structs are returned that should make it easier to work with the results, but with the `raw`-flag set to true you may also retrieve the resulting hash and parse it yourself.
-The results have the method `#epodoc_reference` which perfectly fits into `#biblio`
+### #raw_search
+This allows you to build your own CQL query, as
+described in the official documentation. With the second parameter set
+to true you can get the raw result as a nested Hash, if you want to
+parse it yourself.
 
-### #biblio
-With `Epo::Ops::Register.biblio(reference_id)` you can retrieve the bibliographic entry for the given patent (see OPS documentation). By default it searches the `/application/` endpoint, but you may set `publication` as the second parameter. Make sure the `reference_id` matches the given type. The last optional parameter allows you to set another format the id, but the default `epodoc` is strongly advised. This format is also provided from search results with `#epodoc_reference`.
+```ruby
+Epo::Ops::Register.raw_search("q=pd=20160203 and ic=D&Range=1-100", true)
+```
+
+### #raw_biblio
+If you do not want to retrieve via the `application` endpoint (say you want
+`publication`) this method gives you more fine-grained control. Make sure the
+`reference_id` you use matches the type.
+
+```ruby
+Epo::Ops::Register.raw_biblio('EP1000000', 'publication')
+```

data/epo-ops.gemspec

@@ -21,9 +21,14 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake', '~> 10.5'
   spec.add_development_dependency 'minitest', '~> 5.8'
+  spec.add_development_dependency 'mocha'
   spec.add_development_dependency 'vcr', '~> 2.9'
   spec.add_development_dependency 'webmock', '~> 1.22'
   spec.add_development_dependency 'simplecov'
 
+  spec.add_development_dependency 'redis'
+  spec.add_development_dependency 'connection_pool'
+
   spec.add_dependency 'oauth2', '~> 1.1'
+  spec.add_dependency 'httparty', '~> 0.13'
 end

data/lib/epo/ops.rb

@@ -2,6 +2,8 @@ require 'epo/ops/version'
 require 'epo/ops/token_store'
 require 'epo/ops/register'
 require 'epo/ops/search_query_builder'
+require 'epo/ops/ipc_class_hierarchy_loader'
+require 'epo/ops/ipc_class_util'
 
 module Epo
   module Ops

data/lib/epo/ops/bibliographic_document.rb

@@ -27,7 +27,7 @@ module Epo
 
       # @return [String] The URL at which you can query the original document.
       def url
-        @url ||= "https://ops.epo.org/#{Epo::Ops::API_VERSION}/rest-services/register/application/epodoc/#{application_nr}"
+        @url ||= "https://ops.epo.org/3.1/rest-services/register/application/epodoc/#{application_nr}"
       end
 
       # @return [String] the english title of the patent @note Titles are

data/lib/epo/ops/client.rb

@@ -3,9 +3,20 @@ require 'epo/ops/error'
 
 module Epo
   module Ops
+
+    # This is a wrapper for OAuth
     class Client
       # @return [OAuth2::Response]
       def self.request(verb, url, options = {})
+        do_request(verb, url, options)
+      rescue Error::AccessTokenExpired
+        Epo::Ops.config.token_store.reset
+        do_request(verb, url, options)
+      end
+
+      private
+
+      def self.do_request(verb, url, options = {})
         token = Epo::Ops.config.token_store.token
         response = token.request(verb, URI.encode(url), options)
         fail Error.from_response(response) unless response.status == 200

data/lib/epo/ops/error.rb

@@ -32,6 +32,8 @@ module Epo
       ServiceUnavailable = Class.new(ServerError)
       # Raised when EPO returns the HTTP status code 504
       GatewayTimeout = Class.new(ServerError)
+      # AccessToken has expired
+      AccessTokenExpired = Class.new(ClientError)
 
       ERRORS = {
         400 => Epo::Ops::Error::BadRequest,
@@ -59,6 +61,8 @@ module Epo
 
           if code == 403 && FORBIDDEN_MESSAGES[message]
             FORBIDDEN_MESSAGES[message].new(message, response.headers, code)
+          elsif code == 400 && response.headers['www-authenticate'] && response.headers['www-authenticate'].include?('Access Token expired')
+            Error::AccessTokenExpired.new('Access Token expired', response.headers, code)
           else
             ERRORS[code].new(message, response.headers, code)
           end

data/lib/epo/ops/ipc_class_hierarchy.rb

@@ -0,0 +1,148 @@
+module Epo
+  module Ops
+    # The hierarchy is a flat Hash, that helps finding all known ipc subclasses
+    # of a given class. It was parsed from the WIPO. It does not support all
+    # levels, as it would (currently unnecessarily) blow up this hash. It only
+    # finds the first two sub class levels, e.g. A45F.
+    class IpcClassHierarchy
+      Hierarchy = { 'A' => %w(A01 A21 A22 A23 A24 A41 A42 A43 A44 A45 A46 A47 A61 A62 A63 A99),
+                    'A01' => %w(A01B A01C A01D A01F A01G A01H A01J A01K A01L A01M A01N A01P),
+                    'A21' => %w(A21B A21C A21D),
+                    'A22' => %w(A22B A22C),
+                    'A23' => %w(A23B A23C A23D A23F A23G A23J A23K A23L A23N A23P),
+                    'A24' => %w(A24B A24C A24D A24F),
+                    'A41' => %w(A41B A41C A41D A41F A41G A41H),
+                    'A42' => %w(A42B A42C),
+                    'A43' => %w(A43B A43C A43D),
+                    'A44' => %w(A44B A44C),
+                    'A45' => %w(A45B A45C A45D A45F),
+                    'A46' => %w(A46B A46D),
+                    'A47' => %w(A47B A47C A47D A47F A47G A47H A47J A47K A47L),
+                    'A61' => %w(A61B A61C A61D A61F A61G A61H A61J A61K A61L A61M A61N A61P A61Q),
+                    'A62' => %w(A62B A62C A62D),
+                    'A63' => %w(A63B A63C A63D A63F A63G A63H A63J A63K),
+                    'A99' => ['A99Z'],
+                    'B' => %w(B01 B02 B03 B04 B05 B06 B07 B08 B09 B21 B22 B23 B24 B25 B26 B27 B28 B29 B30 B31 B32 B33 B41 B42 B43 B44 B60 B61 B62 B63 B64 B65 B66 B67 B68 B81 B82 B99),
+                    'B01' => %w(B01B B01D B01F B01J B01L),
+                    'B02' => %w(B02B B02C),
+                    'B03' => %w(B03B B03C B03D),
+                    'B04' => %w(B04B B04C),
+                    'B05' => %w(B05B B05C B05D),
+                    'B06' => ['B06B'],
+                    'B07' => %w(B07B B07C),
+                    'B08' => ['B08B'],
+                    'B09' => %w(B09B B09C),
+                    'B21' => %w(B21B B21C B21D B21F B21G B21H B21J B21K B21L),
+                    'B22' => %w(B22C B22D B22F),
+                    'B23' => %w(B23B B23C B23D B23F B23G B23H B23K B23P B23Q),
+                    'B24' => %w(B24B B24C B24D),
+                    'B25' => %w(B25B B25C B25D B25F B25G B25H B25J),
+                    'B26' => %w(B26B B26D B26F),
+                    'B27' => %w(B27B B27C B27D B27F B27G B27H B27J B27K B27L B27M B27N),
+                    'B28' => %w(B28B B28C B28D),
+                    'B29' => %w(B29B B29C B29D B29K B29L),
+                    'B30' => ['B30B'],
+                    'B31' => %w(B31B B31C B31D B31F),
+                    'B32' => ['B32B'],
+                    'B33' => ['B33Y'],
+                    'B41' => %w(B41B B41C B41D B41F B41G B41J B41K B41L B41M B41N),
+                    'B42' => %w(B42B B42C B42D B42F),
+                    'B43' => %w(B43K B43L B43M),
+                    'B44' => %w(B44B B44C B44D B44F),
+                    'B60' => %w(B60B B60C B60D B60F B60G B60H B60J B60K B60L B60M B60N B60P B60Q B60R B60S B60T B60V B60W),
+                    'B61' => %w(B61B B61C B61D B61F B61G B61H B61J B61K B61L),
+                    'B62' => %w(B62B B62C B62D B62H B62J B62K B62L B62M),
+                    'B63' => %w(B63B B63C B63G B63H B63J),
+                    'B64' => %w(B64B B64C B64D B64F B64G),
+                    'B65' => %w(B65B B65C B65D B65F B65G B65H),
+                    'B66' => %w(B66B B66C B66D B66F),
+                    'B67' => %w(B67B B67C B67D),
+                    'B68' => %w(B68B B68C B68F B68G),
+                    'B81' => %w(B81B B81C),
+                    'B82' => %w(B82B B82Y),
+                    'B99' => ['B99Z'],
+                    'C' => %w(C01 C02 C03 C04 C05 C06 C07 C08 C09 C10 C11 C12 C13 C14 C21 C22 C23 C25 C30 C40 C99),
+                    'C01' => %w(C01B C01C C01D C01F C01G),
+                    'C02' => ['C02F'],
+                    'C03' => %w(C03B C03C),
+                    'C04' => ['C04B'],
+                    'C05' => %w(C05B C05C C05D C05F C05G),
+                    'C06' => %w(C06B C06C C06D C06F),
+                    'C07' => %w(C07B C07C C07D C07F C07G C07H C07J C07K),
+                    'C08' => %w(C08B C08C C08F C08G C08H C08J C08K C08L),
+                    'C09' => %w(C09B C09C C09D C09F C09G C09H C09J C09K),
+                    'C10' => %w(C10B C10C C10F C10G C10H C10J C10K C10L C10M C10N),
+                    'C11' => %w(C11B C11C C11D),
+                    'C12' => %w(C12C C12F C12G C12H C12J C12L C12M C12N C12P C12Q C12R),
+                    'C13' => %w(C13B C13K),
+                    'C14' => %w(C14B C14C),
+                    'C21' => %w(C21B C21C C21D),
+                    'C22' => %w(C22B C22C C22F),
+                    'C23' => %w(C23C C23D C23F C23G),
+                    'C25' => %w(C25B C25C C25D C25F),
+                    'C30' => ['C30B'],
+                    'C40' => ['C40B'],
+                    'C99' => ['C99Z'],
+                    'D' => %w(D01 D02 D03 D04 D05 D06 D07 D21 D99),
+                    'D01' => %w(D01B D01C D01D D01F D01G D01H),
+                    'D02' => %w(D02G D02H D02J),
+                    'D03' => %w(D03C D03D D03J),
+                    'D04' => %w(D04B D04C D04D D04G D04H),
+                    'D05' => %w(D05B D05C),
+                    'D06' => %w(D06B D06C D06F D06G D06H D06J D06L D06M D06N D06P D06Q),
+                    'D07' => ['D07B'],
+                    'D21' => %w(D21B D21C D21D D21F D21G D21H D21J),
+                    'D99' => ['D99Z'],
+                    'E' => %w(E01 E02 E03 E04 E05 E06 E21 E99),
+                    'E01' => %w(E01B E01C E01D E01F E01H),
+                    'E02' => %w(E02B E02C E02D E02F),
+                    'E03' => %w(E03B E03C E03D E03F),
+                    'E04' => %w(E04B E04C E04D E04F E04G E04H),
+                    'E05' => %w(E05B E05C E05D E05F E05G),
+                    'E06' => %w(E06B E06C),
+                    'E21' => %w(E21B E21C E21D E21F),
+                    'E99' => ['E99Z'],
+                    'F' => %w(F01 F02 F03 F04 F15 F16 F17 F21 F22 F23 F24 F25 F26 F27 F28 F41 F42 F99),
+                    'F01' => %w(F01B F01C F01D F01K F01L F01M F01N F01P),
+                    'F02' => %w(F02B F02C F02D F02F F02G F02K F02M F02N F02P),
+                    'F03' => %w(F03B F03C F03D F03G F03H),
+                    'F04' => %w(F04B F04C F04D F04F),
+                    'F15' => %w(F15B F15C F15D),
+                    'F16' => %w(F16B F16C F16D F16F F16G F16H F16J F16K F16L F16M F16N F16P F16S F16T),
+                    'F17' => %w(F17B F17C F17D),
+                    'F21' => %w(F21H F21K F21L F21S F21V F21W F21Y),
+                    'F22' => %w(F22B F22D F22G),
+                    'F23' => %w(F23B F23C F23D F23G F23H F23J F23K F23L F23M F23N F23Q F23R),
+                    'F24' => %w(F24B F24C F24D F24F F24H F24J),
+                    'F25' => %w(F25B F25C F25D F25J),
+                    'F26' => ['F26B'],
+                    'F27' => %w(F27B F27D),
+                    'F28' => %w(F28B F28C F28D F28F F28G),
+                    'F41' => %w(F41A F41B F41C F41F F41G F41H F41J),
+                    'F42' => %w(F42B F42C F42D),
+                    'F99' => ['F99Z'],
+                    'G' => %w(G01 G02 G03 G04 G05 G06 G07 G08 G09 G10 G11 G12 G21 G99),
+                    'G01' => %w(G01B G01C G01D G01F G01G G01H G01J G01K G01L G01M G01N G01P G01Q G01R G01S G01T G01V G01W),
+                    'G02' => %w(G02B G02C G02F),
+                    'G03' => %w(G03B G03C G03D G03F G03G G03H),
+                    'G04' => %w(G04B G04C G04D G04F G04G G04R),
+                    'G05' => %w(G05B G05D G05F G05G),
+                    'G06' => %w(G06C G06D G06E G06F G06G G06J G06K G06M G06N G06Q G06T),
+                    'G07' => %w(G07B G07C G07D G07F G07G),
+                    'G08' => %w(G08B G08C G08G),
+                    'G09' => %w(G09B G09C G09D G09F G09G),
+                    'G10' => %w(G10B G10C G10D G10F G10G G10H G10K G10L),
+                    'G11' => %w(G11B G11C),
+                    'G12' => ['G12B'],
+                    'G21' => %w(G21B G21C G21D G21F G21G G21H G21J G21K),
+                    'G99' => ['G99Z'],
+                    'H' => %w(H01 H02 H03 H04 H05 H99),
+                    'H01' => %w(H01B H01C H01F H01G H01H H01J H01K H01L H01M H01P H01Q H01R H01S H01T),
+                    'H02' => %w(H02B H02G H02H H02J H02K H02M H02N H02P H02S),
+                    'H03' => %w(H03B H03C H03D H03F H03G H03H H03J H03K H03L H03M),
+                    'H04' => %w(H04B H04H H04J H04K H04L H04M H04N H04Q H04R H04S H04W),
+                    'H05' => %w(H05B H05C H05F H05G H05H H05K),
+                    'H99' => ['H99Z'] }
+    end
+  end
+end

data/lib/epo/ops/ipc_class_hierarchy_loader.rb

@@ -0,0 +1,62 @@
+require 'httparty'
+require 'epo/ops/ipc_class_util'
+
+module Epo
+  module Ops
+    # Usually this should only used internally.
+    # Loads the Hierarchy from the WIPO.
+    # This is used to update IpcClassHierarchy manually.
+    # At the beginning of the year the WIPO publishes a new list of IPC classes.
+    # The IpcClassHierarchy should then be updated. Make sure that the url is
+    # correct!
+    class IpcClassHierarchyLoader
+      # loads data from the WIPO
+      # @return [Hash]
+      def self.load
+        load_url
+      end
+
+      private
+
+      def self.load_url
+        url = 'http://www.wipo.int/ipc/itos4ipc/ITSupport_and_download_area/20160101/IPC_scheme_title_list/EN_ipc_section_#letter_title_list_20160101.txt'
+
+        # There is a file for every letter A-H
+        ('A'..'H').inject({}) do |mem, letter|
+          # Fetch the file from the server
+          response = HTTParty.get(url.gsub('#letter', letter), http_proxyaddr: proxy[:addr], http_proxyport: proxy[:port])
+          file = response.body
+          mem.merge! process_file(file)
+        end
+      end
+
+      def self.process_file(file)
+        # Process every line (There is a line for every class entry, name and description are separated by a \t)
+        file.each_line.inject(Hash.new { |h, k| h[k] = [] }) do |mem, line|
+          next if line.to_s.strip.empty?
+          ipc_class_generic, description = line.split("\t")
+
+          # Some entries in the files have the same ipc class, the first line is
+          # just some kind of headline, the second is the description we want.
+          ipc_class = Epo::Ops::IpcClassUtil.parse_generic_format(ipc_class_generic)
+          if ipc_class.length == 3
+            mem[ipc_class[0]] << ipc_class
+          elsif ipc_class.length == 4
+            mem[ipc_class[0, 3]] << ipc_class
+          end
+          mem
+        end
+      end
+
+      def self.proxy
+        # configure proxy
+        proxy_addr = nil
+        proxy_port = nil
+        unless ENV['http_proxy'].to_s.strip.empty?
+          proxy_addr, proxy_port = ENV['http_proxy'].gsub('http://', '').gsub('/', '').split(':')
+        end
+        { addr: proxy_addr, port: proxy_port }
+      end
+    end
+  end
+end

data/lib/epo/ops/ipc_class_util.rb

@@ -0,0 +1,73 @@
+require 'epo/ops/ipc_class_hierarchy'
+
+module Epo
+  module Ops
+    # Utility functions to work on Strings representing ipc classes.
+    class IpcClassUtil
+
+      # @return [Array] \['A', 'B', …, 'H'\]
+      def self.main_classes
+        %w( A B C D E F G H )
+      end
+
+      # check if the given ipc_class is valid as OPS search parameter
+      # @param [String] ipc_class an ipc class
+      # @return [Boolean]
+      def self.valid_for_search?(ipc_class)
+        ipc_class.match(/\A[A-H](\d{2}([A-Z](\d{1,2}\/\d{2,3})?)?)?\z/)
+      end
+
+      # There is a generic format for ipc classes that does not have
+      # the / as delimiter and leaves space for additions. This parses
+      # it into the format the register search understands
+      # @param [String] generic ipc class in generic format
+      # @return [String] reformatted ipc class
+      # @example
+      #   parse_generic_format('A01B0003140000') #=> 'A01B3/14'
+      def self.parse_generic_format(generic)
+        ipc_class = generic
+        if ipc_class.length > 4
+          match = ipc_class.match(/([A-Z]\d{2}[A-Z])(\d{4})(\d{6})$/)
+          ipc_class = match[1] + (match[2].to_i).to_s + '/' + process_number(match[3])
+        end
+        ipc_class
+      end
+
+      # @param [String] ipc_class an ipc_class
+      # @return [Array] List of all ipc classes one level more specific.
+      # @examples
+      #   children('A')   #=> ['A01', 'A21', 'A22', 'A23', ...]
+      #   children('A62') #=> ['A62B', 'A62C', 'A62D'],
+      # @raise [InvalidIpcClassError] if parameter is not a valid ipc class in
+      #   the format EPO understands
+      # @raise [LevelNotSupportedError] for parameters with ipc class depth >= 3
+      #   e.g. 'A62B' cannot be split further. It is currently not necessary to
+      #   do so, it would only blow up the gem, and you do not want to query for
+      #   all classes at the lowest level, as it takes too many requests.
+      def self.children(ipc_class)
+        return main_classes if ipc_class.nil?
+        valid = valid_for_search?(ipc_class)
+        fail InvalidIpcClassError, ipc_class unless valid
+        map = IpcClassHierarchy::Hierarchy
+        fail LevelNotSupportedError, ipc_class unless map.key? ipc_class
+        map[ipc_class]
+      end
+
+      # An ipc class in invalid format was given, or none at all.
+      class InvalidIpcClassError < StandardError; end
+      # It is currently not supported to split by the most specific class level.
+      # This would result in a large amount of requests.
+      class LevelNotSupportedError < StandardError; end
+
+      private
+
+      def self.process_number(number)
+        result = number.gsub(/0+$/, '')
+        result += '0' if result.length == 1
+        result = '00' if result.length == 0
+
+        result
+      end
+    end
+  end
+end

data/lib/epo/ops/register.rb

@@ -3,140 +3,115 @@ require 'epo/ops/client'
 require 'epo/ops/util'
 require 'epo/ops/bibliographic_document'
 require 'epo/ops/logger'
+require 'epo/ops/ipc_class_util'
 
 module Epo
   module Ops
-    # Access to the {http://ops.epo.org/3.2/rest-services/register register}
+    # Access to the {http://ops.epo.org/3.1/rest-services/register register}
     # endpoint of the EPO OPS API.
     #
     # By now you can search and retrieve patents by using the type `application`
     # in the `epodoc` format.
     #
     # Search queries are limited by size, not following these limits
-    # will result in errors.
+    # will result in errors. You should probably use {.search} which handles the
+    # limits itself.
+    #
+    # For more fine grained control use {.raw_search} and {.raw_biblio}
     #
     # @see Limits
     # @see SearchQueryBuilder
     class Register
-      # Helper class that assists in building the queries necessary to search
-      # for more patents than possible with one query respecting the given
-      # limits.
+      # A helper method which creates queries that take API limits into account.
+      # @param patent_count [Integer] number of overall results expected.
+      #   See {.published_patents_count}
       #
-      # @see Limits
-      class Bulk
-        # Helper method returning all unique register references on a given
-        # date. This is the same as executing all queries from {.all_queries}
-        # and making the results unique.
-        #
-        # @note Patents may have more than one IPC class, they would appear
-        #   more than once, this method filters these by `doc_number`
-        def self.all_register_references(date)
-          begin
-            queries = Bulk.all_queries(date)
-            search_entries = queries.flat_map do |query|
-              Register.search(query)
-            end
-          rescue ::Epo::Ops::Error::NotFound
-            return []
-          end
-          search_entries.map(&:application_reference)
-            .uniq(&:doc_number)
+      # @return [Array] of Strings, each a query to put into {Register.raw_search}
+      # @see Epo::Ops::Limits
+      def self.split_by_size_limits(ipc_class, date, patent_count)
+        max_interval = Limits::MAX_QUERY_INTERVAL
+        (1..patent_count).step(max_interval).map do |start|
+          range_end = [start + max_interval - 1, patent_count].min
+          Epo::Ops::SearchQueryBuilder.build(ipc_class, date, start, range_end)
         end
+      end
 
-        # Build the queries to search for all patents on a given date.
-        #
-        # The offset of EPOs register search may at max be 2000, if more patents
-        # are published on one day the queries must be split; here across the
-        # first level of ipc classification.
-        # At time of this writing they are mostly below 1000, there should be
-        # plenty of space for now.
-        #
-        # In case the limits change, they can be found in {Epo::Ops::Limits}
-        # Should there be more than 2000 patents in one class, a message will
-        # be logged, please file an Issue if that happens.
-        #
-        # @return [Array] containing all queries to put into {Register.search}.
-        # @note The queries are split by IPC-classes if necessary; Patents may
-        #   have more than one, you might get multiple references to the same
-        #   patent.
-        # @see .all_register_references
-        def self.all_queries(date)
-          overall_count = published_patents_count(date)
-          if overall_count > Limits::MAX_QUERY_RANGE
-            patent_count_by_ipc_classes(date).flat_map do |ipc_class, count|
-              builder = SearchQueryBuilder.new
-                        .publication_date(date.year, date.month, date.day)
-                        .and
-                        .ipc_class(ipc_class)
-              split_by_size_limits(builder, count)
-            end
-          else
-            builder = SearchQueryBuilder.new
-                      .publication_date(date.year, date.month, date.day)
-            split_by_size_limits(builder, overall_count)
-          end
+      # Makes the requests to find how many patents are in each top
+      # level ipc class on a given date.
+      #
+      # @param date [Date] date on which patents should be counted
+      # @return [Hash] Hash ipc_class => count (ipc_class A-H)
+      def self.patent_counts_per_ipc_class(date)
+        %w( A B C D E F G H ).inject({}) do |mem, icc|
+          mem[icc] = published_patents_counts(icc, date)
+          mem
         end
+      end
 
-        # @return [Hash] For all top level IPC classes (A-H) => count
-        def self.patent_count_by_ipc_classes(date)
-          ipc_classes = %w(A B C D E F G H)
-          ipc_classes.inject({}) do |mem, ipcc|
-            mem[ipcc] = published_patents_count(date, ipcc)
-            if mem[ipcc] > Limits::MAX_QUERY_RANGE
-              Logger.log("IPC class #{ipcc} has more than #{Epo::Ops::Limits::MAX_QUERY_RANGE} on #{date}. They can not all be retrieved. Please file this as an issue!")
-            end
-            mem
-          end
-        end
+      # @param date [Date]
+      # @param ipc_class [String] up to now should only be between A-H
+      # @return [Integer] number of patents with given parameters
+      def self.published_patents_counts(ipc_class = nil, date = nil)
+        query = SearchQueryBuilder.build(ipc_class, date, 1, 2)
+        minimum_result_set = Register.raw_search(query, true)
+        return 0 if minimum_result_set.empty?
+        minimum_result_set['world_patent_data']['register_search']['total_result_count'].to_i
+      end
 
-        # Splits the queries build by `query_builder` by the allowed intervals.
-        #
-        # @param query_builder [SearchQueryBuilder] with all settings made, but
-        #   not built yet.
-        # @param patent_count [Integer] number of overall results expected.
-        #   See {.published_patents_count}
-        #
-        # @return [Array] of Strings, each a query to put into {Register.search}
-        def self.split_by_size_limits(query_builder, patent_count)
-          max_interval = Limits::MAX_QUERY_INTERVAL
-          (1..patent_count).step(max_interval).map do |start|
-            query_builder.build(start, [start + max_interval - 1, patent_count].min)
-          end
-        end
+      # Search method returning all unique register references on a given
+      # date, with optional ipc_class.
+      # @note This method does more than one query; it may happen that you
+      #   exceed your API limits
+      # @return [Array] Array of {SearchEntry}
+      def self.search(ipc_class = nil, date = nil)
+        queries = all_queries(ipc_class, date)
+        search_entries = queries.flat_map { |query| raw_search(query) }
+        search_entries.uniq { |se| se.application_reference.epodoc_reference }
+      end
 
-        # makes a minimum request to find out how many patents are published on
-        # that date
-        #
-        # @return [Integer] number of patents on that date.
-        def self.published_patents_count(date, ipc_class = nil)
-          query = SearchQueryBuilder.new
-          query.publication_date(date.year, date.month, date.day)
-          query.and.ipc_class(ipc_class) if ipc_class
-          query = query.build(1, 2)
-          minimum_result_set = Register.search(query, true)
-          return 0 if minimum_result_set.empty?
-          minimum_result_set['world_patent_data']['register_search']['total_result_count'].to_i
+      # @return [Array] Array of Strings containing queries applicable to
+      #   {Register.raw_search}.
+      # builds all queries necessary to find all patent references on a given
+      # date.
+      def self.all_queries(ipc_class = nil, date = nil)
+        count = published_patents_counts(ipc_class, date)
+        if count > Limits::MAX_QUERY_RANGE
+          IpcClassUtil.children(ipc_class).flat_map { |ic| all_queries(ic, date) }
+        else
+          split_by_size_limits(ipc_class, date, count)
         end
       end
 
       # @param query A query built with {Epo::Ops::SearchQueryBuilder}
-      # @param raw if `true` the result will be the raw response as a nested hash.
-      # if false(default) the result will be parsed further, returning a list of [SearchEntry]
+      # @param raw if `true` the result will be the raw response as a nested
+      #   hash. if false(default) the result will be parsed further, returning a
+      #   list of [SearchEntry]
       # @return [Array] containing {SearchEntry}
-      def self.search(query, raw = false)
-        hash = Client.request(:get, register_api_string + query).parsed
+      def self.raw_search(query, raw = false)
+        hash = Client.request(:get, register_api_string + 'search?' + query).parsed
         return parse_search_results(hash) unless raw
         hash
+      rescue Epo::Ops::Error::NotFound
+        []
+      end
+
+      # @param search_entry [SearchEntry] a search entry which should be
+      #   retrieved.
+      # @return [BibliographicDocument] a parsed document.
+      def self.biblio(search_entry)
+        raw_biblio(search_entry.application_reference.epodoc_reference)
       end
 
-      # @param format epodoc is a format defined by the EPO for a
+      # @param reference_id [String] identifier for document. Format similar to
+      #   EP1000000
+      # @param format [String] epodoc is a format defined by the EPO for a
       #   document id. see their documentation.
-      # @param type may be `application` or `publication` make sure that the
-      #   `reference_id` is matching
-      # @param raw flag if the result should be returned as a raw Hash or
-      #   parsed as {BibliographicDocument}
+      # @param type [String] may be `application` or `publication` make sure
+      #   that the `reference_id` is matching
+      # @param raw [Boolean] flag if the result should be returned as a raw Hash
+      #   or parsed as {BibliographicDocument}
       # @return [BibliographicDocument, Hash]
-      def self.biblio(reference_id, type = 'application', format = 'epodoc', raw = false)
+      def self.raw_biblio(reference_id, type = 'application', format = 'epodoc', raw = false)
         request = "#{register_api_string}#{type}/#{format}/#{reference_id}/biblio"
         result = Client.request(:get, request).parsed
         raw ? result : BibliographicDocument.new(result)
@@ -170,7 +145,7 @@ module Epo
       end
 
       def self.register_api_string
-        "/#{Epo::Ops::API_VERSION}/rest-services/register/"
+        '/3.1/rest-services/register/'
       end
     end
   end

data/lib/epo/ops/search_query_builder.rb

@@ -5,39 +5,34 @@ module Epo
   module Ops
     # This Builder helps creating a search query using
     # {https://www.loc.gov/standards/sru/cql/ CQL} (Common Query Language or
-    # Contextual Query Language) with the identifies specified by the EPO in
-    # the OPS Documentation chapter 4.2 ( {https://www.epo.org/searching-for-patents/technical/espacenet/ops.html Link}
-    # - use tab Downloads and see file 'OPS version 3.2 documentation').
-    # Dont use a builder twice ;)
+    # Contextual Query Language) with the identifiers specified by the EPO in
+    # the OPS Documentation chapter 4.2 ({https://www.epo.org/searching-for-patents/technical/espacenet/ops.html Link})
+    # - use tab Downloads and see file 'OPS version 3.1 documentation').
     class SearchQueryBuilder
-      def initialize
-        @query = 'search?q='
+      # Build the query with the given parameters. Invalid ranges are fixed
+      # automatically and you will be notified about the changes
+      # @return [String]
+      def self.build(ipc_class, date, range_start = 1, range_end = nil)
+        validated_range = validate_range range_start, range_end
+        "q=#{build_params(ipc_class, date)}&Range=#{validated_range[0]}-#{validated_range[1]}"
       end
 
-      def publication_date(year, month, day)
-        @query << "pd=#{('%04d' % year) << ('%02d' % month) << ('%02d' % day)}"
-        self
-      end
+      private
 
-      def and
-        @query << ' and '
-        self
+      def self.build_params(ipc_class, date)
+        [build_date(date), build_class(ipc_class)].compact.join(' and ')
       end
 
-      def ipc_class(ipc_class)
-        @query << "ic=#{ipc_class}"
-        # TODO: ipc_class richtig formatieren
-        self
+      def self.build_date(date)
+        if date
+          "pd=#{('%04d' % date.year)}"\
+          "#{('%02d' % date.month)}"\
+          "#{('%02d' % date.day)}"
+        end
       end
 
-      # builds the search query ready to put into the register API. The
-      # parameters are validated with {#validate_range}.
-      # This does not change the query, several calls will allow you to
-      # create the same queries for different ranges.
-      def build(range_start = 1, range_end = nil)
-        range_end ||= range_start + Limits::MAX_QUERY_INTERVAL - 1
-        validated_range = validate_range range_start, range_end
-        @query + "&Range=#{validated_range[0]}-#{validated_range[1]}"
+      def self.build_class(ipc_class)
+        "ic=#{ipc_class}" if ipc_class
       end
 
       # Fixes the range given so that they meed the EPO APIs rules. The range
@@ -46,11 +41,11 @@ module Epo
       # distance covered.
       # @see Epo::Ops::Limits
       # @return array with two elements: [range_start, range_end]
-      def validate_range(range_start, range_end)
+      def self.validate_range(range_start, range_end)
         if range_start > range_end
           range_start, range_end = range_end, range_start
           Logger.log('range_start was bigger than range_end, swapped values')
-        elsif range_start == range_end || range_end - range_start > Limits::MAX_QUERY_INTERVAL - 1
+        elsif range_end - range_start > Limits::MAX_QUERY_INTERVAL - 1
           range_end = range_start + Limits::MAX_QUERY_INTERVAL - 1
           Logger.log("range invalid, set to: #{[range_start, range_end]}")
         end

data/lib/epo/ops/token_store.rb

@@ -8,10 +8,15 @@ module Epo
     #
     class TokenStore
       def token
-        return generate_token if !@token || @token.expired?
+        @token = generate_token if !@token || @token.expired?
+
         @token
       end
 
+      def reset
+        @token = nil
+      end
+
       protected
 
       def generate_token
@@ -19,10 +24,11 @@ module Epo
           Epo::Ops.config.consumer_key,
           Epo::Ops.config.consumer_secret,
           site: 'https://ops.epo.org/',
-          token_url: "/#{Epo::Ops::API_VERSION}/auth/accesstoken",
+          token_url: '/3.1/auth/accesstoken',
           raise_errors: false
         )
-        @token = client.client_credentials.get_token
+
+        client.client_credentials.get_token
       end
     end
   end

data/lib/epo/ops/token_store/redis.rb

@@ -13,20 +13,32 @@ module Epo
 
         def token
           token = nil
-          @redis.conn do |conn|
+          @redis.with do |conn|
             token = conn.get("epo_token_#{id}")
           end
 
           token.present? ? OAuth2::AccessToken.new(client, token) : generate_token
         end
 
+        def reset
+          @redis.with do |conn|
+            conn.del("epo_token_#{id}")
+          end
+        end
+
         private
 
+        def id
+          Digest::MD5.hexdigest(Epo::Ops.config.consumer_key + Epo::Ops.config.consumer_secret)
+        end
+
         def generate_token
-          super
-          Sidekiq.redis do |conn|
+          token = super
+
+          @redis.with do |conn|
             conn.set("epo_token_#{id}", token.token, ex: token.expires_in, nx: true)
           end
+
           token
         end
       end

data/lib/epo/ops/version.rb

@@ -1,6 +1,5 @@
 module Epo
   module Ops
-    VERSION = '0.1.6'.freeze
-    API_VERSION = '3.2'.freeze
+    VERSION = '0.2.5'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epo-ops
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.5
 platform: ruby
 authors:
 - Max Kießling
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-26 00:00:00.000000000 Z
+date: 2016-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -54,6 +54,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.8'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -96,6 +110,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: oauth2
   requirement: !ruby/object:Gem::Requirement
@@ -110,6 +152,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
 description: This gem allows simple access to the European Patent Offices (EPO) Open
   Patent Services (OPS) using their XML-API
 email: 
@@ -129,6 +185,9 @@ files:
 - lib/epo/ops/bibliographic_document.rb
 - lib/epo/ops/client.rb
 - lib/epo/ops/error.rb
+- lib/epo/ops/ipc_class_hierarchy.rb
+- lib/epo/ops/ipc_class_hierarchy_loader.rb
+- lib/epo/ops/ipc_class_util.rb
 - lib/epo/ops/limits.rb
 - lib/epo/ops/logger.rb
 - lib/epo/ops/rate_limit.rb
@@ -157,7 +216,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby interface to the European Patent Office API (OPS)