class Hoodoo::Services::Interface::ToListDSL
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.
Public Class Methods
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.
# 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
Public Instance Methods
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 ]
# 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
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.
# 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
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.
# 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
As search
, but for filtering.
keys
-
Array of permitted filter keys, as symbols or strings. The order of array entries is arbitrary.
# File lib/hoodoo/services/services/interface.rb, line 284 def filter( *keys ) @tl.send( :filter=, keys.map { | item | item.to_s } ) end
Specify the page size (limit) for lists.
limit
-
Page size (integer).
Example:
limit 100
# 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
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
# File lib/hoodoo/services/services/interface.rb, line 257 def search( *keys ) @tl.send( :search=, keys.map { | item | item.to_s } ) end
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 ]
# 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