rets4r 0.8.2 → 0.8.3

data/CHANGELOG

@@ -1,3 +1,14 @@
+0.8.3
+	Added example #set_pre_request_block. (Fran�ois Beausoleil)
+	Allow a pre request block to be set for RETS4R::Client.  
+		This allows the caller to change the request in any meaningful way, such as adding a 
+		RETS-UA-Authorization header when appropriate. (Fran�ois Beausoleil)
+	Better response handling of HTTP errors. Response codes > 300 other than 401 now raise an 
+		HTTPError exception that encapsulates the HTTPResponse object.
+		401 errors raise a LoginError exception. (Scott Patterson)
+	Added in RETS specification error messages to reference. (Scott Patterson)
+	New Rakefile.  Install the rake gem and do 'rake test' to run the tests. (Fran�ois Beausoleil)
+	
 0.8.2
 	Added missing result parameter to Client#search's yield (Scott Patterson)
 	Added 1.7 to supported list and default version (Fran�ois Beausoleil)

data/lib/rets4r/client.rb

@@ -39,7 +39,30 @@ module RETS4R
 		SUPPORTED_RETS_VERSIONS = ['1.5', '1.7']
 		CAPABILITY_LIST   = ['Action', 'ChangePassword', 'GetObject', 'Login', 'LoginComplete', 'Logout', 'Search', 'GetMetadata', 'Update']
 		SUPPORTED_PARSERS = [] # This will be populated by parsers as they load
-
+		
+		# These are the response messages as defined in the RETS 1.5e2 and 1.7d6 specifications.
+		# Provided for convenience and are used by the HTTPError class to provide more useful
+		# messages.
+		RETS_HTTP_MESSAGES = {
+			'200' => 'Operation successful.',
+			'400' => 'The request could not be understood by the server due to malformed syntax.',
+			'401' => 'Either the header did not contain an acceptable Authorization or the username/password was invalid. The server response MUST include a WWW-Authenticate header field.',
+			'402' => 'The requested transaction requires a payment which could not be authorized.',
+			'403' => 'The server understood the request, but is refusing to fulfill it.',
+			'404' => 'The server has not found anything matching the Request-URI.',
+			'405' => 'The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.',
+			'406' => 'The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.',
+			'408' => 'The client did not produce a request within the time that the server was prepared to wait.',
+			'411' => 'The server refuses to accept the request without a defined Content-Length.',
+			'412' => 'Transaction not permitted at this point in the session.',
+			'413' => 'The server is refusing to process a request because the request entity is larger than the server is willing or able to process.',
+			'414' => 'The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret. This error usually only occurs for a GET method.',
+			'500' => 'The server encountered an unexpected condition which prevented it from fulfilling the request.',
+			'501' => 'The server does not support the functionality required to fulfill the request.',
+			'503' => 'The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.',
+			'505' => 'The server does not support, or refuses to support, the HTTP protocol version that was used in the request message.',
+		}
+	
 		attr_accessor :mimemap, :logger
 		
 		# We load our parsers here so that they can modify the client class appropriately. Because
@@ -82,6 +105,35 @@ module RETS4R
 			end
 		end
 		
+		# Assigns a block that will be called just before the request is sent.
+		# This block must accept three parameters:
+		# * self
+		# * Net::HTTP instance
+		# * Hash of headers
+		#
+		# The block's return value will be ignored.  If you want to prevent the request
+		# to go through, raise an exception.
+		#
+		# == Example
+		#
+		#  client = RETS4R::Client.new(...)
+		#  # Make a new pre_request_block that calculates the RETS-UA-Authorization header.
+		#  client.set_pre_request_block do |rets, http, headers|
+		#    a1 = Digest::MD5.hexdigest([headers["User-Agent"], @password].join(":"))
+		#    if headers.has_key?("Cookie") then
+		#      cookie = headers["Cookie"].split(";").map(&:strip).select {|c| c =~ /rets-session-id/i}
+		#      cookie = cookie ? cookie.split("=").last : ""
+		#    else
+		#      cookie = ""
+		#    end
+		#
+		#    parts = [a1, "", cookie, headers["RETS-Version"]]
+		#    headers["RETS-UA-Authorization"] = "Digest " + Digest::MD5.hexdigest(parts.join(":"))
+		#  end
+		def set_pre_request_block(&block)
+			@pre_request_block = block
+		end
+		
 		# We only allow external read access to URLs because they are internally set based on the
 		# results of various queries.
 		def urls
@@ -343,9 +395,8 @@ module RETS4R
 					'Content-ID'   => response['Content-ID']
 				}
 				
-				if response['Content-Length'].to_i > 100
+				if response['Transfer-Encoding'].to_s.downcase == "chunked" || response['Content-Length'].to_i > 100 then
 					data_object = DataObject.new(info, response.body)
-				
 					if block_given?
 						yield data_object
 						results += 1
@@ -466,6 +517,8 @@ module RETS4R
 					headers = @headers
 					headers.merge(header) unless header.empty?
 					
+					@pre_request_block.call(self, http, headers) if @pre_request_block
+					
 					logger.debug(headers.inspect) if logger
 					
 					@semaphore.unlock
@@ -477,6 +530,10 @@ module RETS4R
 					if response.code == '401'
 						# Authentication is required
 						raise AuthRequired
+					elsif response.code.to_i >= 300
+						# We have a non-successful response that we cannot handle
+						@semaphore.unlock if @semaphore.locked?
+						raise HTTPError.new(response)
 					else
 						cookies = []
 						if set_cookies = response.get_fields('set-cookie') then
@@ -494,6 +551,9 @@ module RETS4R
 						retry_auth -= 1
 						set_header('Authorization', Auth.authenticate(response, @username, @password, url.path, method, @headers['RETS-Request-ID'], get_user_agent, @nc))
 						retry
+					else
+						@semaphore.unlock if @semaphore.locked?
+						raise LoginError.new(response.message)
 					end
 				end		
 				
@@ -545,6 +605,36 @@ module RETS4R
 		class Unsupported < ClientException
 		end
 		
+		# The HTTP response returned by the server indicates that there was an error processing
+		# the request and the client cannot continue on its own without intervention.
+		class HTTPError < ClientException
+			attr_accessor :http_response
+			
+			# Takes a HTTPResponse object
+			def initialize(http_response)
+				self.http_response = http_response
+			end
+			
+			# Shorthand for calling HTTPResponse#code
+			def code
+				http_response.code
+			end
+			
+			# Shorthand for calling HTTPResponse#message
+			def message
+				http_response.message
+			end
+			
+			# Returns the RETS specification message for the HTTP response code
+			def rets_message
+				Client::RETS_HTTP_MESSAGES[code]
+			end
+			
+			def to_s
+				"#{code} #{message}: #{rets_message}"
+			end
+		end
+		
 		# A general RETS level exception was encountered. This would include HTTP and RETS 
 		# specification level errors as well as informative mishaps such as authentication being
 		# required for access.

data/test/client/tc_client.rb

@@ -94,13 +94,30 @@ module RETS4R
 
 		def test_returns_single_entity_object_in_a_single_element_array
 			@response.expects(:[]).with('content-type').at_least_once.returns("image/jpeg")
+			@response.expects(:[]).with('Transfer-Encoding').at_least_once.returns("")
 			@response.expects(:[]).with('Content-Length').at_least_once.returns(241)
 			@response.expects(:[]).with('Object-ID').at_least_once.returns("25478")
 			@response.expects(:[]).with('Content-ID').at_least_once.returns("5589")
 			@response.expects(:body).returns("\000"*241)
 
 			results = @rets.get_object("Property", "Photo", "392103:*")
-			assert_equal 1, results.size, "Client parsed two objects out of the request"
+			assert_equal 1, results.size, "Client parsed one object out of the request"
+			assert_kind_of RETS4R::Client::DataObject, results[0], "First result isn't a DataObject"
+			assert_equal "image/jpeg", results[0].type["Content-Type"], "Content-Type not copied"
+			assert_equal "5589", results[0].type["Content-ID"], "Content-ID not copied"
+			assert_equal "25478", results[0].type["Object-ID"], "Object-ID not copied"
+			assert_equal 241, results[0].data.size, "First object isn't 241 bytes in length"
+		end
+
+		def test_returns_single_entity_object_as_chunked_encoding_in_a_single_element_array
+			@response.expects(:[]).with('content-type').at_least_once.returns("image/jpeg")
+			@response.expects(:[]).with('Transfer-Encoding').at_least_once.returns("chunked")
+			@response.expects(:[]).with('Object-ID').at_least_once.returns("25478")
+			@response.expects(:[]).with('Content-ID').at_least_once.returns("5589")
+			@response.expects(:body).returns("\000"*241)
+
+			results = @rets.get_object("Property", "Photo", "392103:*")
+			assert_equal 1, results.size, "Client parsed one object out of the request"
 			assert_kind_of RETS4R::Client::DataObject, results[0], "First result isn't a DataObject"
 			assert_equal "image/jpeg", results[0].type["Content-Type"], "Content-Type not copied"
 			assert_equal "5589", results[0].type["Content-ID"], "Content-ID not copied"
@@ -110,6 +127,7 @@ module RETS4R
 
 		def test_yields_data_objects_to_block_and_returns_blocks_value
 			@response.expects(:[]).with('content-type').at_least_once.returns("image/jpeg")
+			@response.expects(:[]).with('Transfer-Encoding').at_least_once.returns("")
 			@response.expects(:[]).with('Content-Length').at_least_once.returns(241)
 			@response.expects(:[]).with('Object-ID').at_least_once.returns("25478")
 			@response.expects(:[]).with('Content-ID').at_least_once.returns("5589")

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.2
+rubygems_version: 0.9.4
 specification_version: 1
 name: rets4r
 version: !ruby/object:Gem::Version 
-  version: 0.8.2
-date: 2007-06-27 00:00:00 -07:00
+  version: 0.8.3
+date: 2008-01-03 00:00:00 -08:00
 summary: A native Ruby implementation of RETS (Real Estate Transaction Standard).
 require_paths: 
 - lib
@@ -34,29 +34,21 @@ files:
 - examples/client_metadata.rb
 - examples/client_search.rb
 - lib/rets4r
-- lib/rets4r.rb
 - lib/rets4r/auth.rb
 - lib/rets4r/client
-- lib/rets4r/client.rb
 - lib/rets4r/client/data.rb
 - lib/rets4r/client/dataobject.rb
 - lib/rets4r/client/metadata.rb
 - lib/rets4r/client/metadataindex.rb
 - lib/rets4r/client/parser
-- lib/rets4r/client/parser.rb
-- lib/rets4r/client/transaction.rb
 - lib/rets4r/client/parser/rexml.rb
 - lib/rets4r/client/parser/xmlparser.rb
+- lib/rets4r/client/parser.rb
+- lib/rets4r/client/transaction.rb
+- lib/rets4r/client.rb
+- lib/rets4r.rb
 - test/client
-- test/ts_all.rb
-- test/ts_client.rb
 - test/client/data
-- test/client/parser
-- test/client/tc_auth.rb
-- test/client/tc_client.rb
-- test/client/tc_metadataindex.rb
-- test/client/test_parser.rb
-- test/client/ts_all.rb
 - test/client/data/1.5
 - test/client/data/1.5/error.xml
 - test/client/data/1.5/invalid_compact.xml
@@ -64,8 +56,16 @@ files:
 - test/client/data/1.5/metadata.xml
 - test/client/data/1.5/search_compact.xml
 - test/client/data/1.5/search_unescaped_compact.xml
+- test/client/parser
 - test/client/parser/tc_rexml.rb
 - test/client/parser/tc_xmlparser.rb
+- test/client/tc_auth.rb
+- test/client/tc_client.rb
+- test/client/tc_metadataindex.rb
+- test/client/test_parser.rb
+- test/client/ts_all.rb
+- test/ts_all.rb
+- test/ts_client.rb
 - CONTRIBUTORS
 - README
 - LICENSE