Class: ROM::HTTP::Dataset

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Options
Defined in:
lib/rom/http/dataset.rb,
lib/rom/http/dataset/response_transformers/schemad.rb,
lib/rom/http/dataset/response_transformers/schemaless.rb

Overview

HTTP Dataset

Represents a specific HTTP collection resource

Defined Under Namespace

Modules: ResponseTransformers

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config, options = {}) ⇒ Dataset

HTTP Dataset interface

Parameters:

  • config (Hash) —

    the Gateway’s HTTP server configuration

  • options (Hash) (defaults to: {}) —

    dataset configuration options

Options Hash (options):

  • :request_method (Symbol) — default: :get —

    The HTTP verb to use

  • :projections (Array) — default: [] —

    Keys to select from response tuple

  • :path (String) — default: '' —

    URI request path

  • :headers (Hash) — default: {} —

    Additional request headers

  • :params (Hash) — default: {} —

    HTTP request parameters



49
50
51
52
53
 
# File 'lib/rom/http/dataset.rb', line 49

def initialize(config, options = {})
  @config = config
  @response_transformer = ResponseTransformers::Schemaless.new
  super(options)
end

Instance Attribute Details

#config ⇒ Object (readonly) 



16
17
18
 
# File 'lib/rom/http/dataset.rb', line 16

def config
  @config
end

Class Method Details

.default_request_handler(handler = Undefined) ⇒ Object 



25
26
27
28
 
# File 'lib/rom/http/dataset.rb', line 25

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

.default_response_handler(handler = Undefined) ⇒ Object 



30
31
32
33
 
# File 'lib/rom/http/dataset.rb', line 30

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



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

def absolute_path
  '/' + 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:



165
166
167
 
# File 'lib/rom/http/dataset.rb', line 165

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

#append_path(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:



226
227
228
 
# File 'lib/rom/http/dataset.rb', line 226

def append_path(path)
  with_options(path: options[:path] + '/' + path)
end

#delete ⇒ Array<Hash>

Perform an delete over HTTP Delete

Returns:

  • (Array<Hash>) 


307
308
309
310
311
 
# File 'lib/rom/http/dataset.rb', line 307

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>) 


268
269
270
271
 
# File 'lib/rom/http/dataset.rb', line 268

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) 


94
95
96
 
# File 'lib/rom/http/dataset.rb', line 94

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

#insert(params) ⇒ Array<Hash>

Perform an insert over HTTP Post

Returns:

  • (Array<Hash>) 


280
281
282
283
284
285
 
# File 'lib/rom/http/dataset.rb', line 280

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

#name ⇒ String

Return the dataset name

Returns:

  • (String) 


103
104
105
 
# File 'lib/rom/http/dataset.rb', line 103

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



116
117
118
 
# File 'lib/rom/http/dataset.rb', line 116

def path
  options[:path].to_s.sub(%r{\A/}, '')
end

#project(*args) ⇒ Dataset

Add a new set projection to the result set

Examples:

users = Dataset.new(config, projections: [:login])
users.project(:email, :name).projections
# => [:login, :email, :name]

Parameters:

  • projections (Array, *args) —

    the keys to add to the projections

Returns:



192
193
194
195
196
197
198
 
# File 'lib/rom/http/dataset.rb', line 192

def project(*args)
  projections = args.first.is_a?(::Array) ? args.first : args

  with_options(
    projections: (self.projections + projections)
  )
end

#response ⇒ Array<hash>

Execute the current dataset

Returns:

  • (Array<hash>) 


318
319
320
321
322
323
 
# File 'lib/rom/http/dataset.rb', line 318

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

#response_transformer ⇒ Object #response_transformer(transformer) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Overloads:

  • #response_transformer ⇒ Object

    Return the current response transformer

  • #response_transformer(transformer) ⇒ Object

    Set a new response transformer

    Parameters:

    • transformer (#call) —

      The new response transformer



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

def response_transformer(transformer = Undefined)
  return @response_transformer if Undefined === transformer
  @response_transformer = transformer
end

#update(params) ⇒ Array<Hash>

Perform an update over HTTP Put

Returns:

  • (Array<Hash>) 


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

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



76
77
78
 
# File 'lib/rom/http/dataset.rb', line 76

def uri
  config.fetch(:uri) { fail Error, ':uri configuration missing' }
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:



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

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:



176
177
178
 
# File 'lib/rom/http/dataset.rb', line 176

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:



256
257
258
 
# File 'lib/rom/http/dataset.rb', line 256

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:



211
212
213
 
# File 'lib/rom/http/dataset.rb', line 211

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:



240
241
242
 
# File 'lib/rom/http/dataset.rb', line 240

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