nolij_web 1.0.0 → 1.1.0

data/README.rdoc

@@ -1,6 +1,6 @@
 = NolijWeb
 
-Talk to the Nolij Web API. The first version of this gem contains a small subset of available API methods. Document submission/printing(retrieval) are the main focus. Methods for folder listings, work flow request, and generated urls for the viewer are provided.
+Talk to the Nolij Web API. This gem contains a subset of available API methods for the Nolij Web API. Document submission/printing(retrieval) are the main focus. Methods for folder listings, work flow request, and generated urls for the viewer are provided.
 
 The raw connection can be used to execute other types of requests.
 
@@ -20,26 +20,45 @@ Or install it yourself as:
 
 == Basic Usage
 
-You should be able to use the handler for basic requests.
+You should be able to use the handler for basic requests. Handler method options are based on the options from the Nolij Web API documentation. Underscores have been added to the option names.
+
   require 'nolij_web'
 
   handler = NolijWeb::Handler.new(config_hash_or_path_to_config_yaml)
 
-  handler.folder_info({:folder_id => 1111111})
+  handler.folder_info({:folder_id => '1111111'})
 
-Configuration can be passed as an assigned hash or read from a YAML file.
+=== Configuration
+Configuration can be passed as an assigned hash
   config = {
             :username => 'username',
             :password => 'password',
             :base_url => 'https://somedomain.com/NolijWeb'
            }
 
+Configuration can be read from a YAML file by passing the file path. The file should contain a hash structure:
+  ---
+  :username: 'username'
+  :password: 'password'
+  :base_url: 'https://somedomain.com/NolijWeb'
+
 == Passing a block to NolijWeb::Handler methods
 You may pass a custom block to handler methods. Please note that your block should return the response for successful request. Some of the methods rely on parsing XML responses from the server.
 
 == Using the Connection Directly
 
-You can use the handler's connection directly. See NolijWeb::Connection for info.
+You can use the handler's connection directly. An execute method has been provided to handle opening and closing of sessions. See NolijWeb::Connection for more info.
+  conn = NolijWeb::Connection.new(config_hash_or_path_to_config_yaml)
+  conn.execute() {
+    @folder_info = conn.get_custom_connection([conn.base_url, 'handler', 'api', 'docs', '1_1'].join('/'), conn.headers)
+    @doc_meta = conn.get_custom_connection([conn.base_url, 'handler', 'api', 'docs', '1_1', 123, 'documentmeta'].join('/'), conn.headers)
+  }
+
+You can also manually open and close connections if necessary:
+  conn = NolijWeb::Connection.new(config_hash_or_path_to_config_yaml)
+  conn.establish_connection
+    ... do some stuff with custom connection methods.
+  conn.close_connection
 
 == Contributing
 

data/lib/nolij_web/connection.rb

@@ -28,6 +28,7 @@ Be sure the close the connection when you are finished.
     attr_reader :username
     attr_reader :cookies
     attr_reader :connection
+    attr_reader :headers
 
     @@valid_config_keys = [:username, :password, :base_url]
 

data/lib/nolij_web/handler.rb

@@ -14,7 +14,7 @@ module NolijWeb
       @connection = Connection.new(@config)
     end
 
-    # Folder contents
+    # Folder contents as Nokogiri XML
     # required options: :folder_id
     # additional options: :user_code, :user_id, :sort, :offset, :limit, :wfma_code
     def folder_info(options = {}, &block)
@@ -31,6 +31,7 @@ module NolijWeb
       folder = Nokogiri.XML(response)
     end
 
+    # Folder contents as array
     # Returns an array of hashes with the file info for each file in the folder
     # See #folder_info for options
     def folder_contents(options = {}, &block)
@@ -83,7 +84,7 @@ module NolijWeb
     end
 
     # Print one or more documents to a single pdf
-    # required options: document_ids - can be a numer or an array of numbers
+    # required options: :document_id - can be a number or an array of numbers
     # additional options: :user_code, :document_id, :user_id
     def print_document(options = {}, &block)
       doc_ids = options.delete(:document_id)
@@ -98,6 +99,26 @@ module NolijWeb
       @connection.get relative_path, headers.merge(:params => query_params), &block
     end
 
+    # Return a jpeg of a page of a document
+    # required options: :document_id, :folder_id
+    # additional options: :user_code, :user_id, :rotation, :wpixels, :hpixels, :redact, :annot, :wfma_code, :page
+    # :page will default to 1 if no page is provided.
+    def retrieve_document_image(options = {}, &block)
+      folder_id = options[:folder_id]
+      document_id = options[:document_id].to_i
+      page = options[:page].to_i
+      page = page == 0 ? 1 : page
+      raise AttributeMissingError, 'Folder ID is required to retrieve a document.' unless folder_id.is_a?(String) && ! folder_id.empty?
+      raise AttributeMissingError, 'Document ID is required to retrieve a document.' unless document_id > 0
+
+      allowed_query_params_keys = [:user_code, :user_id, :rotation, :wpixels, :hpixels, :redact, :annot, :wfma_code]
+      query_params = format_query_params(options, allowed_query_params_keys)
+      headers = options[:headers] || {}
+      relative_path = [@@doc_handler_path, folder_id, document_id, 'page', page].join('/')
+
+      @connection.get relative_path, headers.merge(:params => query_params), &block
+    end
+
     # Delete a document
     # required options: :document_id, :folder_id
     # additional options: :user_code, :user_id, :wfma_code
@@ -115,6 +136,36 @@ module NolijWeb
       @connection.delete relative_path, headers.merge(:params => query_params), &block
     end
 
+    # Retrieve metadata for a document as XML
+    # required options: :document_id, :folder_id
+    # additional options: :user_code, :user_id, :start, :end, :wfma_code
+    def document_metadata_xml(options = {}, &block)
+      folder_id = options[:folder_id]
+      document_id = options[:document_id].to_i
+      raise AttributeMissingError, 'Folder ID is required to retrieve a document.' unless folder_id.is_a?(String) && ! folder_id.empty?
+      raise AttributeMissingError, 'Document ID is required to retrieve a document.' unless document_id > 0
+
+      allowed_query_params_keys = [:user_code, :user_id, :start, :end, :wfma_code]
+      query_params = format_query_params(options, allowed_query_params_keys)
+      headers = options[:headers] || {}
+      relative_path = [@@doc_handler_path, folder_id, document_id, 'documentmeta'].join('/')
+
+      response = @connection.get relative_path, headers.merge(:params => query_params), &block
+      doc = Nokogiri.XML(response)
+    end
+
+    # Retrieve metadata for a document as a hash
+    # see #document_metadata_xml for options
+    def document_metadata(options = {}, &block)
+      doc = document_metadata_xml(options, &block)
+      node = doc.xpath('/documentmeta').first
+      doc_metadata = node.attributes.inject({}){|n, (k,v)| n[k] = v.value; n}
+      doc_metadata['pages'] = node.xpath('//pagemeta').collect{|p|
+        p.attributes.inject({}){|n, (k,v)| n[k] = v.value; n}
+      }
+      return doc_metadata
+    end
+
     # URL or path to verify that user is authenticated to Nolijweb in their browser.
     # If the user is logged in redirect them to :redir path.
     # If not, redirect to login and return them to the URL provided once they've authenticated.

data/lib/nolij_web/version.rb

@@ -1,5 +1,5 @@
 module NolijWeb
   class Version
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/nolij_web.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = NolijWeb::Version::VERSION
   spec.authors       = ["Shannon Henderson"]
   spec.email         = ["shenders@reed.edu"]
-  spec.description   = %q{A Ruby wrapper for the Nolijweb API}
+  spec.description   = %q{A Ruby wrapper for the Nolij Web API}
   spec.summary       = %q{Interact with Nolijweb's REST API}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/reed-college/nolij_web/"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/test/nolij_web/handler_test.rb

@@ -111,6 +111,73 @@ describe NolijWeb::Handler do
     end
   end
 
+
+  describe '#retrieve_document_image' do
+    before do
+      @document_id = '12345'
+      @folder_id = '111_2'
+      @stubbed_request = stub_request(:get, /\/handler\/api\/docs\/#{@folder_id}\/#{@document_id}\/page\/1/).to_return(:status => 200)
+    end
+
+    it "should raise missing attribute if no document id supplied" do
+      err = lambda{@handler.retrieve_document_image(:folder_id => '1243')}.must_raise(NolijWeb::AttributeMissingError)
+      err.to_s.must_match /document ID is required/i
+    end
+
+    it "should raise missing attribute if no folder id supplied" do
+      err = lambda{@handler.retrieve_document_image(:document_id => '123')}.must_raise(NolijWeb::AttributeMissingError)
+      err.to_s.must_match /folder ID is required/i
+    end
+
+    it "should get document image" do
+      @handler.retrieve_document_image(:document_id => @document_id, :folder_id => @folder_id, :page => 1)
+      assert_requested @stubbed_request
+    end
+
+    it "should set page to 1 when no page" do
+      @handler.retrieve_document_image(:document_id => @document_id, :folder_id => @folder_id)
+      assert_requested @stubbed_request
+    end
+  end
+
+  describe "document_metadata methods" do
+    before do
+      @folder_id = '1_2'
+      @document_id = '1111'
+      response = File.new(File.join(File.expand_path(File.dirname(__FILE__)), 'test_stubs', 'document_metadata.xml'))
+      @stubbed_request = stub_request(:get, /\/handler\/api\/docs\/#{@folder_id}\/#{@document_id}\/documentmeta/).to_return(:status => 200, :body => response)
+    end
+
+    describe '#document_metadata_xml' do
+      it "should raise missing attribute if no folder id is supplied" do
+        err = lambda{@handler.document_metadata_xml(:document_id => @document_id)}.must_raise(NolijWeb::AttributeMissingError)
+        err.to_s.must_match /Folder ID is required/i
+      end
+
+      it "should raise missing attribute if no document_id is supplied" do
+        err = lambda{@handler.document_metadata_xml(:folder_id => @folder_id)}.must_raise(NolijWeb::AttributeMissingError)
+        err.to_s.must_match /document ID is required/i
+      end
+
+      it "should get stubbed url" do
+        document_metadata = @handler.document_metadata_xml(:folder_id => @folder_id, :document_id => @document_id)
+        assert_requested @stubbed_request
+      end
+
+      it "should return nokogiri xml document" do
+        document_metadata = @handler.document_metadata_xml(:folder_id => @folder_id, :document_id => @document_id)
+        document_metadata.must_be_kind_of(Nokogiri::XML::Document)
+      end
+    end
+
+    describe '#document_metadata' do
+      it "should return nokogiri a hash" do
+        document_metadata = @handler.document_metadata(:folder_id => @folder_id, :document_id => @document_id)
+        document_metadata.must_be_kind_of(Hash)
+      end
+    end
+  end
+
   describe '#viewer_url' do
     it "should raise missing attribute if no document id supplied" do
       err = lambda{@handler.viewer_url}.must_raise(NolijWeb::AttributeMissingError)

data/test/nolij_web/test_stubs/document_metadata.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<documentmeta documentid="1111" folderid="1_2" docname="AAPP Application" subfolder="Previous Apps" datecreated="2014-02-26 23:25:54.0 UTC" createdby="JOES" startpage="1" endpage="6" totalpagecount="6" filesize="1408598">
+  <pagemeta page="1" rotationquads="0" height="6600" width="5120" hasannotations="false"/>
+  <pagemeta page="2" rotationquads="0" height="6600" width="5120" hasannotations="false"/>
+  <pagemeta page="3" rotationquads="0" height="6600" width="5120" hasannotations="false"/>
+  <pagemeta page="4" rotationquads="0" height="6600" width="5120" hasannotations="true"/>
+  <pagemeta page="5" rotationquads="0" height="6600" width="5120" hasannotations="false"/>
+  <pagemeta page="6" rotationquads="0" height="6600" width="5120" hasannotations="false"/>
+</documentmeta>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nolij_web
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -107,7 +107,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.13'
-description: A Ruby wrapper for the Nolijweb API
+description: A Ruby wrapper for the Nolij Web API
 email:
 - shenders@reed.edu
 executables: []
@@ -135,6 +135,7 @@ files:
 - test/nolij_web/connection_test.rb
 - test/nolij_web/handler_test.rb
 - test/nolij_web/test_stubs/bad_nolij_config.yml
+- test/nolij_web/test_stubs/document_metadata.xml
 - test/nolij_web/test_stubs/document_submitted_success.xml
 - test/nolij_web/test_stubs/folder_info.xml
 - test/nolij_web/test_stubs/nolij_config.yml
@@ -142,7 +143,7 @@ files:
 - test/nolij_web/test_stubs/version_info.xml
 - test/nolij_web/version_test.rb
 - test/test_helper.rb
-homepage: ''
+homepage: https://github.com/reed-college/nolij_web/
 licenses:
 - MIT
 post_install_message: 
@@ -178,6 +179,7 @@ test_files:
 - test/nolij_web/connection_test.rb
 - test/nolij_web/handler_test.rb
 - test/nolij_web/test_stubs/bad_nolij_config.yml
+- test/nolij_web/test_stubs/document_metadata.xml
 - test/nolij_web/test_stubs/document_submitted_success.xml
 - test/nolij_web/test_stubs/folder_info.xml
 - test/nolij_web/test_stubs/nolij_config.yml