uses-store-procedures 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Leopold O'Donnell
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+[![Build Status](https://travis-ci.org/leopoldodonnell/uses-stored-procedures.png?branch=master)](https://travis-ci.org/leopoldodonnell/uses-stored-procedures)
+[![Dependency Status](https://gemnasium.com/leopoldodonnell/uses-stored-procedures.png)](https://gemnasium.com/leopoldodonnell/uses-stored-procedures)
+[![Code Climate](https://codeclimate.com/github/leopoldodonnell/uses-stored-procedures.png)](https://codeclimate.com/github/leopoldodonnell/uses-stored-procedures)
+
+# UsesStoredProcedures
+
+Extends ActiveRecord with the ability to use SQL Stored Procedures in Rails.
+
+So, you really need to use stored procedures in your Rails application. This gem extends ActiveRecord with a class method to add to your models or services. Sure stored procedures are *not the Rails way* they are an occasional project necessity. Your reasons may stem from a need to integrate with a legacy database with built-in business rules, or a need to improve performance where other avenues have been exhausted (given available project time). If you need this, *you know who you are*, I don't need to tell you why.
+
+## Version
+
+0.1.0
+
+## Requirements
+
+### Ruby
+
+- 1.8.7, 1.9
+
+### Rails
+
+- 3.1.x or 3.2.x
+
+### ORM
+
+- ActiveRecord
+- Mysql2, MySQL (Tested/Passing)
+- SQLServer     (Untested, but should work)
+- PostgreSQL    (Untested, unsure - please try it and notify the author)
+
+## Installation
+
+The current state of this gem is tested with MySQL, but it also does detection of SQLServer and PostgreSQL which will
+be tested when time permits. Please contact the author if you've gotten it to work before this happens.
+
+In your Gemfile
+
+    gem 'uses-stored-procedures', git => "git://github.com/leopoldodonnell/uses-stored-procedures"
+
+Then from your project root:
+
+    > bundle
+
+
+## Using uses_stored_procedures to call stored procedures from Rails
+
+**UsesStoredProcedues** extends ActiveRecord::Base with the single class method that takes the name of the procedure as a symbol, and optional parameters to generate a class and instance method that can be called to run the stored procedure.
+
+Here's a simple example:
+
+```ruby
+class MyClass < ActiveRecord::Base
+  use_stored_proc :get_office_by_country {|row| "#{row.country} #{row.city}, phone: #{row.phone}"}
+end
+```
+
+Which generates:
+
+```ruby
+def self.get_office_by_country(*args, &block)
+  # code
+end
+
+def get_office_by_country(*args, &block)
+  self.class.get_offic_by_country(args, block)
+end
+```   
+
+So later you can do the following:
+  
+```ruby
+result = MyClass.get_office_by_country 'Canada'
+result.each {|item| puts item}
+```
+
+Note that the object passed to the block is a *UsesStoredProcedures#HashWithAttributes* instance that provides accessors for all of its keys.
+
+### Syntax
+
+The method signature for *use_stored_proc* is:
+
+```ruby
+def self.use_stored_proc(method_name, *options, &block)
+```
+
+That then generates a class and instance method named *method_name*.
+
+* method_name - is the symbolic name of the stored procedure and is the name given to the generated class and instance methods. By default, the stored procedure that is called will be a stringified version of this method_name. Use the :proc_name option if the method_name won't be matching actual stored procedure name.
+
+* options - is an array of arguments that are provided as *:arg_name => value* and where the last argument may be a block, or method name.
+
+####Options
+
+* proc_name - if the stored procedure name is different than method_name parameter, provide a string that matches the actual stored procedure name.
+
+* filter - the name of a class method that receives an instance of *UsesStoredProcedures#HashWithAttributes* to map returned rows.
+
+* block - make the last parameter a block that receive an instance of *UsesStoredProcedures#HashWithAttributes* to map returned rows.
+
+#### Generated Methods
+
+The generated methods all take a variable number of parameters that are mapped to the stored procedure call and can also take a block that can be used to map the returned rows. By default the returned value will be an array of values that are either instances of *UsesStoredProcedures#HashWithAttributes*, or mapped by the block. Note that passing a block overrides the block or method provided when calling *#use_stored_proc*
+
+### Another Example
+
+```ruby
+require 'uses_stored_procedures'
+
+class ClientServices
+  include UsesStoredProcedures
+  
+  use_stored_proc :list_inactive_clients, :proc_name => 'GET_CLIENTS_INACTIVE_STATUS', :filter => :make_clients
+  
+  def self.make_clients(item)
+    Client.new item
+  end
+end
+
+client_services = ClientServices.new
+
+# ...
+
+client_list = client_services.list_inactive_clients(first_of_year)
+
+# and so on ...
+```
+
+### License
+
+MIT License. Copyright 2013 Leopold O'Donnell
+
+

data/Rakefile

@@ -0,0 +1,29 @@
+#!/usr/bin/env rake
+require 'rspec/core/rake_task'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'UsesStoredProcedures'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/tasks/uses-stored-procedures_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :uses-store-procedures do
+#   # Task goes here
+# end

data/lib/uses_stored_procedures.rb

@@ -0,0 +1,107 @@
+require 'uses_stored_procedures/hash_with_attributes'
+
+##
+# UsesStoredProcedures provides that ability to extend a class with
+# the ability to call stored_procedures providing an array of hash
+# entries that can be mapped to an array of other objects.
+#
+module UsesStoredProcedures
+  extend ActiveSupport::Concern
+  
+  module ClassMethods
+    ##
+    # Add a stored procedure that can ba called on a class or a
+    # class instance.
+    #
+    # @param [Symbol] name is the symbolic name of the method to be created.
+    # By default, it is assumed that the stored procedure has the same
+    # name as a string.
+    #
+    # @param args is a variable list of optional arguments. Available Options
+    # include:
+    #
+    #   * :proc_name - is the name of the stored procedure. Use this if the
+    #   name doesn't match the name paramter
+    #   * :filter - is a class method used to filter the return results. The
+    #   method should take a HashWithAttributes instance and return an object
+    #   for the array entry
+    #
+    # @param [Proc] block - is a block that takes a HashWithAttributes instance 
+    # and returns an object for the array entry.
+    #
+    # @raises if the current SQL adapter isn't supported.
+    #   
+    def uses_stored_proc(name, *args, &block)
+      options   = args.extract_options!
+      proc_name = options[:proc_name] || name.to_s
+      
+      # Install the row mapper block or method
+      self.install_stored_proc_methods(name, proc_name, call_stored_proc_verb, options[:filter] || block)
+    end    
+
+
+    # Return the SQL verb for calling a stored procedure.
+    def call_stored_proc_verb()
+      case ActiveRecord::Base.connection.adapter_name.to_sym
+      when :Mysql2, :MySQL
+        'call'
+      when :PostgreSQL
+        'select'
+      when :SQLServer
+        'exec'
+      else
+        raise "uses_stored_procedurs does not support your connection adapter"
+      end        
+    end
+    
+    # Define the class and instance methods. Note the need to
+    # create a singleton class instance to create the stored
+    # procedure class method.
+    def install_stored_proc_methods(name, proc_name, call_stored_proc_verb, filter) #:nodoc:
+      define_method name do |*args| 
+        self.class.exec_stored_proc(proc_name, call_stored_proc_verb, filter, args) 
+      end
+
+      singleton_class = class << self; self; end
+      singleton_class.send(:define_method, name) do |*args| 
+        exec_stored_proc(proc_name, call_stored_proc_verb, filter, args) 
+      end
+
+    end
+    
+    # Run the stored procedure with the arguments provided and send
+    # them through a filter method or block if specified.
+    def exec_stored_proc(name, call_stored_proc_verb, filter, args) #:nodoc:
+      sql = "#{call_stored_proc_verb} #{name} (" + args.map {|a| "'#{a}'"}.join(',') + ")"
+
+      # Call the stored procedure. Note the need to reset the connection
+      # because the mysql connection tends to hangup when stored procedures
+      # are called. Note that testing for ::connected? doesn't work.
+      #
+      # TODO: investigate why stored procedures cause connection hangups.
+      records = ActiveRecord::Base.connection.select_all(sql)
+      ActiveRecord::Base.connection.reconnect!
+
+      filter_stored_proc_results(records, filter)
+    end
+
+    private
+      def filter_stored_proc_results(results, filter)
+        case filter
+          when Symbol
+            # Map with a member function
+            results.map do |r| self.send(filter.to_s, HashWithAttributes.new(r)) end
+          when Proc
+            # Map with a block
+            results.map do |r| filter.call(HashWithAttributes.new(r)) end
+          else
+            # Just map it 
+            results.map do |r| HashWithAttributes.new r end
+        end
+      end
+    
+  end
+end
+
+require 'uses_stored_procedures/railtie'
+

data/lib/uses_stored_procedures/hash_with_attributes.rb

@@ -0,0 +1,68 @@
+module UsesStoredProcedures
+  ##
+  # HashWithAttributes augments Hash with getters and setters on
+  # an as needed basis.
+  #
+  # When ever an instance of HashWithAttributes is sent an accessor
+  # message, or a respond_to? message that matches a hash key for
+  # the first time, a setter and getter is created for that key which
+  # may be either a symbol or a string.
+  #
+  # @example
+  #
+  #    h = HashWithAttributes.new
+  #    h[:one] = 1
+  #    h['two'] = 2
+  #    h.one = 3
+  #    h.two = 4
+  #    puts "One is #{h.one} and Two is #{h.two}"
+  #    # > One is 3 and Two is 4
+  # 
+  class HashWithAttributes < Hash
+    
+    ##
+    # Create a new HashWithAttributes.
+    #
+    # @param [Object] hash_or_obj will initialize the hash
+    # from another hash, or work like Hash where the object
+    # is the default for empty entries.
+    # 
+    def initialize(hash_or_obj = nil)
+      if hash_or_obj && hash_or_obj.kind_of?(Hash)
+        super()
+        self.merge! hash_or_obj
+      else
+        super
+      end
+    end
+         
+    def method_missing(name, *args, &block)
+      if check_and_create_accessors(name)
+        args.length > 0 ? send(name.to_s, args.first) : send(name.to_s)
+      else
+        super
+      end
+    end
+    
+    def respond_to?(symbol, include_private = false)
+      super || check_and_create_accessors(symbol)
+    end
+
+    private
+      def check_and_create_accessors(name)
+        item_name = name.to_s.chomp '='
+        if has_key?(item_name) || has_key?(item_name.to_sym)
+          self.class.create_accessors(item_name)
+          return true
+        end
+        false
+      end
+      
+      def self.create_accessors(accessor)
+        define_method(accessor)       { fetch accessor }
+        define_method("#{accessor}=") { |v| store(accessor, v) }
+        true
+      end
+  end
+   
+end

data/lib/uses_stored_procedures/railtie.rb

@@ -0,0 +1,10 @@
+require 'active_record/railtie'
+require 'active_support/core_ext'
+
+module UsesStoredProcedures
+  class Railtie < Rails::Railtie
+    if defined?(ActiveRecord::Base)
+      ActiveRecord::Base.send :include, UsesStoredProcedures
+    end
+  end
+end

data/lib/uses_stored_procedures/version.rb

@@ -0,0 +1,3 @@
+module UsesStoreProcedures
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: uses-store-procedures
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Leo O'Donnell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.12
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.12
+description: ! 'So, you really need to use stored procedures in your Rails application.
+  This gem extends
+
+  ActiveRecord with a class method to add to your models or services.
+
+'
+email:
+- leopold.odonnell@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/tasks/uses-stored-procedures_tasks.rake
+- lib/uses_stored_procedures/hash_with_attributes.rb
+- lib/uses_stored_procedures/railtie.rb
+- lib/uses_stored_procedures/version.rb
+- lib/uses_stored_procedures.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: https://github.com/leopoldodonnell/uses-stored-procedures
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Extend ActiveRecord with the ability to use Stored Procedures.
+test_files: []
+has_rdoc: