lardawge-rfm 1.3.1 → 1.4.0

data/lib/rfm/commands/server.rb

@@ -0,0 +1,388 @@
+require 'net/https'
+require 'cgi'
+module Rfm
+  # This class represents a single FileMaker server. It is initialized with basic
+  # connection information, including the hostname, port number, and default database
+  # account name and password.
+  #
+  # Note: The host and port number refer to the FileMaker Web Publishing Engine, which
+  # must be installed and configured in order to use RFM. It may not actually be running
+  # on the same server computer as FileMaker Server itself. See your FileMaker Server
+  # or FileMaker Server Advanced documentation for information about configuring a Web
+  # Publishing Engine.
+  #
+  # =Accessing Databases
+  #
+  # Typically, you access a Database object from the Server like this:
+  #
+  #   myDatabase = myServer["Customers"]
+  # 
+  # This code gets the Database object representing the Customers object.
+  # 
+  # Note: RFM does not talk to the server when you retrieve a database object in this way. Instead, it
+  # simply assumes you know what you're talking about. If the database you specify does not exist, you 
+  # will get no error at this point. Instead, you'll get an error when you use the Layout object you get
+  # from this database. This makes debugging a little less convenient, but it would introduce too much
+  # overhead to hit the server at this point.
+  #
+  # The Server object has a +db+ attribute that provides alternate access to Database objects. It acts
+  # like a hash of Database objects, one for each accessible database on the server. So, for example, you
+  # can do this if you want to print out a list of all databses on the server:
+  # 
+  #   myServer.db.each {|database|
+  #     puts database.name
+  #   }
+  # 
+  # The Server::db attribute is actually a DbFactory object, although it subclasses hash, so it should work
+  # in all the ways you expect. Note, though, that it is completely empty until the first time you attempt 
+  # to access its elements. At that (lazy) point, it hits FileMaker, loads in the list of databases, and
+  # constructs a Database object for each one. In other words, it incurrs no overhead until you use it.
+  #
+  # =Attributes
+  # 
+  # In addition to the +db+ attribute, Server has a few other useful attributes:
+  #
+  # * *host_name* is the host name this server points to
+  # * *port* is the port number this server communicates on
+  # * *state* is a hash of all server options used to initialize this server
+  
+  
+  
+  # The Database object represents a single FileMaker Pro database. When you retrieve a Database
+  # object from a server, its account name and password are set to the account name and password you 
+  # used when initializing the Server object. You can override this of course:
+  #
+  #   myDatabase = myServer["Customers"]
+  #   myDatabase.account_name = "foo"
+  #   myDatabase.password = "bar"
+  #
+  # =Accessing Layouts
+  #
+  # All interaction with FileMaker happens through a Layout object. You can get a Layout object
+  # from the Database object like this:
+  #
+  #   myLayout = myDatabase["Details"]
+  #
+  # This code gets the Layout object representing the layout called Details in the database.
+  #
+  # Note: RFM does not talk to the server when you retrieve a Layout object in this way. Instead, it
+  # simply assumes you know what you're talking about. If the layout you specify does not exist, you 
+  # will get no error at this point. Instead, you'll get an error when you use the Layout object methods
+  # to talk to FileMaker. This makes debugging a little less convenient, but it would introduce too much
+  # overhead to hit the server at this point.
+  #
+  # The Database object has a +layout+ attribute that provides alternate access to Layout objects. It acts
+  # like a hash of Layout objects, one for each accessible layout in the database. So, for example, you
+  # can do this if you want to print out a list of all layouts:
+  # 
+  #   myDatabase.layout.each {|layout|
+  #     puts layout.name
+  #   }
+  # 
+  # The Database::layout attribute is actually a LayoutFactory object, although it subclasses hash, so it
+  # should work in all the ways you expect. Note, though, that it is completely empty until the first time
+  # you attempt to access its elements. At that (lazy) point, it hits FileMaker, loads in the list of layouts,
+  # and constructs a Layout object for each one. In other words, it incurrs no overhead until you use it.
+  #
+  # =Accessing Scripts
+  #
+  # If for some reason you need to enumerate the scripts in a database, you can do so:
+  #  
+  #   myDatabase.script.each {|script|
+  #     puts script.name
+  #   }
+  # 
+  # The Database::script attribute is actually a ScriptFactory object, although it subclasses hash, so it
+  # should work in all the ways you expect. Note, though, that it is completely empty until the first time
+  # you attempt to access its elements. At that (lazy) point, it hits FileMaker, loads in the list of scripts,
+  # and constructs a Script object for each one. In other words, it incurrs no overhead until you use it. 
+  #
+  # Note: You don't need a Script object to _run_ a script (see the Layout object instead).
+  #
+  # =Attributes
+  # 
+  # In addition to the +layout+ attribute, Server has a few other useful attributes:
+  #
+  # * *server* is the Server object this database comes from
+  # * *name* is the name of this database
+  # * *state* is a hash of all server options used to initialize this server
+  class Server
+    #
+    # To create a Server object, you typically need at least a host name:
+    # 
+    #   myServer = Rfm::Server.new({:host => 'my.host.com'})
+    #
+    # Several other options are supported:
+    #
+    # * *host* the hostname of the Web Publishing Engine (WPE) server (defaults to 'localhost')
+    #
+    # * *port* the port number the WPE is listening no (defaults to 80 unless *ssl* +true+ which sets it to 443)
+    #
+    # * *account_name* the default account name to log in to databases with (you can also supply a
+    #   account name on a per-database basis if necessary)
+    #
+    # * *password* the default password to log in to databases with (you can also supplly a password
+    #   on a per-databases basis if necessary)
+    #
+    # * *log_actions* when +true+, RFM logs all action URLs that are sent to FileMaker server to stderr
+    #   (defaults to +false+)
+    #
+    # * *log_responses* when +true+, RFM logs all raw XML responses (including headers) from FileMaker to
+    #   stderr (defaults to +false+)
+    #
+    # * *warn_on_redirect* normally, RFM prints a warning to stderr if the Web Publishing Engine redirects
+    #   (this can usually be fixed by using a different host name, which speeds things up); if you *don't*
+    #   want this warning printed, set +warn_on_redirect+ to +true+
+    #
+    # * *raise_on_401* although RFM raises error when FileMaker returns error responses, it typically
+    #   ignores FileMaker's 401 error (no records found) and returns an empty record set instead; if you
+    #   prefer a raised error when a find produces no errors, set this option to +true+
+    #
+    #SSL Options (SSL AND CERTIFICATE VERIFICATION ARE ON BY DEFAULT):
+    #
+    # * *ssl* +false+ if you want to turn SSL (HTTPS) off when connecting to connect to FileMaker (default is +true+)
+    #
+    # If you are using SSL and want to verify the certificate use the following options:
+    #
+    # * *root_cert* +false+ if you do not want to verify your SSL session (default is +true+). 
+    #   You will want to turn this off if you are using a self signed certificate and do not have a certificate authority cert file.
+    #   If you choose this option you will need to provide a cert *root_cert_name* and *root_cert_path* (if not in root directory).
+    #
+    # * *root_cert_name* name of pem file for certificate verification (Root cert from certificate authority who issued certificate.
+    #   If self signed certificate do not use this option!!). You can download the entire bundle of CA Root Certificates
+    #   from http://curl.haxx.se/ca/cacert.pem. Place the pem file in config directory.
+    #
+    # * *root_cert_path* path to cert file. (defaults to '/' if no path given)
+    #
+    #Configuration Examples:    
+    #
+    # Example to turn off SSL:
+    # 
+    #   myServer = Rfm::Server.new({
+    #           :host => 'localhost',
+    #           :account_name => 'sample',
+    #           :password => '12345',
+    #           :ssl => false 
+    #           })
+    #           
+    # Example using SSL without *root_cert*:
+    #           
+    #   myServer = Rfm::Server.new({
+    #           :host => 'localhost',
+    #           :account_name => 'sample',
+    #           :password => '12345',
+    #           :root_cert => false 
+    #           })
+    #           
+    # Example using SSL with *root_cert* at file root:
+    # 
+    #   myServer = Rfm::Server.new({
+    #            :host => 'localhost',
+    #            :account_name => 'sample',
+    #            :password => '12345',
+    #            :root_cert_name => 'example.pem' 
+    #            })
+    #            
+    # Example using SSL with *root_cert* specifying *root_cert_path*:
+    # 
+    #   myServer = Rfm::Server.new({
+    #            :host => 'localhost',
+    #            :account_name => 'sample',
+    #            :password => '12345',
+    #            :root_cert_name => 'example.pem'
+    #            :root_cert_path => '/usr/cert_file/'
+    #            })
+    
+    def initialize(options)
+      @state = {
+        :host => 'localhost',
+        :port => 80,
+        :ssl => true,
+        :root_cert => true,
+        :root_cert_name => '',
+        :root_cert_path => '/',
+        :account_name => '',
+        :password => '',
+        :log_actions => false,
+        :log_responses => false,
+        :warn_on_redirect => true,
+        :raise_on_401 => false
+      }.merge(options)
+    
+      @state.freeze
+    
+      @host_name = @state[:host]
+      @scheme = @state[:ssl] ? "https" : "http"
+      @port = @state[:ssl] && options[:port].nil? ? 443 : @state[:port]
+    
+      @db = Rfm::Factory::DbFactory.new(self)
+    end
+    
+    # Access the database object representing a database on the server. For example:
+    #
+    #   myServer['Customers']
+    #
+    # would return a Database object representing the _Customers_
+    # database on the server.
+    #
+    # Note: RFM never talks to the server until you perform an action. The database object
+    # returned is created on the fly and assumed to refer to a valid database, but you will
+    # get no error at this point if the database you access doesn't exist. Instead, you'll
+    # receive an error when you actually try to perform some action on a layout from this
+    # database.
+    def [](dbname)
+      self.db[dbname]
+    end
+    
+    attr_reader :db, :host_name, :port, :scheme, :state
+    
+    # Performs a raw FileMaker action. You will generally not call this method directly, but it
+    # is exposed in case you need to do something "under the hood."
+    # 
+    # The +action+ parameter is any valid FileMaker web url action. For example, +-find+, +-finadny+ etc.
+    #
+    # The +args+ parameter is a hash of arguments to be included in the action url. It will be serialized
+    # and url-encoded appropriately.
+    #
+    # The +options+ parameter is a hash of RFM-specific options, which correspond to the more esoteric
+    # FileMaker URL parameters. They are exposed separately because they can also be passed into
+    # various methods on the Layout object, which is a much more typical way of sending an action to
+    # FileMaker.
+    #
+    # This method returns the Net::HTTP response object representing the response from FileMaker.
+    #
+    # 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(
+    #     '-find',
+    #     {
+    #       "-db" => "Customers",
+    #       "-lay" => "Details",
+    #       "First Name" => "Bill"
+    #     },
+    #     { :max_records => 20 }
+    #   )
+    def do_action(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
+    
+    def load_layout(layout)
+      post = {'-db' => layout.db.name, '-lay' => layout.name, '-view' => ''}
+      http_fetch(@host_name, @port, "/fmi/xml/FMPXMLLAYOUT.xml", layout.db.account_name, layout.db.password, post)
+    end
+    
+    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
+    
+        if @state[:log_actions] == true
+          qs = post_data.collect{|key,val| "#{CGI::escape(key.to_s)}=#{CGI::escape(val.to_s)}"}.join("&")
+          warn "#{@scheme}://#{@host_name}:#{@port}#{path}?#{qs}"
+        end
+    
+        request = Net::HTTP::Post.new(path)
+        request.basic_auth(account_name, password)
+        request.set_form_data(post_data)
+    
+        response = Net::HTTP.new(host_name, port)
+    
+        if @state[:ssl]
+          response.use_ssl = true
+          if @state[:root_cert]
+            response.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            response.ca_file = File.join(@state[:root_cert_path], @state[:root_cert_name])
+          else
+            response.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          end
+        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
+        end
+    
+        case response
+        when Net::HTTPSuccess
+          response
+        when Net::HTTPRedirection
+          if @state[:warn_on_redirect]
+            warn "The web server redirected to " + response['location'] + 
+            ". You should revise your connection hostname or fix your server configuration if possible to improve performance."
+          end
+          newloc = URI.parse(response['location'])
+          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)
+        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)
+        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)
+        end
+      end
+    
+      def expand_options(options)
+        result = {}
+        options.each do |key,value|
+          case key
+          when :max_records
+            result['-max'] = value
+          when :skip_records
+            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
+              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
+              value.each_index { |i| result["-sortorder.#{i+1}"] = value[i] }
+            else
+              result["-sortorder.1"] = value
+            end
+          when :post_script
+            if value.class == Array
+              result['-script'] = value[0]
+              result['-script.param'] = value[1]
+            else
+              result['-script'] = value
+            end
+          when :pre_find_script
+            if value.class == Array
+              result['-script.prefind'] = value[0]
+              result['-script.prefind.param'] = value[1]
+            else
+              result['-script.presort'] = value
+            end
+          when :pre_sort_script
+            if value.class == Array
+              result['-script.presort'] = value[0]
+              result['-script.presort.param'] = value[1]
+            else
+              result['-script.presort'] = value
+            end
+          when :response_layout
+            result['-lay.response'] = value
+          when :logical_operator
+            result['-lop'] = value
+          when :modification_id
+            result['-modid'] = value
+          else
+            raise Rfm::Error::ParameterError.new("Invalid option: #{key} (are you using a string instead of a symbol?)")
+          end
+        end
+        return result
+      end
+    
+  end
+end

data/lib/rfm/error.rb

@@ -0,0 +1,256 @@
+require "set"
+
+# These classes wrap the filemaker error codes. FileMakerError is the base class of this hierarchy.
+# 
+# One could get a FileMakerError by doing:
+#   err = Rfm::Error::FileMakerError.getError(102)
+# 
+# The above code would return a FieldMissingError instance. Your could use this instance to raise that appropriate
+# exception:
+# 
+#   raise err 
+# 
+# You could access the specific error code by accessing:
+#   
+#   err.code
+#   
+# Author::    Mufaddal Khumri
+# Copyright:: Copyright (c) 2007 Six Fried Rice, LLC and Mufaddal Khumri
+# License::   See MIT-LICENSE for details
+module Rfm
+  module Error
+    
+    class RfmError < StandardError
+    end
+    
+    class CommunicationError < RfmError
+    end
+    
+    class ParameterError < RfmError
+    end
+    
+    class AuthenticationError < RfmError
+    end
+    
+    # Base class for all FileMaker errors
+    class FileMakerError < RfmError
+      attr_accessor :code
+      
+      # Default filemaker error message map
+      @default_messages = {}
+      class << self; attr_reader :default_messages; end
+      
+      
+      # This method instantiates and returns the appropriate FileMakerError object depending on the error code passed to it. It
+      # also accepts an optional message.
+      def self.getError(code, message = nil)
+        if @default_messages == nil or @default_messages.size == 0
+          (0..99).each{|i| @default_messages[i] = 'SystemError occurred.'}
+          (100..199).each{|i| @default_messages[i] = 'MissingError occurred.'}
+          @default_messages[102] = 'FieldMissingError occurred.'
+          @default_messages[104] = 'ScriptMissingError occurred.'
+          @default_messages[105] = 'LayoutMissingError occurred.'
+          @default_messages[106] = 'TableMissingError occurred.'
+          (200..299).each{|i| @default_messages[i] = 'SecurityError occurred.'}
+          @default_messages[200] = 'RecordAccessDeniedError occurred.'
+          @default_messages[201] = 'FieldCannotBeModifiedError occurred.'
+          @default_messages[202] = 'FieldAccessIsDeniedError occurred.'
+          (300..399).each{|i| @default_messages[i] = 'ConcurrencyError occurred.'}
+          @default_messages[301] = 'RecordInUseError occurred.'
+          @default_messages[302] = 'TableInUseError occurred.'
+          @default_messages[306] = 'RecordModIdDoesNotMatchError occurred.'
+          (400..499).each{|i| @default_messages[i] = 'GeneralError occurred.'}
+          @default_messages[401] = 'NoRecordsFoundError occurred.'
+          (500..599).each{|i| @default_messages[i] = 'ValidationError occurred.'}
+          @default_messages[500] = 'DateValidationError occurred.'
+          @default_messages[501] = 'TimeValidationError occurred.'
+          @default_messages[502] = 'NumberValidationError occurred.'
+          @default_messages[503] = 'RangeValidationError occurred.'
+          @default_messages[504] = 'UniqueValidationError occurred.'
+          @default_messages[505] = 'ExistingValidationError occurred.'
+          @default_messages[506] = 'ValueListValidationError occurred.'
+          @default_messages[507] = 'ValidationCalculationError occurred.'
+          @default_messages[508] = 'InvalidFindModeValueError occurred.'
+          @default_messages[511] = 'MaximumCharactersValidationError occurred.'
+          (800..899).each{|i| @default_messages[i] = 'FileError occurred.'}
+          @default_messages[802] = 'UnableToOpenFileError occurred.'
+        end 
+        
+        message = @default_messages[code] if message == nil || message.strip == ''
+        message += " (FileMaker Error ##{code})"
+        
+        if 0 <= code and code <= 99
+          err = SystemError.new(message)
+        elsif 100 <= code and code <= 199
+          if code == 101
+            err = RecordMissingError.new(message)
+          elsif code == 102
+            err = FieldMissingError.new(message)
+          elsif code == 104
+            err = ScriptMissingError.new(message)
+          elsif code == 105
+            err = LayoutMissingError.new(message)
+          elsif code == 106
+            err = TableMissingError.new(message)
+          else
+            err = MissingError.new(message)
+          end
+        elsif 200 <= code and code <= 299
+          if code == 200
+            err = RecordAccessDeniedError.new(message)
+          elsif code == 201
+            err = FieldCannotBeModifiedError.new(message)
+          elsif code == 202
+            err = FieldAccessIsDeniedError.new(message)
+          else
+            err = SecurityError.new(message)
+          end
+        elsif 300 <= code and code <= 399
+          if code == 301
+            err = RecordInUseError.new(message)
+          elsif code == 302
+            err = TableInUseError.new(message)
+          elsif code == 306
+            err = RecordModIdDoesNotMatchError.new(message)
+          else
+            err = ConcurrencyError.new(message)
+          end
+        elsif 400 <= code and code <= 499
+          if code == 401
+            err = NoRecordsFoundError.new(message)
+          else
+            err = GeneralError.new(message)
+          end
+        elsif 500 <= code and code <= 599
+          if code == 500
+            err = DateValidationError.new(message)
+          elsif code == 501
+            err = TimeValidationError.new(message)
+          elsif code == 502
+            err = NumberValidationError.new(message)
+          elsif code == 503
+            err = RangeValidationError.new(message)
+          elsif code == 504
+            err = UniqueValidationError.new(message)
+          elsif code == 505
+            err = ExistingValidationError.new(message)
+          elsif code == 506
+            err = ValueListValidationError.new(message)
+          elsif code == 507
+            err = ValidationCalculationError.new(message)
+          elsif code == 508
+            err = InvalidFindModeValueError.new(message)
+          elsif code == 511
+            err = MaximumCharactersValidationError.new(message)
+          else
+            err = ValidationError.new(message)
+          end
+        elsif 800 <= code and code <= 899
+          if code == 802
+            err = UnableToOpenFileError.new(message)
+          else
+            err = FileError.new(message)
+          end
+        else 
+          # called for code == -1 or any other code not handled above.
+          err = UnknownError.new(message)
+        end
+        err.code = code
+        return err
+      end    
+    end
+    
+    class UnknownError < FileMakerError  
+    end
+    
+    class SystemError < FileMakerError  
+    end
+    
+    class MissingError < FileMakerError  
+    end
+    
+    class RecordMissingError < MissingError  
+    end
+  
+    class FieldMissingError < MissingError  
+    end
+  
+    class ScriptMissingError < MissingError  
+    end
+  
+    class LayoutMissingError < MissingError  
+    end
+  
+    class TableMissingError < MissingError  
+    end
+  
+    class SecurityError < FileMakerError  
+    end
+    
+    class RecordAccessDeniedError < SecurityError  
+    end
+  
+    class FieldCannotBeModifiedError < SecurityError  
+    end
+  
+    class FieldAccessIsDeniedError < SecurityError  
+    end
+    
+    class ConcurrencyError < FileMakerError  
+    end
+    
+    class RecordInUseError < ConcurrencyError  
+    end
+  
+    class TableInUseError < ConcurrencyError  
+    end
+  
+    class RecordModIdDoesNotMatchError < ConcurrencyError  
+    end
+  
+    class GeneralError < FileMakerError  
+    end
+  
+    class NoRecordsFoundError < GeneralError  
+    end
+     
+    class ValidationError < FileMakerError  
+    end 
+  
+    class DateValidationError < ValidationError  
+    end
+  
+    class TimeValidationError < ValidationError  
+    end
+    
+    class NumberValidationError < ValidationError  
+    end
+    
+    class RangeValidationError < ValidationError  
+    end
+  
+    class UniqueValidationError < ValidationError  
+    end
+    
+    class ExistingValidationError < ValidationError  
+    end
+  
+    class ValueListValidationError < ValidationError  
+    end
+  
+    class ValidationCalculationError < ValidationError  
+    end
+  
+    class InvalidFindModeValueError < ValidationError  
+    end
+  
+    class MaximumCharactersValidationError < ValidationError  
+    end
+  
+    class FileError < FileMakerError  
+    end 
+  
+    class UnableToOpenFileError < FileError  
+    end
+  end
+end