jwulff-rets4r 1.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 John Wulff
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,7 @@
+= rets4r
+
+Description goes here.
+
+== Copyright
+
+Copyright (c) 2009 John Wulff. See LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 1
+:patch: 1

data/lib/rets4r/auth.rb

@@ -0,0 +1,73 @@
+require 'digest/md5'
+
+module RETS4R
+	class Auth
+		# This is the primary method that would normally be used, and while it 
+		def Auth.authenticate(response, username, password, uri, method, requestId, useragent, nc = 0)
+                        if response['www-authenticate'].blank?
+                          raise "Missing required header 'www-authenticate'. Got: #{response}"
+                        end
+
+			authHeader = Auth.parse_header(response['www-authenticate'])
+
+			cnonce = cnonce(useragent, password, requestId, authHeader['nonce'])
+			
+			authHash = calculate_digest(username, password, authHeader['realm'], authHeader['nonce'], method, uri, authHeader['qop'], cnonce, nc)
+			
+			header = ''
+			header << "Digest username=\"#{username}\", "
+			header << "realm=\"#{authHeader['realm']}\", "
+			header << "qop=\"#{authHeader['qop']}\", "
+			header << "uri=\"#{uri}\", "
+			header << "nonce=\"#{authHeader['nonce']}\", "
+			header << "nc=#{('%08x' % nc)}, "
+			header << "cnonce=\"#{cnonce}\", "
+			header << "response=\"#{authHash}\", "
+			header << "opaque=\"#{authHeader['opaque']}\""
+			
+			return header
+		end
+		
+		def Auth.calculate_digest(username, password, realm, nonce, method, uri, qop = false, cnonce = false, nc = 0)				
+			a1 = "#{username}:#{realm}:#{password}"
+			a2 = "#{method}:#{uri}"
+						
+			response = '';
+			
+			requestId = Auth.request_id unless requestId
+			
+			if (qop)			
+				throw ArgumentException, 'qop requires a cnonce to be provided.' unless cnonce
+				
+				response = Digest::MD5.hexdigest("#{Digest::MD5.hexdigest(a1)}:#{nonce}:#{('%08x' % nc)}:#{cnonce}:#{qop}:#{Digest::MD5.hexdigest(a2)}")
+			else
+				response = Digest::MD5.hexdigest("#{Digest::MD5.hexdigest(a1)}:#{nonce}:#{Digest::MD5.hexdigest(a2)}")
+			end
+		
+			return response
+		end
+		
+		def Auth.parse_header(header)
+			type = header[0, header.index(' ')]
+			args = header[header.index(' '), header.length].strip.split(',')
+	
+			parts = {'type' => type}
+			
+			args.each do |arg|
+				name, value = arg.split('=')
+				
+				parts[name.downcase.strip] = value.tr('"', '').strip
+			end
+			
+			return parts
+		end
+		
+		def Auth.request_id
+			Digest::MD5.hexdigest(Time.new.to_f.to_s)
+		end
+		
+		def Auth.cnonce(useragent, password, requestId, nonce)
+			Digest::MD5.hexdigest("#{useragent}:#{password}:#{requestId}:#{nonce}")
+		end
+	end
+end

data/lib/rets4r/client/data.rb

@@ -0,0 +1,14 @@
+module RETS4R
+	class Client
+		# Represents a row of data. Nothing more than a glorfied Hash with a custom constructor and a
+		# type attribute.
+		class Data < ::Hash
+			attr_accessor :type
+			
+			def initialize(type = false)
+				super
+				self.type = type
+			end
+		end
+	end
+end 

data/lib/rets4r/client/dataobject.rb

@@ -0,0 +1,20 @@
+module RETS4R
+	class Client
+		# Represents a RETS object (as returned by the get_object) transaction.
+		class DataObject
+			attr_accessor :type, :data
+			
+			alias :info :type
+			
+			def initialize(type, data)
+				self.type = type
+				self.data = data
+			end
+			
+			def success?
+				return true if self.data
+				return false
+			end
+		end
+	end
+end

data/lib/rets4r/client/metadata.rb

@@ -0,0 +1,15 @@
+require 'rets4r/client/data'
+
+module RETS4R
+	class Client
+		# Represents a set of metadata. It is simply an extended Array with type and attributes accessors.
+		class Metadata < Array
+			attr_accessor :type, :attributes
+			
+			def initialize(type = false)
+				self.type = type if type
+				self.attributes = {}
+			end
+		end
+	end
+end

data/lib/rets4r/client/metadataindex.rb

@@ -0,0 +1,82 @@
+module RETS4R
+	class Client
+		# Provides a means of indexing metadata to allow faster searching of it.
+		# This is in dire need of a review and cleanup, so I advise you not to use it until that has been done.
+		class MetadataIndex
+			# Constructor that takes an array of Metadata objects as its sole argument.
+			def initialize(metadata)
+				@metadata 	= metadata
+				@index	= index(@metadata)
+			end
+			
+			# WARNING! Not working properly (does NOT pass unit test)
+			# This is more of a free form search than #lookup, but it is also slower because it must iterate
+			# through the entire metadata array. This also returns multiple matches, which #lookup doesn't do.
+			def search(type, attributes = {})
+				matches = []
+				
+				@metadata.each do |meta|
+					catch :mismatch do
+						if meta.type == type
+							attributes.each do |k,v|
+								throw :mismatch unless meta.attributes[k] == v
+							end
+							
+							matches << meta
+						end
+					end
+				end
+				
+				return matches
+			end
+			
+			# This is a streamlined and probably the preferred method for looking up metadata because it
+			# uses a index to quickly access the data. The downside is that it is not very flexible. This also
+			# only returns one (the "best") match. If you need multiple matches, then you should use #search.
+			# Tests show about a 690% speed increase by using #lookup over #search, so you've been warned.
+			def lookup(type, *attributes)
+				key = type
+				key << attributes.join('')
+				
+				@index[key]
+			end
+			
+			private
+			
+			# Provided an array of metadata, it indexes it for faster lookup.
+			# Takes a +Metadata+ object as its argument.
+			def index(metadata)
+				index = {}
+				
+				metadata.each do |meta|
+					key = generate_key(meta)
+					
+					index[key] = meta
+				end
+				
+				return index
+			end
+			
+			# Used to generate the key for a specified piece of metadata. Takes a +Metadata+ object as its
+			# argument.
+			def generate_key(meta)
+				key = meta.type
+					
+				case (meta.type)
+					when 'METADATA-LOOKUP'
+						key << meta.attributes['Resource']
+					when 'METADATA-LOOKUP_TYPE'
+						key << meta.attributes['Resource'] << meta.attributes['Lookup']
+					when 'METADATA-CLASS'
+						key << meta.attributes['Resource']
+					when 'METADATA-OBJECT'
+						key << meta.attributes['Resource']
+					when 'METADATA-TABLE'
+						key << meta.attributes['Resource'] << meta.attributes['Class']
+				end
+				
+				return key
+			end
+		end
+	end
+end

data/lib/rets4r/client/parser.rb

@@ -0,0 +1,135 @@
+# This is the generic parser 
+#
+#	Supports responses, data, metadata, reply codes, and reply text.
+#
+#	Supports the following tags:
+#		RETS, METADATA-.*, MAXROWS, COLUMNS, DATA, COUNT, DELIMITER
+#
+#	Metadata is built as:
+#		(Metadata 1-> data row
+#		           -> data row),
+#		(Metadata 2 -> data row),
+#		etc.
+#
+#	Data is built as:
+#		Data 1, Data 2, Data N
+#
+#
+#	TODO
+#		Add comments/documentation
+#		Handle more tags (if any are unaccounted for)
+#   Handle standard (non-compact) output
+#		Case Insensitivity?
+# 	There is still some holdovers from the previous organization of parsers, and they should be cleaned
+# 	  up at some point.
+
+require 'cgi'
+
+module RETS4R
+	class Client
+		module Parser			
+			attr_accessor :output, :logger
+			
+			def initialize
+				@transaction = Transaction.new
+				@current	   = []
+				@output      = 2
+			end
+			
+			def get_transaction
+				@transaction
+			end
+					
+			#### Stream Listener Events
+			def tag_start(name, attrs)		
+				@current.push(name)
+	
+				case name
+					when 'RETS'
+						@transaction.reply_code = attrs['ReplyCode']
+						@transaction.reply_text = attrs['ReplyText']
+					when /METADATA.*/
+						@metadata = Metadata.new(name)
+						@metadata.attributes = attrs
+					when 'MAXROWS'
+						@transaction.maxrows = true
+					when 'COUNT'
+						@transaction.count     = attrs['Records'].to_i
+					when 'DELIMITER'
+						@transaction.delimiter = attrs['value'].to_i
+				end
+			end
+			
+			def text(text)
+				case @current[-1]
+					when 'COLUMNS'
+						@transaction.header = parse_compact_line(text, @transaction.ascii_delimiter)
+						
+					when 'DATA'
+						if @transaction.header.length > 0
+							data_type << parse_data(text, @transaction.header)
+						else
+							data_type << parse_compact_line(text, @transaction.ascii_delimiter)
+						end
+					
+					when 'RETS-RESPONSE'
+						@transaction.response = parse_key_value_body(text)
+				end
+			end
+			
+			def tag_end(name)
+				@current.pop
+				
+				@transaction.data << @metadata if name =~ /METADATA.*/
+			end
+			
+			#### Helper Methods
+			def clean_xml(xml)				
+				# This is a hack, and it assumes that we're using compact mode, but it's the easiest way to
+				# strip out those bad "<" and ">" characters that were not properly escaped...
+				xml.gsub!(/<DATA>(.*)<\/DATA>/i) do |match|
+					"<DATA>#{CGI::escapeHTML(CGI::unescapeHTML($1))}</DATA>"
+				end
+			end
+			
+			def data_type
+				if @current[-2].index('METADATA') === 0
+					return @metadata
+				else
+					return @transaction.data
+				end
+			end
+			
+			def parse_compact_line(data, delim = "\t")
+				begin
+					return data.to_s.strip.split(delim)
+				rescue
+					raise "Error while parsing compact line: #{$!} with data: #{data}"
+				end
+			end
+			
+			def parse_data(data, header)			
+				results = Data.new(@current[-2])
+				
+				parsed_data = parse_compact_line(data, @transaction.ascii_delimiter)
+				
+				header.length.times do |pos|
+					results[header[pos]] = parsed_data[pos]
+				end
+				
+				results
+			end
+			
+			def parse_key_value_body(data)
+				parsed = {}
+				
+				data.each do |line|
+					(key, value) = line.strip.split('=')
+					parsed[key] = value
+				end
+				
+				return parsed
+			end
+		end
+	end
+end

data/lib/rets4r/client/parsers/compact.rb

@@ -0,0 +1,41 @@
+# Parses XML response containing 'COMPACT' data format.
+
+require 'cgi'
+
+module RETS4R
+  class Client
+    class CompactDataParser
+      def parse_results(doc)
+
+        delimiter = doc.get_elements('/RETS/DELIMITER')[0].attributes['value'].to_i.chr
+        columns   = doc.get_elements('/RETS/COLUMNS')[0]
+        rows      = doc.get_elements('/RETS/DATA')
+
+        parse_data(columns, rows, delimiter)
+      end
+
+      def parse_data(column_element, row_elements, delimiter = "\t")
+
+        column_names = column_element.text.split(delimiter)
+
+        result = []
+
+        data = row_elements.each do |data_row|
+          data_row = data_row.text.split(delimiter)
+
+          row_result = {}
+
+          column_names.each_with_index do |col, x|
+            row_result[col] = data_row[x]
+          end
+
+          row_result.reject! { |k,v| k.blank? }
+
+          result << row_result
+        end
+
+        return result
+      end
+    end
+  end
+end

data/lib/rets4r/client/parsers/metadata.rb

@@ -0,0 +1,92 @@
+require 'rexml/document'
+require 'yaml'
+require 'rets4r/client/parsers/compact'
+
+module RETS4R
+  class Client
+    class MetadataParser
+
+      TAGS = [ 'METADATA-RESOURCE', 
+               'METADATA-CLASS', 
+               'METADATA-TABLE', 
+               'METADATA-OBJECT', 
+               'METADATA-LOOKUP', 
+               'METADATA-LOOKUP_TYPE' ]
+
+      def initialize()
+        @parser = RETS4R::Client::CompactDataParser.new
+      end
+
+      def parse_file(file = 'metadata.xml')
+        xml = File.read(file)
+        doc = REXML::Document.new(xml)
+        parse(doc)
+      end
+
+      def parse(doc)
+
+        rets_resources = {}
+
+        doc.get_elements('/RETS/*').each do |elem|
+          
+          next unless TAGS.include?(elem.name)
+
+          columns   = elem.get_elements('COLUMNS')[0]
+          rows      = elem.get_elements('DATA')
+
+          data = @parser.parse_data(columns, rows)
+
+          resource_id = elem.attributes['Resource']
+
+          case elem.name
+            when 'METADATA-RESOURCE'
+              data.each do |resource_info|
+                id = resource_info.delete('ResourceID')
+                rets_resources[id] = resource_info
+              end
+
+            when 'METADATA-CLASS'
+              data.each do |class_info|
+                class_name = class_info.delete('ClassName')
+                rets_resources[resource_id][:classes] ||= {} 
+                rets_resources[resource_id][:classes][class_name] = class_info
+              end
+
+            when 'METADATA-TABLE'
+              class_name = elem.attributes['Class']
+              data.each do |table_info|
+                system_name = table_info.delete('SystemName')
+                rets_resources[resource_id][:classes][class_name][:tables] ||= {} 
+                rets_resources[resource_id][:classes][class_name][:tables][system_name] = table_info
+              end
+            
+            when 'METADATA-OBJECT'
+              data.each do |object_info|
+                object_type = object_info.delete('ObjectType')
+                rets_resources[resource_id][:objects] ||= {} 
+                rets_resources[resource_id][:objects][object_type] = object_info
+              end
+
+            when 'METADATA-LOOKUP'
+              data.each do |lookup_info|
+                lookup_name = lookup_info.delete('LookupName')
+                rets_resources[resource_id][:lookups] ||= {} 
+                rets_resources[resource_id][:lookups][lookup_name] = lookup_info
+              end
+
+            when 'METADATA-LOOKUP_TYPE'
+              lookup = elem.attributes['Lookup']
+              rets_resources[resource_id][:lookup_types] ||= {}
+              rets_resources[resource_id][:lookup_types][lookup] = {}
+              data.each do |lookup_type_info|
+                value = lookup_type_info.delete('Value')
+                rets_resources[resource_id][:lookup_types][lookup][value] = lookup_type_info
+              end
+          end
+        end
+
+        rets_resources
+      end
+    end
+  end
+end

data/lib/rets4r/client/parsers/response_parser.rb

@@ -0,0 +1,103 @@
+require 'rets4r/client/transaction'
+require 'rexml/document'
+
+module RETS4R
+  class Client
+    class ResponseParser
+      def parse_key_value(xml)
+        parse_common(xml) do |doc|
+          parsed = nil
+          first_child = doc.get_elements('/RETS/RETS-RESPONSE')[0]
+          unless first_child.nil?
+            parsed = {}
+            first_child.text.each do |line|
+              (key, value) = line.strip.split('=')
+              key.strip! if key
+              value.strip! if value
+              parsed[key] = value
+            end
+          else
+            raise 'Response was not a proper RETS XML doc!'
+          end
+
+          if parsed.nil?
+            raise "Response was not valid key/value format"
+          else
+            parsed
+          end
+        end
+      end
+
+      def parse_results(xml, format)
+        parse_common(xml) do |doc|
+          parser = get_parser_by_name(format)
+          parser.parse_results(doc)
+        end
+      end
+
+      def parse_count(xml)
+        parse_common(xml) do |doc|
+          doc.get_elements('/RETS/COUNT')[0].attributes['Records']
+        end
+      end
+
+      def parse_metadata(xml, format)
+        parse_common(xml) do |doc|
+          return REXML::Document.new(xml)
+        end
+      end
+
+      def parse_object_response(xml)
+        parse_common(xml) do |doc|
+          # XXX
+        end
+      end
+
+      private
+
+      def parse_common(xml, &block)
+        if xml == ''
+          raise RETSException, 'No transaction body was returned!'
+        end
+
+        File.open('/tmp/meh', 'w') do |file|
+          file.write(xml)
+        end
+
+        doc = REXML::Document.new(xml)
+
+        root = doc.root
+        if root.nil? || root.name != 'RETS'
+          raise "Response had invalid root node. Document was: #{doc.inspect}"
+        end
+
+        transaction = Transaction.new
+        transaction.reply_code = root.attributes['ReplyCode']
+        transaction.reply_text = root.attributes['ReplyText']
+        transaction.maxrows    = (doc.get_elements('/RETS/MAXROWS').length > 0)
+
+
+        # XXX: If it turns out we need to parse the response of errors, then this will
+        # need to change.
+        if transaction.reply_code.to_i > 0
+          exception_type = Client::EXCEPTION_TYPES[transaction.reply_code.to_i] || RETSTransactionException
+          raise exception_type, "#{transaction.reply_code} - #{transaction.reply_text}"
+        end
+
+        transaction.response = yield doc
+        return transaction
+      end
+
+      def get_parser_by_name(name)
+        case name
+          when 'COMPACT'
+            type = RETS4R::Client::CompactDataParser
+          else
+            raise "Invalid format #{name}"
+        end
+        type.new
+      end
+    end
+  end
+end
+

data/lib/rets4r/client/transaction.rb

@@ -0,0 +1,34 @@
+module RETS4R
+  class Client
+    class Transaction
+      attr_accessor :reply_code, :reply_text, :response, :metadata, :header, :data, :maxrows, 
+        :count, :delimiter, :secondary_response
+      
+      def initialize
+        self.maxrows = false
+        self.header = []
+        self.data = []
+        self.delimiter = ?\t
+      end
+      
+      def success?
+        return true if self.reply_code == '0'
+        return false
+      end
+      
+      def has_data?
+        return true if self.data.length > 0
+        return false
+      end
+      
+      def maxrows?
+        return true if self.maxrows
+        return false
+      end
+      
+      def ascii_delimiter
+        self.delimiter.chr
+      end
+    end
+  end
+end