rets 0.1.0

data/lib/rets/metadata.rb

@@ -0,0 +1,6 @@
+require 'rets/metadata/containers'
+require 'rets/metadata/lookup_type'
+require 'rets/metadata/resource'
+require 'rets/metadata/rets_class'
+require 'rets/metadata/root'
+require 'rets/metadata/table'

data/lib/rets/metadata/containers.rb

@@ -0,0 +1,84 @@
+module Rets
+  module Metadata
+    #########################
+    # Basic representation of the underlying metadata. This models
+    # the structure of RETS metadata closely. The OO-representation
+    # uses this structure for its construction. External usage of
+    # this API should be discouraged in favor of the richer OO
+    # representation.
+    #
+    module Containers
+      class Container
+        attr_accessor :fragment
+
+        def self.uses(*fields)
+          fields.each do |field|
+            define_method(field) do
+              instance_variable_get("@#{field}") ||
+                instance_variable_set("@#{field}", extract(fragment, field.to_s.capitalize))
+            end
+          end
+        end
+
+        uses :date, :version
+
+        def initialize(fragment)
+          self.fragment = fragment
+        end
+
+        def extract(fragment, attr)
+          fragment.attr(attr)
+        end
+
+      end
+
+      class RowContainer < Container
+
+        attr_accessor :rows
+
+        def initialize(doc)
+          super
+          self.rows = Parser::Compact.parse_document(doc)
+        end
+
+      end
+
+      class ResourceContainer < RowContainer
+        alias resources rows
+      end
+
+      class ClassContainer < RowContainer
+        uses :resource
+
+        alias classes rows
+      end
+
+      class TableContainer < RowContainer
+        uses :resource, :class
+
+        alias tables rows
+      end
+
+      class LookupContainer < RowContainer
+        uses :resource
+
+        alias lookups rows
+      end
+
+      class LookupTypeContainer < RowContainer
+        uses :resource, :lookup
+
+        alias lookup_types rows
+      end
+
+      class ObjectContainer < RowContainer
+        uses :resource
+
+        alias objects rows
+      end
+
+      class SystemContainer < Container
+      end
+    end
+  end
+end

data/lib/rets/metadata/lookup_type.rb

@@ -0,0 +1,17 @@
+module Rets
+  module Metadata
+    class LookupType
+      attr_accessor :long_value, :short_value, :value
+
+      def initialize(lookup_type_fragment)
+        self.value       = lookup_type_fragment["Value"]
+        self.short_value = lookup_type_fragment["ShortValue"]
+        self.long_value  = lookup_type_fragment["LongValue"]
+      end
+
+      def print_tree
+        puts "      #{long_value} -> #{value}"
+      end
+    end
+  end
+end

data/lib/rets/metadata/resource.rb

@@ -0,0 +1,73 @@
+module Rets
+  module Metadata
+    class Resource
+      attr_accessor :rets_classes
+      attr_accessor :lookup_types
+
+      attr_accessor :id
+
+      def initialize(resource)
+        self.rets_classes = []
+        self.lookup_types = {}
+
+        self.id = resource["ResourceID"]
+      end
+
+      def self.find_lookup_containers(metadata, resource)
+        metadata[:lookup].select { |lc| lc.resource == resource.id }
+      end
+
+      def self.find_lookup_type_containers(metadata, resource, lookup_name)
+        metadata[:lookup_type].select { |ltc| ltc.resource == resource.id && ltc.lookup == lookup_name }
+      end
+
+      def self.find_rets_classes(metadata, resource)
+        metadata[:class].detect { |c| c.resource == resource.id }.classes
+      end
+
+      def self.build_lookup_tree(resource, metadata)
+        lookup_types = Hash.new {|h, k| h[k] = Array.new }
+
+        find_lookup_containers(metadata, resource).each do |lookup_container|
+          lookup_container.lookups.each do |lookup_fragment|
+            lookup_name = lookup_fragment["LookupName"]
+
+            find_lookup_type_containers(metadata, resource, lookup_name).each do |lookup_type_container|
+
+              lookup_type_container.lookup_types.each do |lookup_type_fragment|
+                lookup_types[lookup_name] << LookupType.new(lookup_type_fragment)
+              end
+            end
+          end
+        end
+
+        lookup_types
+      end
+
+      def self.build_classes(resource, metadata)
+        find_rets_classes(metadata, resource).map do |rets_class_fragment|
+          RetsClass.build(rets_class_fragment, resource, metadata)
+        end
+      end
+
+      def self.build(resource_fragment, metadata)
+        resource = new(resource_fragment)
+
+        resource.lookup_types = build_lookup_tree(resource, metadata)
+        resource.rets_classes = build_classes(resource, metadata)
+        resource
+      end
+
+      def print_tree
+        puts "Resource: #{id}"
+
+        rets_classes.each(&:print_tree)
+      end
+
+      def find_rets_class(rets_class_name)
+        rets_classes.detect {|rc| rc.name == rets_class_name }
+      end
+    end
+  end
+end
+

data/lib/rets/metadata/rets_class.rb

@@ -0,0 +1,42 @@
+module Rets
+  module Metadata
+    class RetsClass
+      attr_accessor :tables
+      attr_accessor :name
+      attr_accessor :resource
+
+      def initialize(rets_class_fragment, resource)
+        self.resource = resource
+        self.tables = []
+        self.name = rets_class_fragment["ClassName"]
+      end
+
+      def self.find_table_container(metadata, resource, rets_class)
+        metadata[:table].detect { |t| t.resource == resource.id && t.class == rets_class.name }
+      end
+
+      def self.build(rets_class_fragment, resource, metadata)
+        rets_class = new(rets_class_fragment, resource)
+
+        table_container = find_table_container(metadata, resource, rets_class)
+
+        if table_container
+          table_container.tables.each do |table_fragment|
+            rets_class.tables << TableFactory.build(table_fragment, resource)
+          end
+        end
+
+        rets_class
+      end
+
+      def print_tree
+        puts "  Class: #{name}"
+        tables.each(&:print_tree)
+      end
+
+      def find_table(name)
+        tables.detect { |value| value.name == name }
+      end
+    end
+  end
+end

data/lib/rets/metadata/root.rb

@@ -0,0 +1,155 @@
+module Rets
+  module Metadata
+    METADATA_TYPES = %w(SYSTEM RESOURCE CLASS TABLE LOOKUP LOOKUP_TYPE OBJECT)
+
+    # It's useful when dealing with the Rets standard to represent their
+    # relatively flat namespace of interweived components as a Tree. With
+    # a collection of resources at the top, and their various, classes,
+    # tables, lookups, and lookup types underneath.
+    #
+    # It looks something like ...
+    #
+    #    Resource
+    #     |
+    #    Class
+    #     |
+    #     `-- Table
+    #     |
+    #     `-- Lookups
+    #           |
+    #           `-- LookupType
+    #
+    # For our purposes it was helpful to denormalize some of the more deeply
+    # nested branches. In particular by relating Lookups to LookupTypes, and
+    # Tables to lookups with can simplify this diagram.
+    #
+    #
+    #    Resource
+    #     |
+    #    Class
+    #     |
+    #     `-- Table
+    #          |
+    #          `-- Lookups
+    #
+    # By associating Tables and lookups when we parse this structure. It allows
+    # us to seemlessly map Lookup values to their Long or Short value forms.
+    class Root
+      # Metadata_types is the low level parsed representation of the raw xml
+      # sources. Just one level up, they contain Containers, consisting of
+      # SystemContainers or RowContainers
+      attr_writer :metadata_types
+
+      # the tree is the high level represenation of the metadata heiarchy
+      # it begins with root. Stored as a list of Metadata::Resources
+      attr_writer :tree
+
+      # Sources are the raw xml documents fetched for each metadata type
+      # they are stored as a hash with the type names as their keys
+      # and the raw xml as the values
+      attr_accessor :sources
+
+      # fetcher is a proc that inverts control to the client to retrieve metadata
+      # types
+      def initialize(&fetcher)
+        @tree = nil
+        @metadata_types = nil # TODO think up a better name ... containers?
+        @sources = {}
+
+        # allow Root's to be built with no fetcher. Makes for easy testing
+        return unless block_given?
+
+        fetch_sources(&fetcher)
+      end
+
+      def fetch_sources(&fetcher)
+        self.sources = Hash[*METADATA_TYPES.map {|type| [type, fetcher.call(type)] }.flatten]
+      end
+
+      def marshal_dump
+        sources
+      end
+
+      def marshal_load(sources)
+        self.sources = sources
+      end
+
+      def version
+        metadata_types[:system].first.version
+      end
+
+      def date
+        metadata_types[:system].first.date
+      end
+
+      # Wether there exists a more up to date version of the metadata to fetch
+      # is dependant on either a timestamp indicating when the most recent
+      # version was published, or a version number. These values may or may
+      # not exist on any given rets server.
+      def current?(current_timestamp, current_version)
+	if !current_version.to_s.empty? && !version.to_s.empty?
+	  current_version == version 
+	else
+          current_timestamp ? current_timestamp == date : true
+	end
+      end
+
+      def build_tree
+        tree = Hash.new { |h, k| h.key?(k.downcase) ? h[k.downcase] : nil }
+
+        resource_containers = metadata_types[:resource]
+
+        resource_containers.each do |resource_container|
+          resource_container.rows.each do |resource_fragment|
+            resource = Resource.build(resource_fragment, metadata_types)
+            tree[resource.id.downcase] = resource
+          end
+        end
+
+        tree
+      end
+
+      def tree
+        @tree ||= build_tree
+      end
+
+      def print_tree
+        tree.each do |name, value|
+          value.print_tree
+        end
+      end
+
+      def metadata_types
+        return @metadata_types if @metadata_types
+
+        h = {}
+
+        sources.each do |name, source|
+          h[name.downcase.to_sym] = build_containers(Nokogiri.parse(source))
+        end
+
+        @metadata_types = h
+      end
+
+      # Returns an array of container classes that represents
+      # the metadata stored in the document provided.
+      def build_containers(doc)
+        # find all tags that match /RETS/METADATA-*
+        fragments = doc.xpath("/RETS/*[starts-with(name(), 'METADATA-')]")
+
+        fragments.map { |fragment| build_container(fragment) }
+      end
+
+      def build_container(fragment)
+        tag  = fragment.name             # METADATA-RESOURCE
+        type = tag.sub(/^METADATA-/, "") # RESOURCE
+
+        class_name = type.capitalize.gsub(/_(\w)/) { $1.upcase }
+        container_name = "#{class_name}Container"
+
+        container_class = Containers.constants.include?(container_name) ? Containers.const_get(container_name) : Containers::Container
+        container_class.new(fragment)
+      end
+    end
+  end
+end

data/lib/rets/metadata/table.rb

@@ -0,0 +1,98 @@
+module Rets
+  module Metadata
+    class TableFactory
+      def self.build(table_fragment, resource)
+        enum?(table_fragment) ? LookupTable.new(table_fragment, resource) : Table.new(table_fragment)
+      end
+
+      def self.enum?(table_fragment)
+        lookup_value   = table_fragment["LookupName"].strip
+        interpretation = table_fragment["Interpretation"].strip
+
+        interpretation =~ /Lookup/ && !lookup_value.empty?
+      end
+    end
+
+    class Table
+      attr_accessor :type
+      attr_accessor :name
+      attr_accessor :table_fragment
+
+      def initialize(table_fragment)
+        self.table_fragment = table_fragment
+        self.type = table_fragment["DataType"]
+        self.name = table_fragment["SystemName"]
+      end
+
+      def print_tree
+        puts "    Table: #{name}"
+        puts "      ShortName: #{ table_fragment["ShortName"] }"
+        puts "      LongName: #{ table_fragment["LongName"] }"
+        puts "      StandardName: #{ table_fragment["StandardName"] }"
+        puts "      Units: #{ table_fragment["Units"] }"
+        puts "      Searchable: #{ table_fragment["Searchable"] }"
+      end
+
+      def resolve(value)
+        value.to_s.strip
+      end
+    end
+
+    class LookupTable
+      attr_accessor :resource
+      attr_accessor :lookup_name
+      attr_accessor :name
+      attr_accessor :interpretation
+
+      def initialize(table_fragment, resource)
+        self.resource = resource
+        self.name = table_fragment["SystemName"]
+        self.interpretation = table_fragment["Interpretation"]
+        self.lookup_name = table_fragment["LookupName"]
+      end
+
+      def multi?
+        interpretation == "LookupMulti"
+      end
+
+      def lookup_types
+        resource.lookup_types[lookup_name]
+      end
+
+      def print_tree
+        puts "    LookupTable: #{name}"
+
+        lookup_types.each(&:print_tree)
+      end
+
+      def lookup_type(value)
+        lookup_types.detect {|lt| lt.value == value }
+      end
+
+      def resolve(value)
+        if value.empty?
+          return [] if multi?
+          return value.to_s.strip
+        end
+
+        values = multi? ? value.split(","): [value]
+
+        values = values.map do |value|
+
+          #Remove surrounding quotes
+          value  = value.scan(/^["']?(.*?)["']?$/).to_s
+
+          lookup_type = lookup_type(value)
+
+          resolved_value = lookup_type ? lookup_type.long_value : nil
+
+          warn("Discarding unmappable value of #{value.inspect}") if resolved_value.nil? && $VERBOSE
+
+          resolved_value
+        end
+
+        multi? ? values.map {|value| value.to_s.strip } : values.first.to_s.strip
+      end
+    end
+  end
+end