jomz-google-api-client 0.7.1

data/lib/google/api_client/service.rb

@@ -0,0 +1,233 @@
+# Copyright 2013 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'google/api_client'
+require 'google/api_client/service/stub_generator'
+require 'google/api_client/service/resource'
+require 'google/api_client/service/request'
+require 'google/api_client/service/result'
+require 'google/api_client/service/batch'
+require 'google/api_client/service/simple_file_store'
+
+module Google
+  class APIClient
+
+    ##
+    # Experimental new programming interface at the API level.
+    # Hides Google::APIClient. Designed to be easier to use, with less code.
+    #
+    # @example
+    #   calendar = Google::APIClient::Service.new('calendar', 'v3')
+    #   result = calendar.events.list('calendarId' => 'primary').execute()
+    class Service
+      include Google::APIClient::Service::StubGenerator
+      extend Forwardable
+
+      DEFAULT_CACHE_FILE = 'discovery.cache'
+
+      # Cache for discovered APIs.
+      @@discovered = {}
+
+      ##
+      # Creates a new Service.
+      #
+      # @param [String, Symbol] api_name
+      #   The name of the API this service will access.
+      # @param [String, Symbol] api_version
+      #   The version of the API this service will access.
+      # @param [Hash] options
+      #   The configuration parameters for the service.
+      # @option options [Symbol, #generate_authenticated_request] :authorization
+      #   (:oauth_1)
+      #   The authorization mechanism used by the client.  The following
+      #   mechanisms are supported out-of-the-box:
+      #   <ul>
+      #     <li><code>:two_legged_oauth_1</code></li>
+      #     <li><code>:oauth_1</code></li>
+      #     <li><code>:oauth_2</code></li>
+      #   </ul>
+      # @option options [Boolean] :auto_refresh_token (true)
+      #   The setting that controls whether or not the api client attempts to
+      #   refresh authorization when a 401 is hit in #execute. If the token does
+      #   not support it, this option is ignored.
+      # @option options [String] :application_name
+      #   The name of the application using the client.
+      # @option options [String] :application_version
+      #   The version number of the application using the client.
+      # @option options [String] :host ("www.googleapis.com")
+      #   The API hostname used by the client. This rarely needs to be changed.
+      # @option options [String] :port (443)
+      #   The port number used by the client. This rarely needs to be changed.
+      # @option options [String] :discovery_path ("/discovery/v1")
+      #   The discovery base path. This rarely needs to be changed.
+      # @option options [String] :ca_file
+      #   Optional set of root certificates to use when validating SSL connections.
+      #   By default, a bundled set of trusted roots will be used.
+      # @option options [#generate_authenticated_request] :authorization
+      #   The authorization mechanism for requests. Used only if
+      #   `:authenticated` is `true`.
+      # @option options [TrueClass, FalseClass] :authenticated (default: true)
+      #   `true` if requests must be signed or somehow
+      #   authenticated, `false` otherwise.
+      # @option options [TrueClass, FalseClass] :gzip (default: true)
+      #   `true` if gzip enabled, `false` otherwise.
+      # @option options [Faraday::Connection] :connection
+      #   A custom connection to be used for all requests.
+      # @option options [ActiveSupport::Cache::Store, :default] :discovery_cache
+      #   A cache store to place the discovery documents for loaded APIs.
+      #   Avoids unnecessary roundtrips to the discovery service.
+      #   :default loads the default local file cache store.
+      def initialize(api_name, api_version, options = {})
+        @api_name = api_name.to_s
+        if api_version.nil?
+          raise ArgumentError,
+            "API version must be set"
+        end
+        @api_version = api_version.to_s
+        if options && !options.respond_to?(:to_hash)
+          raise ArgumentError,
+            "expected options Hash, got #{options.class}"
+        end
+
+        params = {}
+        [:application_name, :application_version, :authorization, :host, :port,
+         :discovery_path, :auto_refresh_token, :key, :user_ip,
+         :ca_file].each do |option|
+          if options.include? option
+            params[option] = options[option]
+          end
+        end
+
+        @client = Google::APIClient.new(params)
+
+        @connection = options[:connection] || @client.connection
+
+        @options = options
+
+        # Initialize cache store. Default to SimpleFileStore if :cache_store
+        # is not provided and we have write permissions.
+        if options.include? :cache_store
+          @cache_store = options[:cache_store]
+        else
+          cache_exists = File.exist?(DEFAULT_CACHE_FILE)
+          if (cache_exists && File.writable?(DEFAULT_CACHE_FILE)) ||
+             (!cache_exists && File.writable?(Dir.pwd))
+            @cache_store = Google::APIClient::Service::SimpleFileStore.new(
+              DEFAULT_CACHE_FILE)
+          end
+        end
+
+        # Attempt to read API definition from memory cache.
+        # Not thread-safe, but the worst that can happen is a cache miss.
+        unless @api = @@discovered[[api_name, api_version]]
+          # Attempt to read API definition from cache store, if there is one.
+          # If there's a miss or no cache store, call discovery service.
+          if !@cache_store.nil?
+            @api = @cache_store.fetch("%s/%s" % [api_name, api_version]) do
+              @client.discovered_api(api_name, api_version)
+            end
+          else
+            @api = @client.discovered_api(api_name, api_version)
+          end
+          @@discovered[[api_name, api_version]] = @api
+        end
+
+        generate_call_stubs(self, @api)
+      end
+
+      ##
+      # Returns the authorization mechanism used by the service.
+      #
+      # @return [#generate_authenticated_request] The authorization mechanism.
+      def_delegators :@client, :authorization, :authorization=
+
+      ##
+      # The setting that controls whether or not the service attempts to
+      # refresh authorization when a 401 is hit during an API call.
+      #
+      # @return [Boolean]
+      def_delegators :@client, :auto_refresh_token, :auto_refresh_token=
+
+      ##
+      # The application's API key issued by the API console.
+      #
+      # @return [String] The API key.
+      def_delegators :@client, :key, :key=
+
+      ##
+      # The Faraday/HTTP connection used by this service.
+      #
+      # @return [Faraday::Connection]
+      attr_accessor :connection
+
+      ##
+      # The cache store used for storing discovery documents.
+      #
+      # @return [ActiveSupport::Cache::Store,
+      #          Google::APIClient::Service::SimpleFileStore,
+      #          nil]
+      attr_reader :cache_store
+
+      ##
+      # Prepares a Google::APIClient::BatchRequest object to make batched calls.
+      # @param [Array] calls
+      #   Optional array of Google::APIClient::Service::Request to initialize
+      #   the batch request with.
+      # @param [Proc] block
+      #   Callback for every call's response. Won't be called if a call defined
+      #   a callback of its own.
+      #
+      # @yield [Google::APIClient::Service::Result]
+      #   block to be called when result ready
+      def batch(calls = nil, &block)
+        Google::APIClient::Service::BatchRequest.new(self, calls, &block)
+      end
+
+      ##
+      # Executes an API request.
+      # Do not call directly; this method is only used by Request objects when
+      # executing.
+      #
+      # @param [Google::APIClient::Service::Request,
+      #         Google::APIClient::Service::BatchCall] request
+      #   The request to be executed.
+      def execute(request)
+        if request.instance_of? Google::APIClient::Service::Request
+          params = {:api_method => request.method,
+            :parameters => request.parameters,
+            :connection => @connection}
+          if request.respond_to? :body
+            if request.body.respond_to? :to_hash
+              params[:body_object] = request.body
+            else
+              params[:body] = request.body
+            end
+          end
+          if request.respond_to? :media
+            params[:media] = request.media
+          end
+          [:authenticated, :gzip].each do |option|
+            if @options.include? option
+              params[option] = @options[option]
+            end
+          end
+          result = @client.execute(params)
+          return Google::APIClient::Service::Result.new(request, result)
+        elsif request.instance_of? Google::APIClient::Service::BatchRequest
+          @client.execute(request.base_batch)
+        end
+      end
+    end
+  end
+end

data/lib/google/api_client/service/batch.rb

@@ -0,0 +1,103 @@
+# Copyright 2013 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'google/api_client/service/result'
+require 'google/api_client/batch'
+
+module Google
+  class APIClient
+    class Service
+
+      ##
+      # Helper class to contain the result of an individual batched call.
+      #
+      class BatchedCallResult < Result
+        # @return [Fixnum] Index of the call
+        def call_index
+          return @base_result.response.call_id.to_i - 1
+        end
+      end
+
+      ##
+      #
+      #
+      class BatchRequest
+        ##
+        # Creates a new batch request.
+        # This class shouldn't be instantiated directly, but rather through
+        # Service.batch.
+        #
+        # @param [Array] calls
+        #   List of Google::APIClient::Service::Request to be made.
+        # @param [Proc] block
+        #   Callback for every call's response. Won't be called if a call
+        #   defined a callback of its own.
+        #
+        # @yield [Google::APIClient::Service::Result]
+        #   block to be called when result ready
+        def initialize(service, calls, &block)
+          @service = service
+          @base_batch = Google::APIClient::BatchRequest.new
+          @global_callback = block if block_given?
+
+          if calls && calls.length > 0
+            calls.each do |call|
+              add(call)
+            end
+          end
+        end
+
+        ##
+        # Add a new call to the batch request.
+        #
+        # @param [Google::APIClient::Service::Request] call
+        #   the call to be added.
+        # @param [Proc] block
+        #   callback for this call's response.
+        #
+        # @return [Google::APIClient::Service::BatchRequest]
+        #   the BatchRequest, for chaining
+        #
+        # @yield [Google::APIClient::Service::Result]
+        #   block to be called when result ready
+        def add(call, &block)
+          if !block_given? && @global_callback.nil?
+            raise BatchError, 'Request needs a block'
+          end
+          callback = block || @global_callback
+          base_call = {
+            :api_method => call.method,
+            :parameters => call.parameters
+          }
+          @base_batch.add(base_call) do |base_result|
+            result = Google::APIClient::Service::BatchedCallResult.new(
+                call, base_result)
+            callback.call(result)
+          end
+          return self
+        end
+
+        ##
+        # Executes the batch request.
+        def execute
+          @service.execute(self)
+        end
+
+        attr_reader :base_batch
+
+      end
+
+    end
+  end
+end

data/lib/google/api_client/service/request.rb

@@ -0,0 +1,144 @@
+# Copyright 2013 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Google
+  class APIClient
+    class Service
+      ##
+      # Handles an API request.
+      # This contains a full definition of the request to be made (including
+      # method name, parameters, body and media). The remote API call can be
+      # invoked with execute().
+      class Request
+        ##
+        # Build a request.
+        # This class should not be directly instantiated in user code;
+        # instantiation is handled by the stub methods created on Service and
+        # Resource objects.
+        #
+        # @param [Google::APIClient::Service] service
+        #   The parent Service instance that will execute the request.
+        # @param [Google::APIClient::Method] method
+        #   The Method instance that describes the API method invoked by the
+        #   request.
+        # @param [Hash] parameters
+        #   A Hash of parameter names and values to be sent in the API call.
+        def initialize(service, method, parameters)
+          @service = service
+          @method = method
+          @parameters = parameters
+          @body = nil
+          @media = nil
+
+          metaclass = (class << self; self; end)
+
+          # If applicable, add "body", "body=" and resource-named methods for
+          # retrieving and setting the HTTP body for this request.
+          # Examples of setting the body for files.insert in the Drive API:
+          #   request.body = object
+          #   request.execute
+          #  OR
+          #   request.file = object
+          #   request.execute
+          #  OR
+          #   request.body(object).execute
+          #  OR
+          #   request.file(object).execute
+          # Examples of retrieving the body for files.insert in the Drive API:
+          #   object = request.body
+          #  OR
+          #   object = request.file
+          if method.request_schema
+            body_name = method.request_schema.data['id'].dup
+            body_name[0] = body_name[0].chr.downcase
+            body_name_equals = (body_name + '=').to_sym
+            body_name = body_name.to_sym
+
+            metaclass.send(:define_method, :body) do |*args|
+              if args.length == 1
+                @body = args.first
+                return self
+              elsif args.length == 0
+                return @body
+              else
+                raise ArgumentError,
+                  "wrong number of arguments (#{args.length}; expecting 0 or 1)"
+              end
+            end
+
+            metaclass.send(:define_method, :body=) do |body|
+              @body = body
+            end
+
+            metaclass.send(:alias_method, body_name, :body)
+            metaclass.send(:alias_method, body_name_equals, :body=)
+          end
+
+          # If applicable, add "media" and "media=" for retrieving and setting
+          # the media object for this request.
+          # Examples of setting the media object:
+          #   request.media = object
+          #   request.execute
+          #  OR
+          #   request.media(object).execute
+          # Example of retrieving the media object:
+          #   object = request.media
+          if method.media_upload
+            metaclass.send(:define_method, :media) do |*args|
+              if args.length == 1
+                @media = args.first
+                return self
+              elsif args.length == 0
+                return @media
+              else
+                raise ArgumentError,
+                  "wrong number of arguments (#{args.length}; expecting 0 or 1)"
+              end
+            end
+
+            metaclass.send(:define_method, :media=) do |media|
+              @media = media
+            end
+          end
+        end
+
+        ##
+        # Returns the parent service capable of executing this request.
+        #
+        # @return [Google::APIClient::Service] The parent service.
+        attr_reader :service
+
+        ##
+        # Returns the Method instance that describes the API method invoked by
+        # the request.
+        #
+        # @return [Google::APIClient::Method] The API method description.
+        attr_reader :method
+
+        ##
+        # Contains the Hash of parameter names and values to be sent as the
+        # parameters for the API call.
+        #
+        # @return [Hash] The request parameters.
+        attr_accessor :parameters
+
+        ##
+        # Executes the request.
+        def execute
+          @service.execute(self)
+        end
+      end
+    end
+  end
+end