Class: ROM::HTTP::Dataset

Inherits:
Object
  • Object
show all
Extended by:
Initializer
Includes:
Enumerable
Defined in:
lib/rom/http/dataset.rb

Overview

HTTP Dataset

Represents a specific HTTP collection resource

Constant Summary collapse

PATH_SEPARATOR = 
'/'.freeze
STRIP_PATH = 
->(path) { path.sub(%r{\A/}, '') }.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.default_request_handler(handler = Undefined) ⇒ Object 



27
28
29
30
 
# File 'lib/rom/http/dataset.rb', line 27

def default_request_handler(handler = Undefined)
  return @default_request_handler if Undefined === handler
  @default_request_handler = handler
end

.default_response_handler(handler = Undefined) ⇒ Object 



32
33
34
35
 
# File 'lib/rom/http/dataset.rb', line 32

def default_response_handler(handler = Undefined)
  return @default_response_handler if Undefined === handler
  @default_response_handler = handler
end

Instance Method Details

#absolute_path ⇒ string

Return the dataset path

Examples:

Dataset.new(config, path: '/users').path
# => '/users'

Returns:

  • (string) —

    the dataset path, with leading slash



111
112
113
 
# File 'lib/rom/http/dataset.rb', line 111

def absolute_path
  PATH_SEPARATOR + path
end

#add_header(header, value) ⇒ Dataset

Return a new dataset with additional header

Examples:

users = Dataset.new(config, headers: { Accept: 'application/json' })
users.add_header(:'X-Api-Key', '1234').headers
# => { :Accept => 'application/json', :'X-Api-Key' => '1234' }

Parameters:

  • header (Symbol) —

    the HTTP header to add

  • value (String) —

    the header value

Returns:



147
148
149
 
# File 'lib/rom/http/dataset.rb', line 147

def add_header(header, value)
  with_headers(headers.merge(header => value))
end

#append_path(append_path) ⇒ Dataset

Return a new dataset with a modified path

Examples:

users.append_path('profiles').path
# => users/profiles

Parameters:

  • path (String) —

    new path fragment

Returns:



203
204
205
 
# File 'lib/rom/http/dataset.rb', line 203

def append_path(append_path)
  with_options(path: join_path(path, append_path))
end

#base_path ⇒ String

Return the base path

Examples:

Dataset.new(config, base_path: '/users').base_path
# => 'users'

Returns:

  • (String) —

    the dataset path, without a leading slash



85
86
87
 
# File 'lib/rom/http/dataset.rb', line 85

def base_path
  STRIP_PATH.call(super)
end

#delete ⇒ Array<Hash>

Perform an delete over HTTP Delete

Returns:

  • (Array<Hash>) 


284
285
286
287
288
 
# File 'lib/rom/http/dataset.rb', line 284

def delete
  with_options(
    request_method: :delete
  ).response
end

#each {|Hash| ... } ⇒ Enumerator, Array<Hash>

Iterate over each response value

Yields:

  • (Hash) —

    a dataset tuple

Returns:

  • (Enumerator) —

    if no block is given

  • (Array<Hash>) 


245
246
247
248
 
# File 'lib/rom/http/dataset.rb', line 245

def each(&block)
  return to_enum unless block_given?
  response.each(&block)
end

#headers ⇒ Hash

Return request headers

Merges default headers from the Gateway configuration and the current Dataset

Examples:

config = { Accepts: 'application/json' }
users  = Dataset.new(config, headers: { 'Cache-Control': 'no-cache' }
users.headers
# => {:Accepts => "application/json", :'Cache-Control' => 'no-cache'}

Returns:

  • (Hash) 


63
64
65
 
# File 'lib/rom/http/dataset.rb', line 63

def headers
  config.fetch(:headers, {}).merge(options.fetch(:headers, {}))
end

#insert(params) ⇒ Array<Hash>

Perform an insert over HTTP Post

Returns:

  • (Array<Hash>) 


257
258
259
260
261
262
 
# File 'lib/rom/http/dataset.rb', line 257

def insert(params)
  with_options(
    request_method: :post,
    params: params
  ).response
end

#name ⇒ String

Return the dataset name

Returns:

  • (String) 


72
73
74
 
# File 'lib/rom/http/dataset.rb', line 72

def name
  config[:name].to_s
end

#path ⇒ String

Return the dataset path

Examples:

Dataset.new(config, path: '/users').path
# => 'users'

Returns:

  • (String) —

    the dataset path, without a leading slash



98
99
100
 
# File 'lib/rom/http/dataset.rb', line 98

def path
  STRIP_PATH.call(join_path(base_path, super))
end

#response ⇒ Array<hash>

Execute the current dataset

Returns:

  • (Array<hash>) 


295
296
297
 
# File 'lib/rom/http/dataset.rb', line 295

def response
  response_handler.call(request_handler.call(self), self)
end

#update(params) ⇒ Array<Hash>

Perform an update over HTTP Put

Returns:

  • (Array<Hash>) 


271
272
273
274
275
276
 
# File 'lib/rom/http/dataset.rb', line 271

def update(params)
  with_options(
    request_method: :put,
    params: params
  ).response
end

#uri ⇒ String

Return the gateway’s URI

Returns:

  • (String)

Raises:

  • (Error) —

    if the configuration does not contain a URI



45
46
47
 
# File 'lib/rom/http/dataset.rb', line 45

def uri
  config.fetch(:uri) { fail Error, ':uri configuration missing' }
end

#with_base_path(base_path) ⇒ Dataset

Return a new dataset with a different base path

Examples:

users.with_base_path('/profiles').base_path
# => 'profiles'

Parameters:

  • base_path (String) —

    the new base request path

Returns:



173
174
175
 
# File 'lib/rom/http/dataset.rb', line 173

def with_base_path(base_path)
  with_options(base_path: base_path)
end

#with_headers(headers) ⇒ Dataset

Note:

this replaces the dataset’s currently configured headers. To non-destructively add a new header, use #add_header

Return a new dataset with given headers

Examples:

users = Dataset.new(config, headers: { Accept: 'application/json' })
users.with_headers(:'X-Api-Key' => '1234').headers
# => { :'X-Api-Key' => '1234' }

Parameters:

  • headers (Hash) —

    The new headers

Returns:



130
131
132
 
# File 'lib/rom/http/dataset.rb', line 130

def with_headers(headers)
  __new__(config, options.merge(headers: headers))
end

#with_options(opts) ⇒ Dataset

Return a new dataset with additional options

Parameters:

  • opts (Hash) —

    the new options to add

Returns:



158
159
160
 
# File 'lib/rom/http/dataset.rb', line 158

def with_options(opts)
  __new__(config, options.merge(opts))
end

#with_params(params) ⇒ Dataset

Return a new dataset with replaced request parameters

Examples:

users = Dataset.new(config, params: { uid: 33 })
users.with_params(login: 'jdoe').params
# => { :login => 'jdoe' }

Parameters:

  • params (Hash) —

    the new request parameters

Returns:



233
234
235
 
# File 'lib/rom/http/dataset.rb', line 233

def with_params(params)
  with_options(params: params)
end

#with_path(path) ⇒ Dataset

Return a new dataset with a different path

Examples:

users.with_path('/profiles').path
# => 'profiles'

Parameters:

  • path (String) —

    the new request path

Returns:



188
189
190
 
# File 'lib/rom/http/dataset.rb', line 188

def with_path(path)
  with_options(path: path)
end

#with_request_method(request_method) ⇒ Dataset

Return a new dataset with a different request method

Examples:

users.request_method(:put)

Parameters:

  • request_method (Symbol) —

    the new HTTP verb

Returns:



217
218
219
 
# File 'lib/rom/http/dataset.rb', line 217

def with_request_method(request_method)
  with_options(request_method: request_method)
end