sugarcrm_emp 0.10.0

data/lib/sugarcrm/connection_pool.rb

@@ -0,0 +1,163 @@
+require 'monitor'
+
+module SugarCRM; class ConnectionPool
+  attr_accessor :timeout
+  attr_reader :size
+  def initialize(session)
+    @session = session
+    
+    # The cache of reserved connections mapped to threads
+    @reserved_connections = {}
+    
+    # The mutex used to synchronize pool access
+    @connection_mutex = Monitor.new
+    @queue = @connection_mutex.new_cond
+    @timeout = config_timeout || 10
+    
+    # default max pool size to 5
+    @size = config_pool_size || default_pool_size
+    
+    @connections = []
+    @checked_out = []
+  end
+  
+  # If a connection already exists yield it to the block. If no connection
+  # exists checkout a connection, yield it to the block, and checkin the
+  # connection when finished.
+  def with_connection
+    connection_id = current_connection_id
+    fresh_connection = true unless @reserved_connections[connection_id]
+    yield connection
+  ensure
+    release_connection(connection_id) if fresh_connection
+  end
+  
+  # Retrieve the connection associated with the current thread, or call
+  # #checkout to obtain one if necessary.
+  #
+  # #connection can be called any number of times; the connection is
+  # held in a hash keyed by the thread id.
+  def connection
+    @reserved_connections[current_connection_id] ||= checkout
+  end
+  
+  # Check-out a sugarcrm connection from the pool, indicating that you want
+  # to use it. You should call #checkin when you no longer need this.
+  #
+  # This is done by either returning an existing connection, or by creating
+  # a new connection. If the maximum number of connections for this pool has
+  # already been reached, but the pool is empty (i.e. they're all being used),
+  # then this method will wait until a thread has checked in a connection.
+  # The wait time is bounded however: if no connection can be checked out
+  # within the timeout specified for this pool, then a ConnectionTimeoutError
+  # exception will be raised.
+  def checkout
+    # Checkout an available connection
+    @connection_mutex.synchronize do
+      loop do
+        conn = if @checked_out.size < @connections.size
+                  checkout_existing_connection
+                elsif @connections.size < @size
+                  checkout_new_connection
+                end
+        return conn if conn
+
+        @queue.wait(@timeout)
+
+        if(@checked_out.size < @connections.size)
+          next
+        else
+          clear_stale_cached_connections!
+          if @size == @checked_out.size
+            raise SugarCRM::ConnectionTimeoutError, "could not obtain a sugarcrm connection#{" within #{@timeout} seconds" if @timeout}. The max pool size is currently #{@size}; consider increasing it."
+          end
+        end
+
+      end
+    end
+  end
+  
+  # Check-in a sugarcrm connection back into the pool, indicating that you
+  # no longer need this connection.
+  def checkin(conn)
+    @connection_mutex.synchronize do
+      @checked_out.delete conn
+      @queue.signal
+    end
+  end
+  
+  # Disconnects all connections in the pool, and clears the pool.
+  def disconnect!
+    @reserved_connections.each_value do |conn|
+      checkin conn
+    end
+    @reserved_connections = {}
+    @connections.each do |conn|
+      conn.logout
+    end
+    @connections = []
+  end
+  
+  # Return any checked-out connections back to the pool by threads that
+  # are no longer alive.
+  def clear_stale_cached_connections!
+    keys = @reserved_connections.keys - Thread.list.find_all { |t|
+      t.alive?
+    }.map { |thread| thread.object_id }
+    keys.each do |key|
+      checkin @reserved_connections[key]
+      @reserved_connections.delete(key)
+    end
+  end
+  
+  private
+  def new_connection
+    c = Connection.new(@session.config[:base_url], @session.config[:username], @session.config[:password], @session.config[:options])
+    c.session = @session
+    c
+  end
+  
+  def checkout_new_connection
+    c = new_connection
+    @connections << c
+    checkout_connection(c)
+  end
+
+  def checkout_existing_connection
+    c = (@connections - @checked_out).first
+    checkout_connection(c)
+  end
+  
+  def checkout_connection(c)
+    @checked_out << c
+    c
+  end
+  
+  def current_connection_id #:nodoc:
+    Thread.current.object_id
+  end
+  
+  # Returns the connection pool timeout, if present
+  def config_timeout
+    begin
+      @session.config[:options][:connection_pool][:wait_timeout] && @session.config[:options][:connection_pool][:wait_timeout].to_i
+    rescue
+      false
+    end
+  end
+  
+  # Returns the connection pool size, if present
+  def config_pool_size
+    begin
+      @session.config[:options][:connection_pool][:size] && @session.config[:options][:connection_pool][:size].to_i
+    rescue
+      false
+    end
+  end
+  
+  # The default for the connection pool's maximum size depends on environment:
+  # default pool size will be 1 unless used within Rails
+  def default_pool_size
+    defined?(Rails) ? 5 : 1
+  end
+end; end

data/lib/sugarcrm/exceptions.rb

@@ -0,0 +1,23 @@
+module SugarCRM
+  class NoActiveSession < RuntimeError; end
+  class MultipleSessions < RuntimeError; end
+  class InvalidSession < RuntimeError; end
+  class RetryLimitExceeded < RuntimeError; end
+  class LoginError < RuntimeError; end
+  class MissingCredentials < RuntimeError; end
+  class ConnectionTimeoutError < RuntimeError; end
+  class EmptyResponse < RuntimeError; end
+  class UnhandledResponse < RuntimeError; end
+  class InvalidSugarCRMUrl < RuntimeError; end
+  class InvalidRequest < RuntimeError; end
+  class InvalidModule <RuntimeError; end
+  class AttributeParsingError < RuntimeError; end
+  class RecordNotFound < RuntimeError; end
+  class InvalidRecord < RuntimeError; end
+  class RecordSaveFailed < RuntimeError; end
+  class AssociationFailed < RuntimeError; end
+  class UninitializedModule < RuntimeError; end
+  class InvalidAttribute < RuntimeError; end
+  class InvalidAttributeType < RuntimeError; end
+  class InvalidAssociation < RuntimeError; end
+end

data/lib/sugarcrm/extensions/README.txt

@@ -0,0 +1,23 @@
+# Include your extension files here, as simple *.rb files. Here is an example of an extension:
+
+SugarCRM::Contact.class_eval do
+  def self.ten_oldest
+    self.all(:order_by => 'date_entered', :limit => 10)
+  end
+  
+  def vip?
+    self.opportunities.size > 100
+  end
+end
+
+# This will enable you to call
+
+SugarCRM::Contact.ten_oldest
+
+# to get the 10 oldest contacts entered in CRM .
+# 
+# You will also be able to call
+
+SugarCRM::Contact.first.vip?
+
+# to see whether a contact is VIP or not.

data/lib/sugarcrm/finders/dynamic_finder_match.rb

@@ -0,0 +1,41 @@
+module SugarCRM
+  class DynamicFinderMatch
+    def self.match(method)
+      df_match = self.new(method)
+      df_match.finder ? df_match : nil
+    end
+
+    def initialize(method)
+      @finder = :first
+      case method.to_s
+      when /^find_(all_by|last_by|by)_([_a-zA-Z]\w*)$/
+        @finder = :last if $1 == 'last_by'
+        @finder = :all if $1 == 'all_by'
+        names = $2
+      when /^find_by_([_a-zA-Z]\w*)\!$/
+        @bang = true
+        names = $1
+      when /^find_or_(initialize|create)_by_([_a-zA-Z]\w*)$/
+        @instantiator = $1 == 'initialize' ? :new : :create
+        names = $2
+      else
+        @finder = nil
+      end
+      @attribute_names = names && names.split('_and_')
+    end
+
+    attr_reader :finder, :attribute_names, :instantiator
+
+    def finder?
+      !@finder.nil? && @instantiator.nil?
+    end
+
+    def instantiator?
+      @finder == :first && !@instantiator.nil?
+    end
+
+    def bang?
+      @bang
+    end
+  end
+end

data/lib/sugarcrm/finders/finder_methods.rb

@@ -0,0 +1,243 @@
+module SugarCRM; module FinderMethods
+  module ClassMethods
+    private 
+      def find_initial(options)
+        options.update(:limit => 1)
+        result = find_by_sql(options)
+        return result.first if result.instance_of? Array # find_by_sql will return an Array if result are found
+        result
+      end
+  
+      def find_from_ids(ids, options, &block)
+        expects_array = ids.first.kind_of?(Array)
+        return ids.first if expects_array && ids.first.empty?
+
+        ids = ids.flatten.compact.uniq
+
+        case ids.size
+          when 0
+            raise RecordNotFound, "Couldn't find #{self._module.name} without an ID"
+          when 1
+            result = find_one(ids.first, options)
+            expects_array ? [ result ] : result
+          else
+            find_some(ids, options, &block)
+        end
+      end
+  
+      def find_one(id, options)
+      
+        if result = connection.get_entry(self._module.name, id, {:fields => self._module.fields.keys})
+          result
+        else
+          raise RecordNotFound, "Couldn't find #{name} with ID=#{id}#{conditions}"
+        end
+      end
+    
+      def find_some(ids, options, &block)
+        result = connection.get_entries(self._module.name, ids, {:fields => self._module.fields.keys})
+
+        # Determine expected size from limit and offset, not just ids.size.
+        expected_size =
+          if options[:limit] && ids.size > options[:limit]
+            options[:limit]
+          else
+            ids.size
+          end
+
+        # 11 ids with limit 3, offset 9 should give 2 results.
+        if options[:offset] && (ids.size - options[:offset] < expected_size)
+          expected_size = ids.size - options[:offset]
+        end
+
+        if result.size == expected_size
+          if block_given?
+            result.each{|r|
+              yield r
+            }
+          end
+          result
+        else
+          raise RecordNotFound, "Couldn't find all #{name.pluralize} with IDs (#{ids_list})#{conditions} (found #{result.size} results, but was looking for #{expected_size})"
+        end
+      end
+    
+      def find_every(options, &block)
+        find_by_sql(options, &block)
+      end
+      
+      # the number of records we retrieve with each query
+      # it is kept small to avoid timeout issues
+      SLICE_SIZE = 5
+      SLICE_SIZE.freeze
+      # results accumulator stores the results we have fetched so far, recursively
+      def find_by_sql(options, results_accumulator=nil, &block)
+        # SugarCRM REST API has a bug (fixed in release _6.4.0.patch as indicated in SugarCRM bug number 43338)
+        # where, when :limit and :offset options are passed simultaneously,
+        # :limit is considered to be the smallest of the two, and :offset is the larger
+        # In addition to allowing querying of large datasets while avoiding timeouts (by fetching results in small slices),
+        # this implementation fixes the :limit - :offset bug so that it behaves correctly
+        
+        offset = options[:offset].to_i >= 1 ? options[:offset].to_i : nil
+        
+        # if many results are requested (i.e. multiple result slices), we call this function recursively
+        # this array keeps track of which slice we are retrieving (by updating the :offset and :limit options)
+        local_options = {}
+        # ensure results are ordered so :limit and :offset option behave in a deterministic fashion
+        local_options[:order_by] = :id unless options[:order_by]
+        
+        # we must ensure limit <= offset (due to bug mentioned above)
+        if offset
+          local_options[:limit] = [offset.to_i, SLICE_SIZE].min
+          local_options[:offset] = offset if offset
+        else
+          local_options[:limit] = options[:limit] ? [options[:limit].to_i, SLICE_SIZE].min : SLICE_SIZE
+        end
+        local_options[:limit] = [local_options[:limit], options[:limit]].min if options[:limit] # don't retrieve more records than required
+        local_options = options.merge(local_options)
+        
+        query = query_from_options(local_options)
+        result_slice = connection.get_entry_list(self._module.name, query, local_options)
+        return results_accumulator unless result_slice
+        
+        result_slice_array = Array.wrap(result_slice)
+        if block_given?
+          result_slice_array.each{|r| yield r }
+        else
+          results_accumulator = [] unless results_accumulator
+          results_accumulator = results_accumulator.concat(result_slice_array)
+        end
+        
+        # adjust options to take into account records that were already retrieved
+        updated_options = {:offset => options[:offset].to_i + result_slice_array.size}
+        updated_options[:limit] = (options[:limit] ? options[:limit] - result_slice_array.size : nil)
+        updated_options = options.merge(updated_options)
+        
+        # have we retrieved all the records?
+        if (updated_options[:limit] && updated_options[:limit] < 1) || local_options[:limit] > result_slice_array.size
+          return results_accumulator
+        else
+          find_by_sql(updated_options, results_accumulator, &block)
+        end
+      end
+
+      def query_from_options(options)
+        # If we dont have conditions, just return an empty query
+        return "" unless options[:conditions]
+        conditions = []
+        options[:conditions].each do |condition|
+          # Merge the result into the conditions array
+          conditions |= flatten_conditions_for(condition)
+        end
+        conditions.join(" AND ")
+      end
+    
+      # return the opposite of the provided order clause
+      # this is used for the :last find option
+      # in other words SugarCRM::Account.last(:order_by => "name")
+      # is equivalent to SugarCRM::Account.first(:order_by => "name DESC")
+      def reverse_order_clause(order)
+        raise "reversing multiple order clauses not supported" if order.split(',').size > 1
+        raise "order clause format not understood; expected 'column_name (ASC|DESC)?'" unless order =~ /^\s*(\S+)\s*(ASC|DESC)?\s*$/
+        column_name = $1
+        reversed_order = {'ASC' => 'DESC', 'DESC' => 'ASC'}[$2 || 'ASC']
+        return "#{column_name} #{reversed_order}"
+      end
+    
+      # Enables dynamic finders like <tt>find_by_user_name(user_name)</tt> and <tt>find_by_user_name_and_password(user_name, password)</tt>
+      # that are turned into <tt>find(:first, :conditions => ["user_name = ?", user_name])</tt> and
+      # <tt>find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])</tt> respectively. Also works for
+      # <tt>find(:all)</tt> by using <tt>find_all_by_amount(50)</tt> that is turned into <tt>find(:all, :conditions => ["amount = ?", 50])</tt>.
+      #
+      # It's even possible to use all the additional parameters to +find+. For example, the full interface for +find_all_by_amount+
+      # is actually <tt>find_all_by_amount(amount, options)</tt>.
+      #
+      # Also enables dynamic scopes like scoped_by_user_name(user_name) and scoped_by_user_name_and_password(user_name, password) that
+      # are turned into scoped(:conditions => ["user_name = ?", user_name]) and scoped(:conditions => ["user_name = ? AND password = ?", user_name, password])
+      # respectively.
+      #
+      # Each dynamic finder, scope or initializer/creator is also defined in the class after it is first invoked, so that future
+      # attempts to use it do not run through method_missing.
+      def method_missing(method_id, *arguments, &block)
+        if match = DynamicFinderMatch.match(method_id)
+          attribute_names = match.attribute_names
+          super unless all_attributes_exists?(attribute_names)
+          if match.finder?
+            finder = match.finder
+            bang = match.bang?
+            self.class_eval <<-EOS, __FILE__, __LINE__ + 1
+              def self.#{method_id}(*args)
+                options = args.extract_options!
+                attributes = construct_attributes_from_arguments(
+                  [:#{attribute_names.join(',:')}],
+                  args
+                )
+                finder_options = { :conditions => attributes }
+                validate_find_options(options)
+
+                #{'result = ' if bang}if options[:conditions]
+                  with_scope(:find => finder_options) do
+                    find(:#{finder}, options)
+                  end
+                else
+                  find(:#{finder}, options.merge(finder_options))
+                end
+                #{'result || raise(RecordNotFound, "Couldn\'t find #{name} with #{attributes.to_a.collect {|pair| "#{pair.first} = #{pair.second}"}.join(\', \')}")' if bang}
+              end
+            EOS
+            send(method_id, *arguments)
+          elsif match.instantiator?
+            instantiator = match.instantiator
+            self.class_eval <<-EOS, __FILE__, __LINE__ + 1
+              def self.#{method_id}(*args)
+                attributes = [:#{attribute_names.join(',:')}]
+                protected_attributes_for_create, unprotected_attributes_for_create = {}, {}
+                args.each_with_index do |arg, i|
+                  if arg.is_a?(Hash)
+                    protected_attributes_for_create = args[i].with_indifferent_access
+                  else
+                    unprotected_attributes_for_create[attributes[i]] = args[i]
+                  end
+                end
+
+                find_attributes = (protected_attributes_for_create.merge(unprotected_attributes_for_create)).slice(*attributes)
+
+                options = { :conditions => find_attributes }
+
+                record = find(:first, options)
+
+                if record.nil?
+                  record = self.new(unprotected_attributes_for_create)
+                  #{'record.save' if instantiator == :create}
+                  record
+                else
+                  record
+                end
+              end
+            EOS
+            send(method_id, *arguments, &block)
+          end
+        else
+          super
+        end
+      end
+    
+      def all_attributes_exists?(attribute_names)
+        attribute_names.all? { |name| attributes_from_module.include?(name) }
+      end
+    
+      def construct_attributes_from_arguments(attribute_names, arguments)
+        attributes = {}
+        attribute_names.each_with_index { |name, idx| attributes[name] = arguments[idx] }
+        attributes
+      end
+    
+      VALID_FIND_OPTIONS = [ :conditions, :deleted, :fields, :include, :joins, :limit, :link_fields, :offset,
+                             :order_by, :select, :readonly, :group, :having, :from, :lock ]
+
+      def validate_find_options(options) #:nodoc:
+        options.assert_valid_keys(VALID_FIND_OPTIONS)
+      end
+    end
+  end
+end

data/lib/sugarcrm/finders.rb

@@ -0,0 +1,2 @@
+require 'sugarcrm/finders/finder_methods'
+require 'sugarcrm/finders/dynamic_finder_match'

data/lib/sugarcrm/module.rb

@@ -0,0 +1,174 @@
+module SugarCRM
+  # A class for handling SugarCRM Modules
+  class Module
+    attr :name, true
+    attr :table_name, true
+    attr :custom_table_name, true
+    attr :klass, true
+    attr :fields, true
+    attr :link_fields, true
+    alias :bean :klass
+
+    # Dynamically register objects based on Module name
+    # I.e. a SugarCRM Module named Users will generate
+    # a SugarCRM::User class.
+    def initialize(session, name)
+      @session = session # the session from which this module was retrieved
+      @name   = name
+      @klass  = name.classify
+      unless custom_module?
+        @table_name = name.tableize
+      else
+        @table_name = @name
+      end
+      @custom_table_name = resolve_custom_table_name      
+      @fields = {}
+      @link_fields = {}
+      @fields_registered = false
+      self
+    end
+    
+    # Return true if this module was created in the SugarCRM Studio (i.e. it is not part of the modules that
+    # ship in the default SugarCRM configuration)
+    def custom_module?
+      # custom module names are all lower_case, whereas SugarCRM modules are CamelCase
+      @name.downcase == @name 
+    end
+
+    # Set table name for custom attibutes
+    # Custom attributes are contained in a table named after the module, with a '_cstm' suffix.
+    # The module's table name must be tableized for the modules that ship with SugarCRM.
+    # For custom modules (created in the Studio), table name don't need to be tableized since
+    # the name passed to the constructor is already tableized    
+    def resolve_custom_table_name
+      if custom_module?
+        @custom_table_name = @name + "_cstm"
+      else
+        @custom_table_name = @table_name + "_cstm"
+      end
+    end
+    
+    # Returns the fields associated with the module
+    def fields
+      return @fields if fields_registered?
+      all_fields  = @session.connection.get_fields(@name)
+      @fields     = all_fields["module_fields"].with_indifferent_access
+      @link_fields= all_fields["link_fields"]
+      handle_empty_arrays
+      @fields_registered = true
+      @fields
+    end
+    
+    def fields_registered?
+      @fields_registered
+    end
+    
+    alias :link_fields_registered? :fields_registered?
+    
+    # Returns the required fields
+    def required_fields
+      required_fields = []
+      ignore_fields = [:id, :date_entered, :date_modified]
+      self.fields.each_value do |field|
+        next if ignore_fields.include? field["name"].to_sym
+        required_fields << field["name"].to_sym if field["required"] == 1
+      end 
+      required_fields
+    end
+    
+    def link_fields
+      self.fields unless link_fields_registered?
+      handle_empty_arrays
+      @link_fields
+    end
+    
+    # TODO: Refactor this to be less repetitive
+    def handle_empty_arrays
+      @fields = {}.with_indifferent_access if @fields.length == 0
+      @link_fields = {}.with_indifferent_access if @link_fields.length == 0
+    end
+    
+    # Registers a single module by name
+    # Adds module to SugarCRM.modules (SugarCRM.modules << Module.new("Users"))
+    # Adds module class to SugarCRM parent module (SugarCRM.constants << User)
+    # Note, SugarCRM::User.module == Module.find("Users")
+    def register
+      return self if registered?
+      mod_instance = self
+      sess = @session
+      # class Class < SugarCRM::Base
+      #   module_name = "Accounts"
+      # end
+      klass = Class.new(SugarCRM::Base) do
+        self._module = mod_instance
+        self.session = sess
+      end
+      
+      # class Account < SugarCRM::Base
+      @session.namespace_const.const_set self.klass, klass
+      self
+    end
+    
+    # Deregisters the module
+    def deregister
+      return true unless registered?
+      klass = self.klass
+      @session.namespace_const.instance_eval{ remove_const klass }
+      true
+    end
+
+    def registered?
+      @session.namespace_const.const_defined? @klass
+    end  
+      
+    def to_s
+      @klass
+    end
+    
+    def to_class
+      SugarCRM.const_get(@klass).new
+    end
+      
+    class << self
+      @initialized = false
+      
+      # Registers all of the SugarCRM Modules
+      def register_all(session)
+        namespace = session.namespace_const
+        session.connection.get_modules.each do |m|
+          session.modules << m.register
+        end
+        @initialized = true
+        true
+      end
+      
+      # Deregisters all of the SugarCRM Modules
+      def deregister_all(session)
+        namespace = session.namespace_const
+        session.modules.each do |m|
+          m.deregister
+        end
+        session.modules = []
+        @initialized = false
+        true
+      end
+
+      # Finds a module by name, or klass name
+      def find(name, session=nil)
+        session ||= SugarCRM.session
+        register_all(session) unless initialized?
+        session.modules.each do |m|
+          return m if m.name  == name
+          return m if m.klass == name
+        end
+        false
+      end
+      
+      # Class variable to track if we've initialized or not
+      def initialized?
+        @initialized ||= false
+      end
+      
+    end
+  end
+end