sdk/ruby-google-api-client/lib/google/api_client/service/result.rb

   1 # Copyright 2013 Google Inc.
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #      http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 module Google
  16   class APIClient
  17     class Service
  18       ##
  19       # Handles an API result.
  20       # Wraps around the Google::APIClient::Result class, making it easier to
  21       # handle the result (e.g. pagination) and keeping it in line with the rest
  22       # of the Service programming interface.
  23       class Result
  24         extend Forwardable
  25
  26         ##
  27         # Init the result.
  28         #
  29         # @param [Google::APIClient::Service::Request] request
  30         #   The original request
  31         # @param [Google::APIClient::Result] base_result
  32         #   The base result to be wrapped
  33         def initialize(request, base_result)
  34           @request = request
  35           @base_result = base_result
  36         end
  37
  38         # @!attribute [r] status
  39         #   @return [Fixnum] HTTP status code
  40         # @!attribute [r] headers
  41         #   @return [Hash] HTTP response headers
  42         # @!attribute [r] body
  43         #   @return [String] HTTP response body
  44         def_delegators :@base_result, :status, :headers, :body
  45
  46         # @return [Google::APIClient::Service::Request] Original request object
  47         attr_reader :request
  48
  49         ##
  50         # Get the content type of the response
  51         # @!attribute [r] media_type
  52         # @return [String]
  53         #  Value of content-type header
  54         def_delegators :@base_result, :media_type
  55
  56         ##
  57         # Check if request failed
  58         #
  59         # @!attribute [r] error?
  60         # @return [TrueClass, FalseClass]
  61         #   true if result of operation is an error
  62         def_delegators :@base_result, :error?
  63
  64         ##
  65         # Check if request was successful
  66         #
  67         # @!attribute [r] success?
  68         # @return [TrueClass, FalseClass]
  69         #   true if result of operation was successful
  70         def_delegators :@base_result, :success?
  71
  72         ##
  73         # Extracts error messages from the response body
  74         #
  75         # @!attribute [r] error_message
  76         # @return [String]
  77         #   error message, if available
  78         def_delegators :@base_result, :error_message
  79
  80         ##
  81         # Check for parsable data in response
  82         #
  83         # @!attribute [r] data?
  84         # @return [TrueClass, FalseClass]
  85         #   true if body can be parsed
  86         def_delegators :@base_result, :data?
  87
  88         ##
  89         # Return parsed version of the response body.
  90         #
  91         # @!attribute [r] data
  92         # @return [Object, Hash, String]
  93         #   Object if body parsable from API schema, Hash if JSON, raw body if unable to parse
  94         def_delegators :@base_result, :data
  95
  96         ##
  97         # Pagination scheme used by this request/response
  98         #
  99         # @!attribute [r] pagination_type
 100         # @return [Symbol]
 101         #  currently always :token
 102         def_delegators :@base_result, :pagination_type
 103
 104         ##
 105         # Name of the field that contains the pagination token
 106         #
 107         # @!attribute [r] page_token_param
 108         # @return [String]
 109         #  currently always 'pageToken'
 110         def_delegators :@base_result, :page_token_param
 111
 112         ##
 113         # Get the token used for requesting the next page of data
 114         #
 115         # @!attribute [r] next_page_token
 116         # @return [String]
 117         #   next page tokenx =
 118         def_delegators :@base_result, :next_page_token
 119
 120         ##
 121         # Get the token used for requesting the previous page of data
 122         #
 123         # @!attribute [r] prev_page_token
 124         # @return [String]
 125         #   previous page token
 126         def_delegators :@base_result, :prev_page_token
 127
 128         # @!attribute [r] resumable_upload
 129         def resumable_upload
 130           # TODO(sgomes): implement resumable_upload for Service::Result
 131           raise NotImplementedError
 132         end
 133
 134         ##
 135         # Build a request for fetching the next page of data
 136         #
 137         # @return [Google::APIClient::Service::Request]
 138         #   API request for retrieving next page
 139         def next_page
 140           request = @request.clone
 141           # Make a deep copy of the parameters.
 142           request.parameters = Marshal.load(Marshal.dump(request.parameters))
 143           request.parameters[page_token_param] = self.next_page_token
 144           return request
 145         end
 146
 147         ##
 148         # Build a request for fetching the previous page of data
 149         #
 150         # @return [Google::APIClient::Service::Request]
 151         #   API request for retrieving previous page
 152         def prev_page
 153           request = @request.clone
 154           # Make a deep copy of the parameters.
 155           request.parameters = Marshal.load(Marshal.dump(request.parameters))
 156           request.parameters[page_token_param] = self.prev_page_token
 157           return request
 158         end
 159       end
 160     end
 161   end
 162 end