jschairb-rets4r 1.1.18

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,28 @@
+module RETS4R
+  class Client
+    class ObjectHeader < Hash
+      include Net::HTTPHeader
+      def initialize(raw_header)
+        initialize_http_header( raw_header )
+      end
+    end
+    # Represents a RETS object (as returned by the get_object) transaction.
+    class DataObject
+      
+      attr_accessor :header, :data
+
+      alias :type :header
+      alias :info :type
+
+      def initialize(headers, data)
+        @header = ObjectHeader.new(headers) 
+        @data = data
+      end
+
+      def success?
+          return true if self.data
+          return false
+      end
+    end
+  end
+end

data/lib/rets4r/client/exceptions.rb

@@ -0,0 +1,116 @@
+module RETS4R
+  class Client
+    # This exception should be thrown when a generic client error is encountered.
+    class ClientException < Exception; end
+
+    # This exception should be thrown when there is an error with the parser, which is
+    # considered a subcomponent of the RETS client. It also includes the XML data that
+    # that was being processed at the time of the exception.
+    class ParserException < ClientException
+      attr_accessor :file
+    end
+
+    # The client does not currently support a specified action.
+    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.
+    class RETSException < RuntimeError; end
+
+    # There was a problem with logging into the RETS server.
+    class LoginError < RETSException; end
+
+    # For internal client use only, it is thrown when the a RETS request is made but a password
+    # is prompted for.
+    class AuthRequired < RETSException; end
+
+    # A RETS transaction failed
+    class RETSTransactionException < RETSException; end
+
+    # Search Transaction Exceptions
+    class UnknownQueryFieldException < RETSTransactionException; end
+    class NoRecordsFoundException < RETSTransactionException; end
+    class InvalidSelectException < RETSTransactionException; end
+    class MiscellaneousSearchErrorException < RETSTransactionException; end
+    class InvalidQuerySyntaxException < RETSTransactionException; end
+    class UnauthorizedQueryException < RETSTransactionException; end
+    class MaximumRecordsExceededException < RETSTransactionException; end
+    class TimeoutException < RETSTransactionException; end
+    class TooManyOutstandingQueriesException < RETSTransactionException; end
+    class DTDVersionUnavailableException < RETSTransactionException; end
+
+    # GetObject Exceptions
+    class InvalidResourceException < RETSTransactionException; end
+    class InvalidTypeException < RETSTransactionException; end
+    class InvalidIdentifierException < RETSTransactionException; end
+    class NoObjectFoundException < RETSTransactionException; end
+    class UnsupportedMIMETypeException < RETSTransactionException; end
+    class UnauthorizedRetrievalException < RETSTransactionException; end
+    class ResourceUnavailableException < RETSTransactionException; end
+    class ObjectUnavailableException < RETSTransactionException; end
+    class RequestTooLargeException < RETSTransactionException; end
+    class TimeoutException < RETSTransactionException; end
+    class TooManyOutstandingRequestsException < RETSTransactionException; end
+    class MiscellaneousErrorException < RETSTransactionException; end
+
+    EXCEPTION_TYPES = {
+      # Search Transaction Reply Codes
+      20200 => UnknownQueryFieldException,
+      20201 => NoRecordsFoundException,
+      20202 => InvalidSelectException,
+      20203 => MiscellaneousSearchErrorException,
+      20206 => InvalidQuerySyntaxException,
+      20207 => UnauthorizedQueryException,
+      20208 => MaximumRecordsExceededException,
+      20209 => TimeoutException,
+      20210 => TooManyOutstandingQueriesException,
+      20514 => DTDVersionUnavailableException,
+
+      # GetObject Reply Codes
+      20400 => InvalidResourceException,
+      20401 => InvalidTypeException,
+      20402 => InvalidIdentifierException,
+      20403 => NoObjectFoundException,
+      20406 => UnsupportedMIMETypeException,
+      20407 => UnauthorizedRetrievalException,
+      20408 => ResourceUnavailableException,
+      20409 => ObjectUnavailableException,
+      20410 => RequestTooLargeException,
+      20411 => TimeoutException,
+      20412 => TooManyOutstandingRequestsException,
+      20413 => MiscellaneousErrorException
+
+    }
+  end
+end

data/lib/rets4r/client/links.rb

@@ -0,0 +1,32 @@
+require 'uri'
+
+module RETS4R #:nodoc:
+  class Client #:nodoc:
+    class Links < Hash
+      attr_accessor :logger
+      def self.from_login_url(login_url)
+        links = self.new
+        links['Login'] = URI.parse(login_url)
+        links
+      end
+      def login
+        self['Login']
+      end
+      def logout
+        self['Logout']
+      end
+      def metadata
+        self['GetMetadata']
+      end
+      def objects
+        self['GetObject']
+      end
+      def search
+        self['Search']
+      end
+      def action
+        self['Action']
+      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/parsers/compact.rb

@@ -0,0 +1,42 @@
+# 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] &&
+                    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.to_s.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.nil? || k.empty? }
+
+          result << row_result
+        end
+
+        return result
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+require 'nokogiri'
+module RETS4R
+  class Client
+    class CompactNokogiriParser
+      include Enumerable
+      def initialize(io)
+        @doc    = CompactDocument.new
+        @parser = Nokogiri::XML::SAX::Parser.new(@doc)
+        @io     = io
+      end
+
+      def to_a
+        @parser.parse(@io) if @doc.results.empty?
+        @doc.results
+      end
+
+      def each(&block)
+        @doc.proc = block.to_proc
+        @parser.parse(@io)
+        nil
+      end
+
+      class CompactDocument < Nokogiri::XML::SAX::Document
+        attr_reader :results
+        attr_writer :proc
+
+        def initialize
+          @results = []
+        end
+        def start_element name, attrs = []
+          case name
+          when 'DELIMITER'
+            @delimiter = attrs.last.to_i.chr
+          when 'COLUMNS'
+            @columns_element = true
+            @string = ''
+          when 'DATA'
+            @data_element = true
+            @string = ''
+          when 'RETS'
+            handle_body_start attrs
+          end
+        end
+
+        def end_element name
+          case name
+          when 'COLUMNS'
+            @columns_element = false
+            @columns = @string.split(@delimiter)
+          when 'DATA'
+            @data_element = false
+            handle_row
+          end
+        end
+
+        def characters string
+          if @columns_element
+            @string << string
+          elsif @data_element
+            @string << string
+          elsif @reply_code
+            throw string
+            @reply_code = false
+          end
+        end
+
+        private
+        def handle_row
+          data = make_hash
+          if @proc
+            @proc.call(data)
+          else
+            @results << data
+          end
+        end
+        def handle_body_start attrs
+          attrs = Hash[*attrs]
+          if exception_class = Client::EXCEPTION_TYPES[attrs['ReplyCode'].to_i]
+            raise exception_class.new(attrs['ReplyText'])
+          end
+        end
+        def make_hash
+          @columns.zip(@string.split(@delimiter)).inject({}) do | h,(k,v) |
+            h[k] = v unless k.empty?
+            next h
+          end
+        end
+      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,100 @@
+require 'rets4r/client/transaction'
+require 'rets4r/client/parsers/compact'
+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] ? doc.get_elements('/RETS/RETS-RESPONSE')[0] : doc.get_elements('/RETS')[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
+
+        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 && transaction.reply_code.to_i != 20201
+          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', 'COMPACT-DECODED'
+            type = RETS4R::Client::CompactDataParser
+          else
+            raise "Invalid format #{name}"
+        end
+        type.new
+      end
+    end
+  end
+end
+