Class: ROM::HTTP::Dataset

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

Overview

HTTP Dataset

Represents a specific HTTP collection resource. This class can be subclassed in a specialized HTTP adapter to provide its own response/request handlers or any other configuration that should differ from the defaults.

Constant Summary collapse

PATH_SEPARATOR = 
"/"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#base_path ⇒ String (readonly)

Returns:

  • (String) 


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

option :base_path, type: Types::Path, default: proc { EMPTY_STRING }

#body_params ⇒ Hash (readonly)

Returns:

  • (Hash) 


109
 
# File 'lib/rom/http/dataset.rb', line 109

option :body_params, type: Types::Hash, default: proc { EMPTY_HASH }

#headers ⇒ Hash (readonly)

Returns:

  • (Hash) 


114
 
# File 'lib/rom/http/dataset.rb', line 114

option :headers, type: Types::Hash, default: proc { EMPTY_HASH }

#path ⇒ String (readonly)

Return the dataset path

Examples:

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

Returns:

  • (String) —

    the dataset path, without a leading slash



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

option :path, type: Types::Path, default: proc { EMPTY_STRING }

#query_params ⇒ Hash (readonly)

Returns:

  • (Hash) 


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

option :query_params, type: Types::Hash, default: proc { EMPTY_HASH }

#request_handler ⇒ Object (readonly)

Returns:

  • (Object) 


79
 
# File 'lib/rom/http/dataset.rb', line 79

option :request_handler, default: proc { self.class.default_request_handler }

#request_method ⇒ Symbol (readonly)

Returns:

  • (Symbol) 


89
 
# File 'lib/rom/http/dataset.rb', line 89

option :request_method, type: Types::Symbol, default: proc { :get }

#response_handler ⇒ Object (readonly)

Returns:

  • (Object) 


84
 
# File 'lib/rom/http/dataset.rb', line 84

option :response_handler, default: proc { self.class.default_response_handler }

#uri ⇒ URI::HTTP (readonly)

Return the dataset’s URI

Returns:

  • (URI::HTTP) 


124
 
# File 'lib/rom/http/dataset.rb', line 124

option :uri, type: Types::String

Class Method Details

.default_request_handler ⇒ Object

Return configured default request handler

Examples:

class MyDataset < ROM::HTTP::Dataset
  configure do |config|
    config.default_request_handler = MyRequestHandler
  end
end

MyDataset.default_request_handler # MyRequestHandler
MyDataset.new(uri: "http://localhost").request_handler # MyRequestHandler


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

setting :default_request_handler, reader: true

.default_response_handler ⇒ Object

Return configured default response handler

Examples:

class MyDataset < ROM::HTTP::Dataset
  configure do |config|
    config.default_response_handler = MyResponseHandler
  end
end

MyDataset.default_response_handler # MyResponseHandler
MyDataset.new(uri: "http://localhost").response_handler # MyResponseHandler


60
 
# File 'lib/rom/http/dataset.rb', line 60

setting :default_response_handler, reader: true

.query_param_encoder ⇒ Object

Return configured query param encoder

Examples:

class MyDataset < ROM::HTTP::Dataset
  configure do |config|
    config.query_param_encoder = MyParamEncoder
  end
end

MyDataset.query_param_encoder # MyParamEncoder
MyDataset.new(uri: "http://localhost").query_param_encoder # MyParamEncoder


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

setting :query_param_encoder, default: URI.method(:encode_www_form), reader: true

Instance Method Details

#absolute_path ⇒ String

Return the dataset path

Examples:

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

Returns:

  • (String) —

    the dataset path, with leading slash



199
200
201
 
# File 'lib/rom/http/dataset.rb', line 199

def absolute_path
  PATH_SEPARATOR + path
end

#add_body_params(new_body_params) ⇒ Dataset

Return a new dataset with merged request body parameters

Examples:

users = Dataset.new(body_params: { uid: 33 })
users.add_body_params(login: 'jdoe').body_params
# => { uid: 33, :login => 'jdoe' }

Parameters:

  • body_params (Hash) —

    the new request body parameters to add

Returns:



370
371
372
373
 
# File 'lib/rom/http/dataset.rb', line 370

def add_body_params(new_body_params)
  with_options(body_params: ::ROM::HTTP::Transformer[:deep_merge][body_params,
                                                                  new_body_params])
end

#add_header(header, value) ⇒ Dataset

Return a new dataset with additional header

Examples:

users = Dataset.new(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:



235
236
237
 
# File 'lib/rom/http/dataset.rb', line 235

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

#add_query_params(new_query_params) ⇒ Dataset

Return a new dataset with merged request query parameters

Examples:

users = Dataset.new(query_params: { uid: 33 })
users.add_query_params(login: 'jdoe').query_params
# => { uid: 33, :login => 'jdoe' }

Parameters:

  • query_params (Hash) —

    the new request query parameters to add

Returns:



337
338
339
340
 
# File 'lib/rom/http/dataset.rb', line 337

def add_query_params(new_query_params)
  with_options(query_params: ::ROM::HTTP::Transformer[:deep_merge][query_params,
                                                                   new_query_params])
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:



291
292
293
 
# File 'lib/rom/http/dataset.rb', line 291

def append_path(append_path)
  with_path(join_path(options[:path], append_path))
end

#delete ⇒ Array<Hash>

Perform an delete over HTTP Delete

Returns:

  • (Array<Hash>) 


423
424
425
 
# File 'lib/rom/http/dataset.rb', line 423

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

#delete? ⇒ Boolean

Return true if request method is set to :delete

Returns:

  • (Boolean) 


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

def delete?
  request_method.equal?(:delete)
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>) 


383
384
385
386
387
 
# File 'lib/rom/http/dataset.rb', line 383

def each(&block)
  return to_enum unless block_given?

  response.each(&block)
end

#get? ⇒ Boolean

Return true if request method is set to :get

Returns:

  • (Boolean) 


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

def get?
  request_method.equal?(:get)
end

#insert(attributes) ⇒ Array<Hash>

Perform an insert over HTTP Post

Parameters:

  • attributes (Hash) —

    the attributes to insert

Returns:

  • (Array<Hash>) 


396
397
398
399
400
401
 
# File 'lib/rom/http/dataset.rb', line 396

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

#post? ⇒ Boolean

Return true if request method is set to :post

Returns:

  • (Boolean) 


155
156
157
 
# File 'lib/rom/http/dataset.rb', line 155

def post?
  request_method.equal?(:post)
end

#put? ⇒ Boolean

Return true if request method is set to :put

Returns:

  • (Boolean) 


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

def put?
  request_method.equal?(:put)
end

#response ⇒ Array<hash>

Execute the current dataset

Returns:

  • (Array<hash>) 


432
433
434
 
# File 'lib/rom/http/dataset.rb', line 432

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

#update(attributes) ⇒ Array<Hash>

Perform an update over HTTP Put

Parameters:

  • attributes (Hash) —

    the attributes to update

Returns:

  • (Array<Hash>) 


410
411
412
413
414
415
 
# File 'lib/rom/http/dataset.rb', line 410

def update(attributes)
  with_options(
    request_method: :put,
    body_params: attributes
  ).response
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:



261
262
263
 
# File 'lib/rom/http/dataset.rb', line 261

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

#with_body_params(body_params) ⇒ Dataset

Return a new dataset with replaced request body parameters

Examples:

users = Dataset.new(body_params: { uid: 33 })
users.with_body_params(login: 'jdoe').body_params
# => { :login => 'jdoe' }

Parameters:

  • body_params (Hash) —

    the new request body parameters

Returns:



354
355
356
 
# File 'lib/rom/http/dataset.rb', line 354

def with_body_params(body_params)
  with_options(body_params: body_params)
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(headers: { Accept: 'application/json' })
users.with_headers(:'X-Api-Key' => '1234').headers
# => { :'X-Api-Key' => '1234' }

Parameters:

  • headers (Hash) —

    The new headers

Returns:



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

def with_headers(headers)
  with_options(headers: headers)
end

#with_options(opts) ⇒ Dataset

Return a new dataset with additional options

Parameters:

  • opts (Hash) —

    the new options to add

Returns:



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

def with_options(opts)
  __new__(**options.merge(opts))
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:



276
277
278
 
# File 'lib/rom/http/dataset.rb', line 276

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

#with_query_params(query_params) ⇒ Dataset

Return a new dataset with replaced request query parameters

Examples:

users = Dataset.new(query_params: { uid: 33 })
users.with_query_params(login: 'jdoe').query_params
# => { :login => 'jdoe' }

Parameters:

  • query_params (Hash) —

    the new request query parameters

Returns:



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

def with_query_params(query_params)
  with_options(query_params: query_params)
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:



305
306
307
 
# File 'lib/rom/http/dataset.rb', line 305

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