salesforce_cache 0.0.6

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+CHANGELOG
+---------
+- **2014-03-05**: 0.0.6
+  - Ability to disable remote downloading from Salesforce.com when it is not desirable
+  - Convert README and CHANGELOG files to Markdown format
+  - Rename to SalesforceCache from SalesforceFsdb
+- **2014-03-05**: 0.0.5
+  - Deprecation notice for SalesforceFsdb
+- **2014-02-19**: 0.0.4
+  - Add "redirect" in case an Opportunity Id is presented for an Account sObject
+  - Add autoload to enable "require 'salesforce_fsdb'" (now require 'salesforce_cache')
+- **2014-02-06**: 0.0.3
+  - Add SOQL result caching
+- **2014-01-28**: 0.0.2
+  - Use sObject types in filenames to enable wider, more generic sObject support
+- **2014-01-27**: 0.0.1
+  - Initial release
+  - Filesystem cache of Account, Contact, Opportunity and User sObjects.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2014 John Wang
+ 
+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,127 @@
+SalesforceCache: SFDC sObject / SOQL Request Caching
+====================================================
+
+Synopsis
+--------
+
+Salesforce sObject system to retrieve and cache queries from Salesforce.com including sObjects and SOQL results. This currently uses the file system to cache results though other storage methods may be supported in the future.
+
+Prior to version 0.0.6, SalesforceCache was named SalesforceFsdb.
+
+Installing
+----------
+
+To install SalesforceCache, use the following command:
+
+    $ gem install salesforce_cache
+
+#Examples
+---------
+
+    require 'salesforce_cache'
+
+    paramsGeneral    =  {
+      :api_fqdn      => 'na1.salesforce.com',
+      :api_version   => '29.0',
+      :data_dir      => '/path/to/sf_data',
+      :max_age       => 60*60*24*7,
+      :skip_remote   => false                  # optional
+    }
+
+    paramsToken      =  {
+      :grant_type    => 'password',
+      :client_id     => 'my_client_id',
+      :client_secret => 'my_client_secret',
+      :username      => 'my_username',
+      :password      => 'my_password'
+    }
+
+    # using the filesystem cache with max_age
+    sfCacheClient = SalesforceCache::Client.new(paramsGeneral,paramsToken)
+    sObjectHash   = sfCacheClient.getSobjectForSfidAndType('my_sobject_id','Account')
+
+    sSfid = '1234567890'
+    sSoql = %{ SELECT Id,AccountId,Name,IsWon,StageName,CloseDate from Opportunity where AccountId='\#{sSfid}' }
+    sPath = "AccountOpportunities/sf_act_\#{sSfid}_opps.jff"
+
+    dResults = sfCacheClient.getResForSoqlAndPath( sSoql, sPath )
+
+    # without using a filesystem cache
+    sfRestClient = SalesforceCache::RestClient.new(paramsGeneral,paramsToken)
+    sObjectHash  = sfRestClient.getSobjectForSfidAndType('my_sobject_id','Account')
+
+#Documentation
+--------------
+
+This gem is 100% documented with YARD, an exceptional documentation library. To see documentation for this, and all the gems installed on your system use:
+
+    $ gem install yard
+    $ yard server -g
+
+Notes
+-----
+
+1. Max Age
+
+  The :max_age parameter is used to indicate the maximum age in seconds for cached data. If local data exceeds maximum age, a new copy of the data is retrieved from Salesforce.com. To ensure retrieval of a new copy, use :max_age=-1.
+
+2. Disable Remote Requests
+
+  If the optional :skip_remote parameter is set to true, the :max_age parameter is ignored and a local copy will be used if available. A remote call to Salesforce will not be issued if a local cache is not found. This is for environments when it is undesirable to make outside requests.
+
+  The default value is false.
+
+3. Directory Paths
+
+  1. Salesforce Sobjects are stored on the file system under File.join( paramsGeneral[:data_dir], Sobject_type ).
+
+  2. SOQL results are stored in the path indicated. Sub-directories are created for SOQL paths. If a relative directory is provided, it is appended to the :data_dir. If an absolute directory is provided, it is used as an absolute directory in its entirety.
+
+4. Object Size
+
+  Some large Salesforce Objects may generate Salesforce errors. A future release will allow specifying specific fields for retrieval.
+
+5. Redirection
+
+  In the event an Account sObject request results in a NOT_FOUND error for a given Salesforce Id, the library will attempt to use the Id as an Opportunity Id and, if successful, will return the proper Account sObject.
+
+#Change Log
+-----------
+
+- **2014-03-05**: 0.0.6
+  - Ability to disable remote downloading from Salesforce.com when it is not desirable
+  - Convert README and CHANGELOG files to Markdown format
+  - Rename to SalesforceCache from SalesforceFsdb
+- **2014-03-05**: 0.0.5
+  - Deprecation notice for SalesforceFsdb
+- **2014-02-19**: 0.0.4
+  - Add "redirect" in case an Opportunity Id is presented for an Account sObject
+  - Add autoload to enable "require 'salesforce_fsdb'" (now require 'salesforce_cache')
+- **2014-02-06**: 0.0.3
+  - Add SOQL result caching
+- **2014-01-28**: 0.0.2
+  - Use sObject types in filenames to enable wider, more generic sObject support
+- **2014-01-27**: 0.0.1
+  - Initial release
+  - Filesystem cache of Account, Contact, Opportunity and User sObjects.
+
+Please see the {file:CHANGELOG.md} document for additional release information.
+
+#Links
+------
+
+Salesforce REST API Reference
+
+http://www.salesforce.com/us/developer/docs/api_rest/
+
+#Copyright and License
+----------------------
+
+SalesforceCache © 2014 by [John Wang](mailto:johncwang@gmail.com).
+
+SalesforceCache is licensed under the MIT license. Please see the LICENSE document for more information.
+
+Warranty
+--------
+
+This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+
+task :build => :gendoc do
+  system "gem build salesforce_cache.gemspec"
+end
+
+task :gendoc do
+  #puts 'yard doc generation disabled until JRuby build native extensions for redcarpet or yard removes the dependency.'
+  system "yardoc"
+  system "yard stats --list-undoc"
+end
+
+task :default => :test
+
+desc 'Test the SalesforceFsdb library.'
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = false
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.6

data/lib/salesforce_cache/client.rb

@@ -0,0 +1,137 @@
+require 'fileutils'
+require 'json'
+require 'salesforce_cache/rest_client'
+
+module SalesforceCache
+  class Client
+    attr_accessor :oSfRestClient
+
+    def initialize(dParamsGeneral={},dParamsToken={})
+      if dParamsGeneral.has_key?(:disable_remote) && dParamsGeneral[:disable_remote]
+        @bRemoteEnabled = false
+      else
+        @bRemoteEnabled = true
+      end
+      @oSfRestClient  = @bRemoteEnabled \
+        ? SalesforceCache::RestClient.new(dParamsGeneral,dParamsToken) : nil
+      @sFsdbBaseDir   = dParamsGeneral[:data_dir] || '.'
+      @iMaxAgeSec     = dParamsGeneral[:max_age]  || 3600*24*7
+    end
+
+    def getFileForSfidAndType(sSfid=nil,sType=nil)
+      sFile  = %Q{sf_#{sType}_#{sSfid}.json}
+      return sFile
+    end
+
+    def getDirForType(sType=nil)
+      sDir   = File.join(@sFsdbBaseDir,sType)
+      return sDir
+    end
+
+    def getPathForSfidAndType(sSfid=nil,sType=nil)
+      sPath  = File.join( self.getDirForType(sType), self.getFileForSfidAndType(sSfid,sType))
+      return sPath
+    end
+
+    def getResForSoqlAndPath(sSoql=nil,sPath=nil)
+      return nil if sSoql.nil?
+      if ! sPath.nil? && sPath !~ /^\s*\//
+        sPath.strip!
+        sPath = File.join(@sFsdbBaseDir,sPath)
+      end
+      dRes      = { :meta => { :iEpochRetrieved => -1, :iStatus => 404 } }
+      if !sPath.nil? && File.exists?(sPath)
+        jTop    = File.open(sPath,'r').read
+        dTop    = JSON.parse(jTop,:symbolize_names=>true)
+        if dTop.has_key?(:source) && dTop.has_key?(:meta) && dTop[:meta].has_key?(:iEpochRetrieved)
+          iEpochRetrieved = dTop[:meta][:iEpochRetrieved]
+          iEpochNow       = Time.now.to_i
+          iAgeSec         = iEpochNow - iEpochRetrieved
+          if ! @bRemoteEnabled || ( iAgeSec < @iMaxAgeSec && dTop[:source].has_key?(:done) )
+            dRes = dTop[:source]
+            return dRes
+          end
+        end
+      end
+      return @bRemoteEnabled ? self.getResForSoqlAndPathFromRemote(sSoql,sPath) : nil
+    end
+
+    def getResForSoqlAndPathFromRemote(sSoql=nil,sPath=nil)
+      return nil if sSoql.nil?
+      if ! sPath.nil? && sPath !~ /^\s*\//
+        sPath.strip!
+        sPath = File.join(@sFsdbBaseDir,sPath)
+      end
+      dRes = @oSfRestClient.getSoqlResults(sSoql)
+      if ! dRes.nil? && dRes.has_key?(:done) && dRes[:done] == true && ! sPath.nil?
+        if sPath =~ /^([\S]+)\/[^\/]+$/
+          sDir   = $1
+          FileUtils.mkdir_p(sDir) if ! Dir.exists?(sDir)
+        end
+        File.open(sPath,'w') do |fTop|
+          dTop      =  {
+            :meta   => { :iEpochRetrieved => Time.now.to_i, :iStatus => 200 },
+            :source => dRes
+          }
+          jTop = JSON.dump(dTop)
+          fTop.puts(jTop)
+        end
+        return dRes
+      end
+      return nil
+    end
+
+    def getSobjectForSfidAndType(sSfid=nil,sType=nil)
+      sPath     = self.getPathForSfidAndType(sSfid,sType)
+      dObj      = { :meta => { :iEpochRetrieved => -1, :iStatus => 404 } }
+      if File.exists?(sPath)
+        jTop    = File.open(sPath,'r').read
+        dTop    = JSON.parse(jTop,:symbolize_names=>true)
+        if dTop.has_key?(:source) && dTop.has_key?(:meta) && dTop[:meta].has_key?(:iEpochRetrieved)
+          iEpochRetrieved = dTop[:meta][:iEpochRetrieved]
+          iEpochNow       = Time.now.to_i
+          iAgeSec         = iEpochNow - iEpochRetrieved
+          if ! @bRemoteEnabled || ( iAgeSec < @iMaxAgeSec && dTop[:source].has_key?(:Id) )
+            dObj = dTop[:source]
+            return dObj
+          end
+        end
+      end
+      return @bRemoteEnabled ? self.getSobjectForSfidAndTypeFromRemote(sSfid,sType) : nil
+    end
+
+    def getSobjectForSfidAndTypeFromRemote(sSfid=nil,sType=nil)
+      dObj = @oSfRestClient.getSobjectForSfidAndType(sSfid,sType)
+      if (dObj.is_a?(Array) && dObj[0][:errorCode] == 'NOT_FOUND') || dObj.nil?
+        if sType == 'Account'
+
+          dObjOppTry = self.getSobjectForSfidAndType(sSfid,'Opportunity')
+
+          if dObjOppTry.is_a?(Hash) && dObjOppTry.has_key?(:AccountId)
+            sSfidAct = dObjOppTry[:AccountId]
+            return self.getSobjectForSfidAndType(sSfidAct,sType)
+          end
+
+        else
+          return nil
+        end
+      end
+      if dObj.is_a?(Hash) && dObj.has_key?(:Id)
+        sDir        = self.getDirForType(sType)
+        sPath       = self.getPathForSfidAndType(sSfid,sType)
+        FileUtils.mkdir_p(sDir) if ! Dir.exists?(sDir)
+        File.open(sPath,'w') do |fTop|
+          dTop      =  {
+            :meta   => { :iEpochRetrieved => Time.now.to_i, :iStatus => 200 },
+            :source => dObj
+          }
+          jTop = JSON.dump(dTop)
+          fTop.puts(jTop)
+        end
+        return dObj
+      end
+      return nil
+    end
+
+  end
+end

data/lib/salesforce_cache/rest_client.rb

@@ -0,0 +1,91 @@
+require 'faraday'
+require 'json'
+
+module SalesforceCache
+  class RestClient
+
+    attr_accessor :sSfTokenUrl
+    attr_accessor :dTokenRes
+
+    def initialize(dParamsGeneral={},dParamsToken={})
+      @dParamsToken = dParamsToken
+      @sSfTokenUrl  = dParamsGeneral.has_key?(:token_url)   ? dParamsGeneral[:token_url] \
+                    : 'https://login.salesforce.com/services/oauth2/token'
+      @sApiFqdn     = dParamsGeneral.has_key?(:api_fqdn)    ? dParamsGeneral[:api_fqdn] : 'na5.salesforce.com'
+      @sApiVersion  = dParamsGeneral.has_key?(:api_version) ? dParamsGeneral[:api_version] : '27.0'
+      @dTokenRes    = {}
+      self.loadToken()
+    end
+
+    def loadToken()
+      oRes       = Faraday.post(@sSfTokenUrl,@dParamsToken) 
+      @dTokenRes = JSON.parse(oRes.body,:symbolize_names=>true)
+      return self
+    end
+
+    def getAttr(yKey=nil)
+      yKey  = yKey.to_sym if yKey.is_a?(String)
+      xxVal = @dTokenRes.has_key?(yKey) ? @dTokenRes[yKey] : nil
+      return xxVal
+    end
+
+    def getHeaders()
+      dHeaders = { 'Authorization' => 'Bearer ' + self.getAttr(:access_token) }
+      return dHeaders
+    end
+
+    def getSoqlResults(sSoql=nil)
+      dQry  = { :q => sSoql}
+      sUrl  = "https://#{@sApiFqdn}/services/data/v#{@sApiVersion}/query"
+      dHead = self.getHeaders()
+      oRes  = Faraday.get(sUrl,dQry,dHead)
+      dRes  = JSON.parse(oRes.body,:symbolize_names=>true)
+      return dRes
+    end
+
+    def getSfUrlForSfidAndType(sSfid=nil,sType=nil)
+      sUrl  = "https://#{@sApiFqdn}/services/data/v#{@sApiVersion}/sobjects/#{sType}/#{sSfid}/"
+      return sUrl
+    end
+
+    def getSobjectForSfidAndType(sSfid=nil,sType=nil)
+      sUrl  = self.getSfUrlForSfidAndType(sSfid,sType)
+      sHead = self.getHeaders()
+      oRes  = Faraday.get(sUrl,{},sHead)
+      dRes  = JSON.parse(oRes.body,:symbolize_names=>true)
+      return dRes
+    end
+
+  end
+end
+
+=begin
+  
+SFDC Error: Unable to Process Request
+
+'<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> (JSON::ParserError)
+
+<html>
+    <head>
+        <title>Unable to Process Request</title>
+        <link  href="/dCSS/Theme2/default/maintenance.css" type="text/css" rel="stylesheet" >
+    </head>
+
+    <body>
+        <div id="red">
+            <div id="box">
+                <h1>Unable to Process Request</h1>
+                <h2>We apologize for the inconvenience</h2>
+                <br><br>
+                The salesforce.com servers are temporarily unable to respond to your request.  We apologize for the inconvenience.<br>
+                Thank you for your patience, and please try again in a few moments.
+                <br><br>
+                Visit <a href=http://trust.salesforce.com>http://trust.salesforce.com</a> for current system status and availability.
+                <br><br>
+                <form><p class="input"><a href="javascript:history.back()" class="back">back</a><span>&nbsp;</span></form>
+            </div>
+        </div>
+    </body>
+</html>' 
+
+=end

data/lib/salesforce_cache.rb

@@ -0,0 +1,4 @@
+module SalesforceCache
+  autoload :Client, 'salesforce_cache/client'
+  autoload :RestClient, 'salesforce_cache/rest_client'
+end

data/salesforce_cache.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name        = 'salesforce_cache'
+  s.version     = '0.0.6'
+  s.date        = '2014-03-05'
+  s.summary     = 'Salesforce Filesystem Cache'
+  s.description = 'Filesystem cache manager for Salesforce sObjects and SOQL results'
+  s.authors     = ['John Wang']
+  s.email       = 'johncwang@gmail.com'
+  s.files       = [
+    'CHANGELOG.md',
+    'LICENSE',
+    'README.md',
+    'Rakefile',
+    'VERSION',
+    'salesforce_cache.gemspec',
+    'lib/salesforce_cache.rb',
+    'lib/salesforce_cache/client.rb',
+    'lib/salesforce_cache/rest_client.rb',
+    'test/test_setup.rb'
+  ]
+  s.homepage    = 'http://johnwang.com/'
+  s.license     = 'MIT'
+end

data/test/test_setup.rb

@@ -0,0 +1,29 @@
+require 'test/unit'
+require 'salesforce_cache/client'
+
+class SalesforceCacheTest < Test::Unit::TestCase
+  def testSetup
+    paramsGeneral    =  {
+      :api_fqdn      => 'na1.salesforce.com',
+      :api_version   => '29.0',
+      :data_dir      => '/path/to/sf_data',
+      :max_age       => 60*60*24*7
+    }
+
+    paramsToken      =  {
+      :grant_type    => 'password',
+      :client_id     => 'my_client_id',
+      :client_secret => 'my_client_secret',
+      :username      => 'my_username',
+      :password      => 'my_password'
+    }
+
+    sfFsdbClient = SalesforceCache::Client.new(paramsGeneral,paramsToken)
+    accountDir   = sfFsdbClient.getDirForType('Account')
+
+    assert_equal accountDir, File.join(paramsGeneral[:data_dir],'Account')
+
+    tokenUrl     = 'https://login.salesforce.com/services/oauth2/token'
+    assert_equal tokenUrl, sfFsdbClient.oSfRestClient.sSfTokenUrl
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: salesforce_cache
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.6
+platform: ruby
+authors: 
+- John Wang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2014-03-05 00:00:00 Z
+dependencies: []
+
+description: Filesystem cache manager for Salesforce sObjects and SOQL results
+email: johncwang@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- salesforce_cache.gemspec
+- lib/salesforce_cache.rb
+- lib/salesforce_cache/client.rb
+- lib/salesforce_cache/rest_client.rb
+- test/test_setup.rb
+homepage: http://johnwang.com/
+licenses: 
+- MIT
+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.11
+signing_key: 
+specification_version: 3
+summary: Salesforce Filesystem Cache
+test_files: []
+