google-api-client 0.7.0.rc2 → 0.7.0

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

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

@@ -0,0 +1,40 @@
+# 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 resource.
+      # Simple class that contains API methods and/or child resources.
+      class Resource
+        include Google::APIClient::Service::StubGenerator
+
+        ##
+        # Build a resource.
+        # This class should not be directly instantiated in user code; resources
+        # are instantiated by the stub generation mechanism on Service creation.
+        #
+        # @param [Google::APIClient::Service] service
+        #   The Service instance this resource belongs to.
+        # @param [Google::APIClient::API, Google::APIClient::Resource] root
+        #   The node corresponding to this resource.
+        def initialize(service, root)
+          @service = service
+          generate_call_stubs(service, root)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# 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 result.
+      # Wraps around the Google::APIClient::Result class, making it easier to
+      # handle the result (e.g. pagination) and keeping it in line with the rest
+      # of the Service programming interface.
+      class Result
+        extend Forwardable
+
+        ##
+        # Init the result.
+        #
+        # @param [Google::APIClient::Service::Request] request
+        #   The original request
+        # @param [Google::APIClient::Result] base_result
+        #   The base result to be wrapped
+        def initialize(request, base_result)
+          @request = request
+          @base_result = base_result
+        end
+
+        # @!attribute [r] status
+        #   @return [Fixnum] HTTP status code
+        # @!attribute [r] headers
+        #   @return [Hash] HTTP response headers
+        # @!attribute [r] body
+        #   @return [String] HTTP response body
+        def_delegators :@base_result, :status, :headers, :body
+
+        # @return [Google::APIClient::Service::Request] Original request object
+        attr_reader :request
+
+        ##
+        # Get the content type of the response
+        # @!attribute [r] media_type
+        # @return [String]
+        #  Value of content-type header
+        def_delegators :@base_result, :media_type
+
+        ##
+        # Check if request failed
+        #
+        # @!attribute [r] error?
+        # @return [TrueClass, FalseClass]
+        #   true if result of operation is an error
+        def_delegators :@base_result, :error?
+
+        ##
+        # Check if request was successful
+        #
+        # @!attribute [r] success?
+        # @return [TrueClass, FalseClass]
+        #   true if result of operation was successful
+        def_delegators :@base_result, :success?
+
+        ##
+        # Extracts error messages from the response body
+        #
+        # @!attribute [r] error_message
+        # @return [String]
+        #   error message, if available
+        def_delegators :@base_result, :error_message
+
+        ##
+        # Check for parsable data in response
+        #
+        # @!attribute [r] data?
+        # @return [TrueClass, FalseClass]
+        #   true if body can be parsed
+        def_delegators :@base_result, :data?
+
+        ##
+        # Return parsed version of the response body.
+        #
+        # @!attribute [r] data
+        # @return [Object, Hash, String]
+        #   Object if body parsable from API schema, Hash if JSON, raw body if unable to parse
+        def_delegators :@base_result, :data
+
+        ##
+        # Pagination scheme used by this request/response
+        #
+        # @!attribute [r] pagination_type
+        # @return [Symbol]
+        #  currently always :token
+        def_delegators :@base_result, :pagination_type
+
+        ##
+        # Name of the field that contains the pagination token
+        #
+        # @!attribute [r] page_token_param
+        # @return [String]
+        #  currently always 'pageToken'
+        def_delegators :@base_result, :page_token_param
+
+        ##
+        # Get the token used for requesting the next page of data
+        #
+        # @!attribute [r] next_page_token
+        # @return [String]
+        #   next page tokenx =
+        def_delegators :@base_result, :next_page_token
+
+        ##
+        # Get the token used for requesting the previous page of data
+        #
+        # @!attribute [r] prev_page_token
+        # @return [String]
+        #   previous page token
+        def_delegators :@base_result, :prev_page_token
+
+        # @!attribute [r] resumable_upload
+        def resumable_upload
+          # TODO(sgomes): implement resumable_upload for Service::Result
+          raise NotImplementedError
+        end
+
+        ##
+        # Build a request for fetching the next page of data
+        #
+        # @return [Google::APIClient::Service::Request]
+        #   API request for retrieving next page
+        def next_page
+          request = @request.clone
+          # Make a deep copy of the parameters.
+          request.parameters = Marshal.load(Marshal.dump(request.parameters))
+          request.parameters[page_token_param] = self.next_page_token
+          return request
+        end
+
+        ##
+        # Build a request for fetching the previous page of data
+        #
+        # @return [Google::APIClient::Service::Request]
+        #   API request for retrieving previous page
+        def prev_page
+          request = @request.clone
+          # Make a deep copy of the parameters.
+          request.parameters = Marshal.load(Marshal.dump(request.parameters))
+          request.parameters[page_token_param] = self.prev_page_token
+          return request
+        end
+      end
+    end
+  end
+end