connection.rb in gooddata-0.6.0.pre11

- old
+ new

@@ -1,11 +1,13 @@
 require 'json'
 require 'rest-client'
 
+require File.join(File.dirname(__FILE__), 'version')
+
 module GoodData
 
-  # = GoodData HTTP wrapper
+  # # GoodData HTTP wrapper
   #
   # Provides a convenient HTTP wrapper for talking with the GoodData API.
   #
   # Remember that the connection is shared amongst the entire application.
   # Therefore you can't be logged in to more than _one_ GoodData account.
@@ -14,16 +16,15 @@
   #
   # The GoodData API is a RESTful API that communicates using JSON. This wrapper
   # makes sure that the session is stored between requests and that the JSON is
   # parsed both when sending and receiving.
   #
-  # == Usage
+  # ## Usage
   #
-  # Before a connection can be made to the GoodData API, you have to supply the user
-  # credentials using the set_credentials method:
+  # Before a connection can be made to the GoodData API, you have to supply the user credentials like this:
   #
-  #   Connection.new(username, password).set_credentials(username, password)
+  #   Connection.new(username, password)
   #
   # To send a HTTP request use either the get, post or delete methods documented below.
   #
   class Connection
 
@@ -32,21 +33,20 @@
     TOKEN_PATH = '/gdc/account/token'
 
     attr_reader(:auth_token, :url)
     attr_accessor :status, :options
 
-
     # Options:
     # * :tries - Number of retries to perform. Defaults to 1.
     # * :on - The Exception on which a retry will be performed. Defaults to Exception, which retries on any Exception.
     #
-    # Example
-    # =======
-    #   retryable(:tries => 1, :on => OpenURI::HTTPError) do
-    #     # your code here
-    #   end
+    # ### Example
     #
+    #     retryable(:tries => 1, :on => OpenURI::HTTPError) do
+    #       # your code here
+    #     end
+    #
     def retryable(options = {}, &block)
       opts = { :tries => 1, :on => Exception }.merge(options)
 
       retry_exception, retries = opts[:on], opts[:tries]
 
@@ -61,14 +61,13 @@
 
     # Set the GoodData account credentials.
     #
     # This have to be performed before any calls to the API.
     #
-    # === Parameters
+    # @param username The GoodData account username
+    # @param password The GoodData account password
     #
-    # * +username+ - The GoodData account username
-    # * +password+ - The GoodData account password
     def initialize(username, password, options = {})
       @status     = :not_connected
       @username   = username
       @password   = password
       @url        = options[:server] || DEFAULT_URL
@@ -87,17 +86,16 @@
 
     # Performs a HTTP GET request.
     #
     # Retuns the JSON response formatted as a Hash object.
     #
-    # === Parameters
+    # @param path The HTTP path on the GoodData server (must be prefixed with a forward slash)
     #
-    # * +path+ - The HTTP path on the GoodData server (must be prefixed with a forward slash)
+    # ### Examples
     #
-    # === Examples
+    #     Connection.new(username, password).get '/gdc/projects'
     #
-    #   Connection.new(username, password).get '/gdc/projects'
     def get(path, options = {})
       GoodData.logger.debug "GET #{@server}#{path}"
       ensure_connection
       b = Proc.new { @server[path].get cookies }
       process_response(options, &b)
@@ -105,20 +103,18 @@
 
     # Performs a HTTP POST request.
     #
     # Retuns the JSON response formatted as a Hash object.
     #
-    # === Parameters
+    # @param path The HTTP path on the GoodData server (must be prefixed with a forward slash)
+    # @param data The payload data in the format of a Hash object
     #
-    # * +path+ - The HTTP path on the GoodData server (must be prefixed with a forward slash)
-    # * +data+ - The payload data in the format of a Hash object
+    # ### Examples
     #
-    # === Examples
+    #     Connection.new(username, password).post '/gdc/projects', { ... }
     #
-    #   Connection.new(username, password).post '/gdc/projects', { ... }
     def post(path, data, options = {})
-      
       GoodData.logger.debug("POST #{@server}#{path}, payload: #{scrub_params(data, [:password, :login, :authorizationToken])}")
       ensure_connection
       payload = data.is_a?(Hash) ? data.to_json : data
       b = Proc.new { @server[path].post payload, cookies }
       process_response(options, &b)
@@ -126,18 +122,17 @@
 
     # Performs a HTTP PUT request.
     #
     # Retuns the JSON response formatted as a Hash object.
     #
-    # === Parameters
+    # @param path The HTTP path on the GoodData server (must be prefixed with a forward slash)
+    # @param data The payload data in the format of a Hash object
     #
-    # * +path+ - The HTTP path on the GoodData server (must be prefixed with a forward slash)
-    # * +data+ - The payload data in the format of a Hash object
+    # ### Examples
     #
-    # === Examples
+    #     Connection.new(username, password).put '/gdc/projects', { ... }
     #
-    #   Connection.new(username, password).put '/gdc/projects', { ... }
     def put(path, data, options = {})
       payload = data.is_a?(Hash) ? data.to_json : data
       GoodData.logger.debug "PUT #{@server}#{path}, payload: #{payload}"
       ensure_connection
       b = Proc.new { @server[path].put payload, cookies }
@@ -146,17 +141,16 @@
 
     # Performs a HTTP DELETE request.
     #
     # Retuns the JSON response formatted as a Hash object.
     #
-    # === Parameters
+    # @param path The HTTP path on the GoodData server (must be prefixed with a forward slash)
     #
-    # * +path+ - The HTTP path on the GoodData server (must be prefixed with a forward slash)
+    # ### Examples
     #
-    # === Examples
+    #     Connection.new(username, password).delete '/gdc/project/1'
     #
-    #   Connection.new(username, password).delete '/gdc/project/1'
     def delete(path, options = {})
       GoodData.logger.debug "DELETE #{@server}#{path}"
       ensure_connection
       b = Proc.new { @server[path].delete cookies }
       process_response(options, &b)
@@ -276,19 +270,30 @@
           where.write chunk
         end
       end
     end
 
+    def connected?
+      @status == :logged_in
+    end
+
+    def disconnect
+      if connected? && GoodData.connection.user["state"]
+        GoodData.delete(GoodData.connection.user["state"])
+        @status = :not_connected
+      end
+    end
+
     private
 
     def create_server_connection(url, options)
       RestClient::Resource.new url,
         :timeout => options[:timeout],
         :headers => {
           :content_type => :json,
           :accept => [ :json, :zip ],
-          :user_agent => GoodData.gem_version_string,
+          :user_agent => GoodData::gem_version_string,
         }
     end
 
     def ensure_connection
       connect if @status == :not_connected
@@ -370,10 +375,10 @@
             k[key_to_scrub] = ("*" * k[key_to_scrub].length) if k && k.has_key?(key_to_scrub) && k[key_to_scrub]
           rescue
             binding.pry
           end
         end
-      end      
+      end
       new_params
     end
 
   end
 end