glebtv-httpclient 3.0.0

data/lib/httpclient/include_client.rb

@@ -0,0 +1,83 @@
+# It is useful to re-use a HTTPClient instance for multiple requests, to
+# re-use HTTP 1.1 persistent connections. 
+#
+# To do that, you sometimes want to store an HTTPClient instance in a global/
+# class variable location, so it can be accessed and re-used. 
+#
+# This mix-in makes it easy to create class-level access to one or more
+# HTTPClient instances. The HTTPClient instances are lazily initialized
+# on first use (to, for instance, avoid interfering with WebMock/VCR),
+# and are initialized in a thread-safe manner. Note that a 
+# HTTPClient, once initialized, is safe for use in multiple threads.
+#
+# Note that you `extend` HTTPClient::IncludeClient, not `include. 
+#
+#    require 'httpclient/include_client'
+#    class Widget
+#       extend HTTPClient::IncludeClient
+#
+#       include_http_client
+#       # and/or, specify more stuff
+#       include_http_client('http://myproxy:8080', :method_name => :my_client) do |client|
+#          # any init you want
+#          client.set_cookie_store nil
+#          client.
+#       end
+#    end
+#
+# That creates two HTTPClient instances available at the class level.
+# The first will be available from Widget.http_client (default method
+# name for `include_http_client`), with default initialization. 
+#
+# The second will be available at Widget.my_client, with the init arguments
+# provided, further initialized by the block provided. 
+#
+# In addition to a class-level method, for convenience instance-level methods
+# are also provided. Widget.http_client is identical to Widget.new.http_client
+#
+#
+class HTTPClient
+  module IncludeClient
+        
+
+    def include_http_client(*args, &block)
+      # We're going to dynamically define a class
+      # to hold our state, namespaced, as well as possibly dynamic
+      # name of cover method. 
+      method_name = (args.last.delete(:method_name) if args.last.kind_of? Hash) || :http_client
+      args.pop if args.last == {} # if last arg was named methods now empty, remove it.       
+      
+      # By the amazingness of closures, we can create these things
+      # in local vars here and use em in our method, we don't even
+      # need iVars for state. 
+      client_instance = nil
+      client_mutex = Mutex.new
+      client_args = args
+      client_block = block
+
+      # to define a _class method_ on the specific class that's currently
+      # `self`, we have to use this bit of metaprogramming, sorry. 
+      (class << self; self ; end).instance_eval do      
+        define_method(method_name) do                            
+          # implementation copied from ruby stdlib singleton
+          # to create this global obj thread-safely.
+          return client_instance if client_instance
+          client_mutex.synchronize do
+            return client_instance if client_instance
+            # init HTTPClient with specified args/block  
+            client_instance = HTTPClient.new(*client_args)
+            client_block.call(client_instance) if client_block
+          end
+          return client_instance
+        end
+      end
+      
+      # And for convenience, an  _instance method_ on the class that just
+      # delegates to the class method. 
+      define_method(method_name) do
+        self.class.send(method_name)
+      end
+          
+    end
+  end
+end