lardawge-rfm 1.4.0 → 1.4.1

data/lib/rfm/record.rb

@@ -0,0 +1,219 @@
+module Rfm
+  
+  # The Record object represents a single FileMaker record. You typically get them from ResultSet objects.
+  # For example, you might use a Layout object to find some records:
+  #
+  #   results = myLayout.find({"First Name" => "Bill"})
+  #
+  # The +results+ variable in this example now contains a ResultSet object. ResultSets are really just arrays of
+  # Record objects (with a little extra added in). So you can get a record object just like you would access any 
+  # typical array element:
+  #
+  #   first_record = results[0]
+  #
+  # You can find out how many record were returned:
+  #
+  #   record_count = results.size
+  #
+  # And you can of course iterate:
+  # 
+  #   results.each (|record|
+  #     // you can work with the record here
+  #   )
+  #
+  # =Accessing Field Data
+  #
+  # You can access field data in the Record object in two ways. Typically, you simply treat Record like a hash
+  # (because it _is_ a hash...I love OOP). Keys are field names:
+  # 
+  #   first = myRecord["First Name"]
+  #   last = myRecord["Last Name"]
+  #
+  # If your field naming conventions mean that your field names are also valid Ruby symbol named (ie: they contain only
+  # letters, numbers, and underscores) then you can treat them like attributes of the record. For example, if your fields
+  # are called "first_name" and "last_name" you can do this:
+  #
+  #   first = myRecord.first_name
+  #   last = myRecord.last_name
+  #
+  # Note: This shortcut will fail (in a rather mysterious way) if your field name happens to match any real attribute
+  # name of a Record object. For instance, you may have a field called "server". If you try this:
+  # 
+  #   server_name = myRecord.server
+  # 
+  # you'll actually set +server_name+ to the Rfm::Server object this Record came from. This won't fail until you try
+  # to treat it as a String somewhere else in your code. It is also possible a future version of Rfm will include
+  # new attributes on the Record class which may clash with your field names. This will cause perfectly valid code
+  # today to fail later when you upgrade. If you can't stomach this kind of insanity, stick with the hash-like
+  # method of field access, which has none of these limitations. Also note that the +myRecord[]+ method is probably
+  # somewhat faster since it doesn't go through +method_missing+.
+  #
+  # =Accessing Repeating Fields
+  #
+  # If you have a repeating field, RFM simply returns an array:
+  #
+  #   val1 = myRecord["Price"][0]
+  #   val2 = myRecord["Price"][1]
+  #
+  # In the above example, the Price field is a repeating field. The code puts the first repetition in a variable called 
+  # +val1+ and the second in a variable called +val2+.
+  #
+  # =Accessing Portals
+  #
+  # If the ResultSet includes portals (because the layout it comes from has portals on it) you can access them
+  # using the Record::portals attribute. It is a hash with table occurrence names for keys, and arrays of Record
+  # objects for values. In other words, you can do this:
+  #
+  #   myRecord.portals["Orders"].each {|record|
+  #     puts record["Order Number"]
+  #   }
+  #
+  # This code iterates through the rows of the _Orders_ portal.
+  # 
+  # =Field Types and Ruby Types
+  #
+  # RFM automatically converts data from FileMaker into a Ruby object with the most reasonable type possible. The 
+  # type are mapped thusly:
+  #
+  # * *Text* fields are converted to Ruby String objects
+  # 
+  # * *Number* fields are converted to Ruby BigDecimal objects (the basic Ruby numeric types have
+  #   much less precision and range than FileMaker number fields)
+  #
+  # * *Date* fields are converted to Ruby Date objects
+  #
+  # * *Time* fields are converted to Ruby DateTime objects (you can ignore the date component)
+  #
+  # * *Timestamp* fields are converted to Ruby DateTime objects
+  #
+  # * *Container* fields are converted to Ruby URI objects
+  #
+  # =Attributes
+  #
+  # In addition to +portals+, the Record object has these useful attributes:
+  #
+  # * *record_id* is FileMaker's internal identifier for this record (_not_ any ID field you might have
+  #   in your table); you need a +record_id+ to edit or delete a record
+  #
+  # * *mod_id* is the modification identifier for the record; whenever a record is modified, its +mod_id+
+  #   changes so you can tell if the Record object you're looking at is up-to-date as compared to another
+  #   copy of the same record
+  class Record < Rfm::CaseInsensitiveHash
+    
+    attr_reader :record_id, :mod_id, :portals
+
+    def initialize(record, result, field_meta, layout, portal=nil)
+      @record_id = record['record-id']
+      @mod_id    = record['mod-id']
+      @mods      = {}
+      @layout    = layout
+      @portals ||= Rfm::CaseInsensitiveHash.new
+
+      relatedsets = !portal && result.instance_variable_get(:@include_portals) ? record.xpath('relatedset') : []
+      
+      record.xpath('field').each do |field|
+        field_name = field['name']
+        field_name.gsub!(Regexp.new(portal + '::'), '') if portal
+        datum = []
+        
+        field.xpath('data').each do |x| 
+          datum.push(field_meta[field_name].coerce(x.inner_text, result))
+        end
+      
+        if datum.length == 1
+          self[field_name] = datum[0]
+        elsif datum.length == 0
+          self[field_name] = nil
+        else
+          self[field_name] = datum
+        end
+      end
+      
+      unless relatedsets.empty?
+        relatedsets.each do |relatedset|
+          tablename, records = relatedset['table'], []
+      
+          relatedset.xpath('record').each do |record|
+            records << self.class.new(record, result, result.portal_meta[tablename], layout, tablename)
+          end
+      
+          @portals[tablename] = records
+        end
+      end
+      
+      @loaded = true
+    end
+
+    def self.build_records(records, result, field_meta, layout, portal=nil)
+      records.each do |record|
+        result << self.new(record, result, field_meta, layout, portal)
+      end
+    end
+
+    # Saves local changes to the Record object back to Filemaker. For example:
+    #
+    #   myLayout.find({"First Name" => "Bill"}).each(|record|
+    #     record["First Name"] = "Steve"
+    #     record.save
+    #   )
+    #
+    # This code finds every record with _Bill_ in the First Name field, then changes the first name to 
+    # Steve.
+    #
+    # Note: This method is smart enough to not bother saving if nothing has changed. So there's no need
+    # to optimize on your end. Just save, and if you've changed the record it will be saved. If not, no
+    # server hit is incurred.
+    def save
+      self.merge(@layout.edit(self.record_id, @mods)[0]) if @mods.size > 0
+      @mods.clear
+    end
+
+    # Like Record::save, except it fails (and raises an error) if the underlying record in FileMaker was
+    # modified after the record was fetched but before it was saved. In other words, prevents you from
+    # accidentally overwriting changes someone else made to the record.
+    def save_if_not_modified
+      self.merge(@layout.edit(@record_id, @mods, {:modification_id => @mod_id})[0]) if @mods.size > 0
+      @mods.clear
+    end
+    
+    # Gets the value of a field from the record. For example:
+    #
+    #   first = myRecord["First Name"]
+    #   last = myRecord["Last Name"]
+    #
+    # This sample puts the first and last name from the record into Ruby variables.
+    #
+    # You can also update a field:
+    #
+    #   myRecord["First Name"] = "Sophia"
+    #
+    # When you do, the change is noted, but *the data is not updated in FileMaker*. You must call
+    # Record::save or Record::save_if_not_modified to actually save the data.
+    def []=(pname, value)
+      return super unless @loaded # keeps us from getting mods during initialization
+      name = pname
+      if self[name] != nil
+        @mods[name] = val
+      else
+        raise Rfm::Error::ParameterError.new("You attempted to modify a field called '#{name}' on the Rfm::Record object, but that field does not exist.")
+      end
+    end
+    
+    def method_missing (symbol, *attrs)
+      # check for simple getter
+      return self[symbol.to_s] if self.include?(symbol.to_s) 
+
+      # check for setter
+      symbol_name = symbol.to_s
+      if symbol_name[-1..-1] == '=' && self.has_key?(symbol_name[0..-2])
+        return @mods[symbol_name[0..-2]] = attrs[0]
+      end
+      super
+    end
+    
+    def respond_to?(symbol, include_private = false)
+      return true if self[symbol.to_s] != nil
+      super
+    end
+  end
+end

data/lib/rfm/resultset.rb

@@ -0,0 +1,136 @@
+# This module includes classes that represent FileMaker data. When you communicate with FileMaker
+# using, ie, the Layout object, you typically get back ResultSet objects. These contain Records,
+# which in turn contain Fields, Portals, and arrays of data.
+#
+# Author::    Geoff Coffey  (mailto:gwcoffey@gmail.com)
+# Copyright:: Copyright (c) 2007 Six Fried Rice, LLC and Mufaddal Khumri
+# License::   See MIT-LICENSE for details
+require 'nokogiri'
+require 'bigdecimal'
+require 'rfm/record'
+require 'rfm/metadata/field'
+
+module Rfm
+
+  # The ResultSet object represents a set of records in FileMaker. It is, in every way, a real Ruby
+  # Array, so everything you expect to be able to do with an Array can be done with a ResultSet as well.
+  # In this case, the elements in the array are Record objects.
+  #
+  # Here's a typical example, displaying the results of a Find:
+  #
+  #   myServer = Rfm::Server.new(...)
+  #   results = myServer["Customers"]["Details"].find("First Name" => "Bill")
+  #   results.each {|record|
+  #     puts record["First Name"]
+  #     puts record["Last Name"]
+  #     puts record["Email Address"]
+  #   }
+  #
+  # =Attributes
+  #
+  # The ResultSet object has these attributes:
+  #
+  # * *field_meta* is a hash with field names for keys and Field objects for values; it provides 
+  #   info about the fields in the ResultSet
+  #
+  # * *portal_meta* is a hash with table occurrence names for keys and arrays of Field objects for values;
+  #   it provides metadata about the portals in the ResultSet and the Fields on those portals
+
+  class Resultset < Array
+    
+    attr_reader :layout
+    attr_reader :field_meta, :portal_meta
+    attr_reader :date_format, :time_format, :timestamp_format
+    attr_reader :total_count, :foundset_count
+    
+    # Initializes a new ResultSet object. You will probably never do this your self (instead, use the Layout
+    # object to get various ResultSet obejects).
+    #
+    # If you feel so inclined, though, pass a Server object, and some +fmpxmlresult+ compliant XML in a String.
+    #
+    # =Attributes
+    #
+    # The ResultSet object includes several useful attributes:
+    #
+    # * *fields* is a hash (with field names for keys and Field objects for values). It includes an entry for
+    #   every field in the ResultSet. Note: You don't use Field objects to access _data_. If you're after 
+    #   data, get a Record object (ResultSet is an array of records). Field objects tell you about the fields
+    #   (their type, repetitions, and so forth) in case you find that information useful programmatically.
+    #
+    #   Note: keys in the +fields+ hash are downcased for convenience (and [] automatically downcases on 
+    #   lookup, so it should be seamless). But if you +each+ a field hash and need to know a field's real
+    #   name, with correct case, do +myField.name+ instead of relying on the key in the hash.
+    #
+    # * *portals* is a hash (with table occurrence names for keys and Field objects for values). If your
+    #   layout contains portals, you can find out what fields they contain here. Again, if it's the data you're
+    #   after, you want to look at the Record object.
+    
+    def initialize(server, xml_response, layout, portals=nil)
+      @layout           = layout
+      @field_meta     ||= Rfm::CaseInsensitiveHash.new
+      @portal_meta    ||= Rfm::CaseInsensitiveHash.new
+      @include_portals  = portals 
+      
+      doc = Nokogiri.XML(remove_namespace(xml_response))
+      
+      error = doc.xpath('/fmresultset/error').attribute('code').value.to_i
+      check_for_errors(error, server.state[:raise_on_401])
+
+      datasource        = doc.xpath('/fmresultset/datasource')
+      meta              = doc.xpath('/fmresultset/metadata')
+      resultset         = doc.xpath('/fmresultset/resultset')
+
+      @date_format      = convert_date_time_format(datasource.attribute('date-format').value)
+      @time_format      = convert_date_time_format(datasource.attribute('time-format').value)
+      @timestamp_format = convert_date_time_format(datasource.attribute('timestamp-format').value)
+
+      @foundset_count   = resultset.attribute('count').value.to_i
+      @total_count      = datasource.attribute('total-count').value.to_i
+
+      parse_fields(meta)
+      parse_portals(meta) if @include_portals
+      
+      Rfm::Record.build_records(resultset.xpath('record'), self, @field_meta, @layout)
+      
+    end
+    
+    private
+      def remove_namespace(xml)
+        xml.gsub('xmlns="http://www.filemaker.com/xml/fmresultset" version="1.0"', '')
+      end
+    
+      def check_for_errors(code, raise_401)
+        raise Rfm::Error.getError(code) if code != 0 && (code != 401 || raise_401)
+      end
+    
+      def parse_fields(meta)
+        meta.xpath('field-definition').each do |field|
+          @field_meta[field['name']] = Rfm::Metadata::Field.new(field)
+        end
+      end
+
+      def parse_portals(meta)
+        meta.xpath('relatedset-definition').each do |relatedset|
+          table, fields = relatedset.attribute('table').value, {}
+
+          relatedset.xpath('field-definition').each do |field|
+            name = field.attribute('name').value.gsub(Regexp.new(table + '::'), '')
+            fields[name] = Rfm::Metadata::Field.new(field)
+          end
+
+          @portal_meta[table] = fields
+        end
+      end
+    
+      def convert_date_time_format(fm_format)
+        fm_format.gsub!('MM', '%m')
+        fm_format.gsub!('dd', '%d')
+        fm_format.gsub!('yyyy', '%Y')
+        fm_format.gsub!('HH', '%H')
+        fm_format.gsub!('mm', '%M')
+        fm_format.gsub!('ss', '%S')
+        fm_format
+      end
+    
+  end
+end

data/lib/rfm/{commands/server.rb → server.rb}

@@ -254,7 +254,7 @@ module Rfm
     # For example, if you wanted to send a raw command to FileMaker to find the first 20 people in the
     # "Customers" database whose first name is "Bill" you might do this:
     #
-    #   response = myServer.do_action(
+    #   response = myServer.connect(
     #     '-find',
     #     {
     #       "-db" => "Customers",
@@ -263,7 +263,7 @@ module Rfm
     #     },
     #     { :max_records => 20 }
     #   )
-    def do_action(account_name, password, action, args, options = {})
+    def connect(account_name, password, action, args, options = {})
       post = args.merge(expand_options(options)).merge({action => ''})
       http_fetch(@host_name, @port, "/fmi/xml/fmresultset.xml", account_name, password, post)
     end
@@ -276,7 +276,7 @@ module Rfm
     private
     
       def http_fetch(host_name, port, path, account_name, password, post_data, limit=10)
-        raise Rfm::Error::CommunicationError.new("While trying to reach the Web Publishing Engine, RFM was redirected too many times.") if limit == 0
+        raise Rfm::CommunicationError.new("While trying to reach the Web Publishing Engine, RFM was redirected too many times.") if limit == 0
     
         if @state[:log_actions] == true
           qs = post_data.collect{|key,val| "#{CGI::escape(key.to_s)}=#{CGI::escape(val.to_s)}"}.join("&")
@@ -300,7 +300,6 @@ module Rfm
         end
     
         response = response.start { |http| http.request(request) }
-    
         if @state[:log_responses] == true
           response.to_hash.each { |key, value| warn "#{key}: #{value}" }
           warn response.body
@@ -318,13 +317,13 @@ module Rfm
           http_fetch(newloc.host, newloc.port, newloc.request_uri, account_name, password, post_data, limit - 1)
         when Net::HTTPUnauthorized
           msg = "The account name (#{account_name}) or password provided is not correct (or the account doesn't have the fmxml extended privilege)."
-          raise Rfm::Error::AuthenticationError.new(msg)
+          raise Rfm::AuthenticationError.new(msg)
         when Net::HTTPNotFound
           msg = "Could not talk to FileMaker because the Web Publishing Engine is not responding (server returned 404)."
-          raise Rfm::Error::CommunicationError.new(msg)
+          raise Rfm::CommunicationError.new(msg)
         else
-          msg = "Unexpected response from server: #{result.code} (#{result.class.to_s}). Unable to communicate with the Web Publishing Engine."
-          raise Rfm::Error::CommunicationError.new(msg)
+          msg = "Unexpected response from server: #{response.code} (#{response.class.to_s}). Unable to communicate with the Web Publishing Engine."
+          raise Rfm::CommunicationError.new(msg)
         end
       end
     
@@ -338,14 +337,14 @@ module Rfm
             result['-skip'] = value
           when :sort_field
             if value.kind_of? Array
-              raise Rfm::Error::ParameterError.new(":sort_field can have at most 9 fields, but you passed an array with #{value.size} elements.") if value.size > 9
+              raise Rfm::ParameterError.new(":sort_field can have at most 9 fields, but you passed an array with #{value.size} elements.") if value.size > 9
               value.each_index { |i| result["-sortfield.#{i+1}"] = value[i] }
             else
               result["-sortfield.1"] = value
             end
           when :sort_order
             if value.kind_of? Array
-              raise Rfm::Error::ParameterError.new(":sort_order can have at most 9 fields, but you passed an array with #{value.size} elements.") if value.size > 9
+              raise Rfm::ParameterError.new(":sort_order can have at most 9 fields, but you passed an array with #{value.size} elements.") if value.size > 9
               value.each_index { |i| result["-sortorder.#{i+1}"] = value[i] }
             else
               result["-sortorder.1"] = value
@@ -378,7 +377,7 @@ module Rfm
           when :modification_id
             result['-modid'] = value
           else
-            raise Rfm::Error::ParameterError.new("Invalid option: #{key} (are you using a string instead of a symbol?)")
+            raise Rfm::ParameterError.new("Invalid option: #{key} (are you using a string instead of a symbol?)")
           end
         end
         return result

data/lib/rfm/utilities/case_insensitive_hash.rb

@@ -0,0 +1,10 @@
+module Rfm
+  class CaseInsensitiveHash < Hash
+    def []=(key, value)
+      super(key.downcase, value)
+    end
+    def [](key)
+      super(key.downcase)
+    end
+  end
+end

data/lib/rfm/{factory.rb → utilities/factory.rb}

@@ -7,7 +7,7 @@
 
 module Rfm
   module Factory # :nodoc: all
-    class DbFactory < Rfm::Utility::CaseInsensitiveHash
+    class DbFactory < Rfm::CaseInsensitiveHash
     
       def initialize(server)
         @server = server
@@ -20,7 +20,7 @@ module Rfm
       
       def all
         if !@loaded
-          Rfm::Result::ResultSet.new(@server, @server.do_action(@server.state[:account_name], @server.state[:password], '-dbnames', {}).body).each {|record|
+          Rfm::Result::ResultSet.new(@server, @server.connect(@server.state[:account_name], @server.state[:password], '-dbnames', {}).body).each {|record|
             name = record['DATABASE_NAME']
             self[name] = Rfm::Database.new(name, @server) if self[name] == nil
           }
@@ -31,7 +31,7 @@ module Rfm
     
     end
     
-    class LayoutFactory < Rfm::Utility::CaseInsensitiveHash
+    class LayoutFactory < Rfm::CaseInsensitiveHash
     
       def initialize(server, database)
         @server = server
@@ -45,7 +45,7 @@ module Rfm
       
       def all
         if !@loaded
-          Rfm::Result::ResultSet.new(@server, @server.do_action(@server.state[:account_name], @server.state[:password], '-layoutnames', {"-db" => @database.name}).body).each {|record|
+          Rfm::Result::ResultSet.new(@server, @server.connect(@server.state[:account_name], @server.state[:password], '-layoutnames', {"-db" => @database.name}).body).each {|record|
             name = record['LAYOUT_NAME']
             self[name] = Rfm::Layout.new(name, @database) if self[name] == nil
           }
@@ -56,7 +56,7 @@ module Rfm
     
     end
     
-    class ScriptFactory < Rfm::Utility::CaseInsensitiveHash
+    class ScriptFactory < Rfm::CaseInsensitiveHash
     
       def initialize(server, database)
         @server = server
@@ -70,7 +70,7 @@ module Rfm
       
       def all
         if !@loaded
-          Rfm::Result::ResultSet.new(@server, @server.do_action(@server.state[:account_name], @server.state[:password], '-scriptnames', {"-db" => @database.name}).body).each {|record|
+          Rfm::Result::ResultSet.new(@server, @server.connect(@server.state[:account_name], @server.state[:password], '-scriptnames', {"-db" => @database.name}).body).each {|record|
             name = record['SCRIPT_NAME']
             self[name] = Rfm::Script.new(name, @database) if self[name] == nil
           }