Class: Pod4::NebulousInterface

Inherits:
Interface show all
Defined in:
lib/pod4/nebulous_interface.rb

Overview

An interface to talk to a Nebulous Target.

Each interface can only speak with one target, designated with #set_target.# The developer must also set a unique ID key using #set_id_fld.

The primary challenge here is to map the CRUDL methods (which interfaces contract to implement) to nebulous verbs. The programmer uses #set_verb for this purpose: the first parameter indicates the CRUDL method, the next is the verb name, and the rest are hash keys.

In the case of the #create and #update methods, the list of keys controls which parts of the incoming hash end up in the verb parameters, and in what order. For #update, the list must include the ID key that you gave to #set_id_fld.

Parameters for the #list method similarly constrain how its selection parameter is translated to a nebulous verb parameter string.

Parameters for #read and #delete can be whatever you like, but since the only value passed to read is the ID, the only symbol there should be the same as the one in #set_id_fld.

class CustomerInterface < SwingShift::NebulousInterface
  set_target 'accord'
  set_id_fld :id
  set_verb :read,   'customerread',   :id, '100'
  set_verb :list,   'customerlist',   :name
  set_verb :create, 'customerupdate', 'create', :name, :price
  set_verb :update, 'customerupdate', 'update', :name, :id, :price

  def update(id, name, price)
    super( id, name: name, price: price)
  end
end

In this example both the create and update methods point to the same nebulous verb. Note that only keys which are symbols are translated to the corresponding values in the record or selection hash; anything else is passed literally in the Nebulous parameter string.

When you subclass NebulousInterfce, you may want to override some or all of the CRUDL methods so that your callers can pass specific parameters rather than a hash; the above example demonstrates this.

We assume that the response to the #create message returns the ID as the parameter part of the success verb. If that’s not true, then you will have to override #create and sort this out yourself.

Calls to create, update and delete avoid (for obvious reasons) Nebulous’ Redis cache if present. Read and list use it, but can take an extra options hash to control it, which, of course, Pod4::Model does not know about. If you want to enable a non-cached read in your model, it will need a method something like this:

def read_no_cache
  r = interface.read(@model_id, caching: false)

  if r.empty?
    add_alert(:error, "Record ID '#@model_id' not found on the data source")
  else
    map_to_model(r)
    run_validation(:read)
    @model_status = :okay if @model_status == :empty
  end

  self
rescue Pod4::WeakError
  add_alert(:error, $!)
  self
end

Defined Under Namespace

Classes: Verb

Constant Summary

Constants inherited from Interface

Interface::ACTIONS

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Metaxing

#define_class_method, #metaclass

Constructor Details

#initialize(requestObj = nil) ⇒ NebulousInterface

In normal operation, takes no parameters.

For testing purposes you may pass something here. Whatever it is you pass, it must respond to a ‘send` method, take the same parameters as NebulousStomp::Request.new (that is, a target and a message) and return something that behaves like a NebulousStomp::Request. This method will be called instead of creating a NebulousStomp::Request directly.



180
181
182
183
184
185
186
187
 
# File 'lib/pod4/nebulous_interface.rb', line 180

def initialize(requestObj=nil)
  @request_object  = requestObj # might as well be a reference 
  @response        = nil
  @response_status = nil
  @id_fld          = self.class.id_fld

  self.class.validate_params
end

Instance Attribute Details

#id_fld ⇒ Object (readonly)

Returns the value of attribute id_fld.



77
78
79
 
# File 'lib/pod4/nebulous_interface.rb', line 77

def id_fld
  @id_fld
end

#response ⇒ Object (readonly)

The NebulousStomp Message object holding the response from the last message sent, or, nil.



80
81
82
 
# File 'lib/pod4/nebulous_interface.rb', line 80

def response
  @response
end

#response_status ⇒ Object (readonly)

The status of the response from the last message:

  • nil - we didn’t send a request yet

  • :off - Nebulous is turned off, so nothing happened

  • :timeout we sent the message but timed out waiting for a response

  • :verberror - we got an error verb in response

  • :verbsuccess - we got a success verb in response

  • :response - we got some response that doesn’t follow The Protocol

NB: if we got an exception sending the message, we raised it on the caller, so there is no status for that.



92
93
94
 
# File 'lib/pod4/nebulous_interface.rb', line 92

def response_status
  @response_status
end

Class Method Details

.id_fld ⇒ Object

Raises:



142
143
144
 
# File 'lib/pod4/nebulous_interface.rb', line 142

def id_fld
  raise Pod4Error, "You need to use set_id_fld"
end

.set_id_fld(idFld) ⇒ Object

Set the name of the ID parameter (needs to be in the CRUD verbs param list)



138
139
140
 
# File 'lib/pod4/nebulous_interface.rb', line 138

def set_id_fld(idFld)
  define_class_method(:id_fld) {idFld}
end

.set_target(target) ⇒ Object

Set the name of the Nebulous target in the interface definition

a reference to the interface object.



127
128
129
 
# File 'lib/pod4/nebulous_interface.rb', line 127

def set_target(target)
  define_class_method(:target) {target.to_s}
end

.set_verb(action, verb, *paramKeys) ⇒ Object

Set a verb.

  • action - must be one of CRUDL

  • verb - the name of the verb

  • parameters - array of symbols to order the hash passed to create, etc

Raises:

  • (ArgumentError) 


110
111
112
113
114
115
116
117
 
# File 'lib/pod4/nebulous_interface.rb', line 110

def set_verb(action, verb, *paramKeys)
  raise ArgumentError, "Bad action" unless Interface::ACTIONS.include? action

  v = verbs.dup
  v[action] = Verb.new( verb, paramKeys.flatten )

  define_class_method(:verbs) {v}
end

.target ⇒ Object

Raises:



131
132
133
 
# File 'lib/pod4/nebulous_interface.rb', line 131

def target
  raise Pod4Error, "You need to use set_target on your interface"
end

.validate_params ⇒ Object

Make sure all of the above is consistent

Raises:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/pod4/nebulous_interface.rb', line 150

def validate_params
  raise Pod4Error, "You need to use set_verb" if verbs == {}

  %i|create read update delete|.each do |action|
    raise Pod4Error, "set_verb #{action} is missing a parameter list" \
      if verbs[action] && !verbs[action].params == []

  end

  %i|read update delete|.each do |action|
    raise Pod4Error, "#{action} verb doesn't have an #{id_fld} key" \
      if verbs[action] && !verbs[action].params.include?(id_fld)

  end

end

.verbs ⇒ Object 



119
 
# File 'lib/pod4/nebulous_interface.rb', line 119

def verbs; {}; end

Instance Method Details

#clearing_cache ⇒ Object

Bonus method: chain this method before a CRUDL method to clear the cache for that parameter string:

@interface.clearing_cache.read(14)

Note that there is no guarantee that the request that clears the cache is actually the one you chain after (if multiple model instances are running against the same interface instance) but for the instance that calls ‘clearing_cache`, this is not important.



298
299
300
301
 
# File 'lib/pod4/nebulous_interface.rb', line 298

def clearing_cache
  @clear_cache = true
  self
end

#create(record) ⇒ Object

Pass a parameter string or an array as the record. returns the ID. We assume that the response to the create message returns the ID as the parameter part of the success verb. If that’s not true, then you will have to override #create and sort this out yourself.



224
225
226
227
228
229
230
231
232
 
# File 'lib/pod4/nebulous_interface.rb', line 224

def create(record)
  raise ArgumentError, 'create takes a Hash or an Octothorpe' unless hashy?(record)

  send_message( verb_for(:create), param_string(:create, record), false )
  @response.params

rescue => e
  handle_error(e)
end

#delete(id) ⇒ Object

Given an ID, delete the record. Return self.

The actual parameters passed to nebulous depend on how you #set_verb

Raises:

  • (ArgumentError) 


277
278
279
280
281
282
283
284
285
 
# File 'lib/pod4/nebulous_interface.rb', line 277

def delete(id)
  raise ArgumentError, 'You must pass an ID to delete' unless id

  send_message( verb_for(:delete), 
                param_string(:delete, nil, id), 
                false )

  self
end

#list(selection = nil, opts = {}) ⇒ Object

Pass a parameter string or array (which will be taken as the literal Nebulous parameter) or a Hash or Octothorpe (which will be interpreted as per your list of keys set in add_verb :list).

Returns an array of Octothorpes, or an empty array if the responder could not make any records out of our message.

Note that the ‘opts` hash is not part of the protocol supported by Pod4::Model. If you want to make use of it, you will have to write your own method for that. Supported keys:

  • caching: true if you want to use redis caching (defaults to true)



203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/pod4/nebulous_interface.rb', line 203

def list(selection=nil, opts={})
  sel = 
    case selection
      when Array, Hash, Octothorpe then param_string(:list, selection)
      else selection
    end

  caching = opts[:caching].nil? ? true : !!opts[:caching]
  send_message( verb_for(:list), sel, caching )
  @response.body.is_a?(Array) ? @response.body.map{|e| Octothorpe.new e} : []

rescue => e
  handle_error(e)
end

#read(id, opts = {}) ⇒ Object

Given the id, return an Octothorpe of the record.

The actual parameters passed to nebulous depend on how you #set_verb

Note that the ‘opts` hash is not part of the protocol supported by Pod4::Model. If you want to make use of it, you will have to write your own method for that. Supported keys:

  • caching: true if you want to use redis caching (defaults to true)

Raises:

  • (ArgumentError) 


245
246
247
248
249
250
251
252
253
254
 
# File 'lib/pod4/nebulous_interface.rb', line 245

def read(id, opts={})
  raise ArgumentError, 'You must pass an ID to read' unless id

  caching = opts[:caching].nil? ? true : !!opts[:caching]
  send_message( verb_for(:read), 
                param_string(:read, nil, id), 
                caching )

  Octothorpe.new( @response.body.is_a?(Hash) ? @response.body : {} )
end

#send_message(verb, paramStr, with_cache = true) ⇒ Object

Bonus method: send an arbitrary Nebulous message to the target and return the response object.

We don’t trap errors here - see #handle_error - but we raise extra ones if we think things look fishy.



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/pod4/nebulous_interface.rb', line 310

def send_message(verb, paramStr, with_cache=true)
  unless NebulousStomp.on? 
    @response_status = :off
    raise Pod4::DatabaseError, "Nebulous is turned off!"
  end

  Pod4.logger.debug(__FILE__) do
    "Sending v:#{verb} p:#{paramStr} c?: #{with_cache}"
  end

  @response = send_message_helper(verb, paramStr, with_cache)

  raise Pod4::DatabaseError, "Null response" if @response.nil?

  @response_status = 
    case @response.verb
      when 'error'   then :verberror
      when 'success' then :verbsuccess
      else                :response
    end

  raise Pod4::WeakError, "Nebulous returned an error verb: #{@response.description}" \
    if @response_status == :verberror

  self

rescue => err
  handle_error(err)
end

#update(id, record) ⇒ Object

Given an id an a record (Octothorpe or Hash), update the record. Returns self.

Raises:

  • (ArgumentError) 


260
261
262
263
264
265
266
267
268
269
 
# File 'lib/pod4/nebulous_interface.rb', line 260

def update(id, record)
  raise ArgumentError, 'You must pass an ID to update' unless id
  raise ArgumentError, 'update record takes a Hash or an Octothorpe' unless hashy?(record)

  send_message( verb_for(:update), 
                param_string(:update, record, id), 
                false )

  self
end