Class: Hoodoo::Services::Interface::ToListDSL

Inherits:
Object
  • Object
show all
Defined in:
lib/hoodoo/services/services/interface.rb

Overview

Implementation of the DSL that’s written inside a block passed to Hoodoo::Services::Interface#to_list. This is an internal implementation class. Instantiate with a Hoodoo::Services::Interface::ToList instance, the data in which is updated as the DSL methods run.

Instance Method Summary collapse

Constructor Details

#initialize(hoodoo_interface_to_list_instance, &block) ⇒ ToListDSL

Initialize an instance and run the DSL methods.

hoodoo_interface_to_list_instance

Instance of Hoodoo::Services::Interface::ToList to update with data from DSL method calls.

&block

Block of code that makes calls to the DSL herein.

On exit, the DSL is run and the Hoodoo::Services::Interface::ToList has been updated.



159
160
161
162
163
164
165
166
167
 
# File 'lib/hoodoo/services/services/interface.rb', line 159

def initialize( hoodoo_interface_to_list_instance, &block )
  @tl = hoodoo_interface_to_list_instance # Shorthand!

  unless @tl.instance_of?( Hoodoo::Services::Interface::ToList )
    raise "Hoodoo::Services::Interface::ToListDSL\#initialize requires a Hoodoo::Services::Interface::ToList instance - got '#{ @tl.class }'"
  end

  self.instance_eval( &block )
end

Instance Method Details

#default(sort_key) ⇒ Object

Used in conjunction with #sort. Specifies that a sort key should be the default sort order for the interface.

Example - add sort key ‘code’ with directions :asc and :desc, plus sort key :member which only supports direction :asc. Say that ‘code’ is to be the default sort order.

sort default( :code ) => [ :asc, :desc ],
     :member          => [ :asc ]



231
232
233
234
235
236
237
238
 
# File 'lib/hoodoo/services/services/interface.rb', line 231

def default( sort_key )
  unless sort_key.is_a?( ::String ) || sort_key.is_a?( ::Symbol )
    raise "Hoodoo::Services::Interface::ToListDSL\#default requires a String or Symbol - got '#{ sort_key.class }'"
  end

  @tl.send( :default_sort_key=, sort_key.to_s )
  return sort_key
end

#do_not_filter(*keys) ⇒ Object

As #do_not_search, but for default Hoodoo framework exclusions.

keys

Array of prohibited framework filter keys, as symbols or strings. The order of array entries is arbitrary.



293
294
295
296
297
298
299
300
301
 
# File 'lib/hoodoo/services/services/interface.rb', line 293

def do_not_filter( *keys )
  @tl.send( :do_not_filter=, keys.map { | item | item.to_s } )

  unknown = @tl.do_not_filter() - Hoodoo::Services::Middleware::FRAMEWORK_QUERY_DATA.keys

  unless unknown.empty?
    raise "Hoodoo::Services::Interface::ToListDSL\#do_not_filter was given one or more unknown keys: #{ unknown.join( ', ' ) }"
  end
end

#do_not_search(*keys) ⇒ Object

Similar to #search, but for default Hoodoo framework exclusions. The Hoodoo::Services::Middleware FRAMEWORK_QUERY_DATA array lists the known framework keys for a given Hoodoo version. An exception is raised if an attempt is made to exclude unknown keys.

keys

Array of prohibited framework search keys, as symbols or strings. The order of array entries is arbitrary.



269
270
271
272
273
274
275
276
277
 
# File 'lib/hoodoo/services/services/interface.rb', line 269

def do_not_search( *keys )
  @tl.send( :do_not_search=, keys.map { | item | item.to_s } )

  unknown = @tl.do_not_search() - Hoodoo::Services::Middleware::FRAMEWORK_QUERY_DATA.keys

  unless unknown.empty?
    raise "Hoodoo::Services::Interface::ToListDSL\#do_not_search was given one or more unknown keys: #{ unknown.join( ', ' ) }"
  end
end

#filter(*keys) ⇒ Object

As #search, but for filtering.

keys

Array of permitted filter keys, as symbols or strings. The order of array entries is arbitrary.



284
285
286
 
# File 'lib/hoodoo/services/services/interface.rb', line 284

def filter( *keys )
  @tl.send( :filter=, keys.map { | item | item.to_s } )
end

#limit(limit) ⇒ Object

Specify the page size (limit) for lists.

limit

Page size (integer).

Example:

limit 100



177
178
179
180
181
182
183
 
# File 'lib/hoodoo/services/services/interface.rb', line 177

def limit( limit )
  unless limit.is_a?( ::Integer )
    raise "Hoodoo::Services::Interface::ToListDSL\#limit requires an Integer - got '#{ limit.class }'"
  end

  @tl.send( :limit=, limit )
end

#search(*keys) ⇒ Object

Specify supported search keys in an array. The middleware will make sure the interface implementation is only called with search keys in that list. If a client attempts a search on an unsupported key, their request will be rejected by the middleware.

If a service wants to do its own search validation, it should not list call here. Note also that only the keys are specified and validated; value escaping and validation, if necessary, is up to the service implementation.

keys

Array of permitted search keys, as symbols or strings. The order of array entries is arbitrary.

Example - allow searches specifying first_name and last_name keys:

search :first_name, :last_name



257
258
259
 
# File 'lib/hoodoo/services/services/interface.rb', line 257

def search( *keys )
  @tl.send( :search=, keys.map { | item | item.to_s } )
end

#sort(sort) ⇒ Object

Specify extra sort keys and orders that add with whatever platform common defaults are already in place.

sort

Hash of sort keys, with values that are an array of supported sort directions. The first array entry is used as the default direction if no direction is specified in the client caller’s query string. Use strings or symbols.

To specify that a sort key should be the new default for the interface in question, wrap it in a call to the #default DSL method.

Example - add sort key ‘code’ with directions :asc and :desc, plus sort key :member which only supports direction :asc.

sort :code   => [ :asc, :desc ],
     :member => [ :asc ]



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/hoodoo/services/services/interface.rb', line 203

def sort( sort )
  unless sort.is_a?( ::Hash )
    raise "Hoodoo::Services::Interface::ToListDSL\#sort requires a Hash - got '#{ sort.class }'"
  end

  # Convert Hash keys to Strings and Arrays to Sets of Strings too.

  sort = sort.inject( {} ) do | memo, ( k, v ) |
    memo[ k.to_s ] = Set.new( v.map do | entry |
      entry.to_s
    end )
    memo
  end

  merged = @tl.sort().merge( sort )
  @tl.send( :sort=, merged )
end