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.

Finally, note that all values are returned as strings; there is no typecasting. This is a given limitation for Nebulous as a whole.

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.



161
162
163
164
165
166
167
168
 
# File 'lib/pod4/nebulous_interface.rb', line 161

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.



58
59
60
 
# File 'lib/pod4/nebulous_interface.rb', line 58

def id_fld
  @id_fld
end

#response ⇒ Object (readonly)

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



61
62
63
 
# File 'lib/pod4/nebulous_interface.rb', line 61

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.



73
74
75
 
# File 'lib/pod4/nebulous_interface.rb', line 73

def response_status
  @response_status
end

Class Method Details

.id_fld ⇒ Object

Raises:



123
124
125
 
# File 'lib/pod4/nebulous_interface.rb', line 123

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)



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

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.



108
109
110
 
# File 'lib/pod4/nebulous_interface.rb', line 108

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) 


91
92
93
94
95
96
97
98
 
# File 'lib/pod4/nebulous_interface.rb', line 91

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:



112
113
114
 
# File 'lib/pod4/nebulous_interface.rb', line 112

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:



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/pod4/nebulous_interface.rb', line 131

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 



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

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)



261
262
263
264
 
# File 'lib/pod4/nebulous_interface.rb', line 261

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.



199
200
201
202
203
204
205
206
207
 
# File 'lib/pod4/nebulous_interface.rb', line 199

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

  send_message( verb_for(:create), param_string(:create, record) )
  @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) 


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

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



179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/pod4/nebulous_interface.rb', line 179

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

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

rescue => e
  handle_error(e)
end

#read(id) ⇒ Object

Given the id, return an Octothorpe of the record.

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

Raises:

  • (ArgumentError) 


215
216
217
218
219
220
221
 
# File 'lib/pod4/nebulous_interface.rb', line 215

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

  send_message( verb_for(:read), param_string(:read, nil, id) )

  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.



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/pod4/nebulous_interface.rb', line 273

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::CantContinue, "Nebulous returned an error verb" 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) 


227
228
229
230
231
232
233
234
235
236
 
# File 'lib/pod4/nebulous_interface.rb', line 227

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