Class: SoftLayer::APIParameterFilter

Inherits:
Object
  • Object
show all
Defined in:
lib/softlayer/APIParameterFilter.rb

Overview

class to be created with the service as its target.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target, starting_parameters = nil) ⇒ APIParameterFilter

Construct a filter with the given target (and starting parameters if given)



41
42
43
44
 
# File 'lib/softlayer/APIParameterFilter.rb', line 41

def initialize(target, starting_parameters = nil)
  @target = target
  @parameters = starting_parameters || {}
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_name, *args, &block) ⇒ Object

This allows the filters to be used at the end of a long chain of calls that ends at a service. It forwards the message and the parameters to the target of this method (presumably a Service instance)



190
191
192
193
194
195
196
197
198
 
# File 'lib/softlayer/APIParameterFilter.rb', line 190

def method_missing(method_name, *args, &block)
  puts "SoftLayer::APIParameterFilter#method_missing called #{method_name}, #{args.inspect}" if $DEBUG

  if(!block && method_name.to_s.match(/[[:alnum:]]+/))
    @target.call_softlayer_api_with_params(method_name, self, args)
  else
    super
  end
end

Instance Attribute Details

#parameters ⇒ Object (readonly)

The collected parameters represented by this filter. These parameters are passed along to the target when method_missing is forwarding a message.



38
39
40
 
# File 'lib/softlayer/APIParameterFilter.rb', line 38

def parameters
  @parameters
end

#target ⇒ Object (readonly)

The target of this API Parameter Filter. Should the filter receive an unknown method call, method_missing will forward the call on to the target. This is supposed to be an instance of the SoftLayer::Service class.



33
34
35
 
# File 'lib/softlayer/APIParameterFilter.rb', line 33

def target
  @target
end

Instance Method Details

#object_filter(filter) ⇒ Object

Adds an object_filter to the result. An Object Filter allows you to specify criteria which are used to filter the results returned by the server.

Raises:

  • (ArgumentError) 


114
115
116
117
118
119
120
 
# File 'lib/softlayer/APIParameterFilter.rb', line 114

def object_filter(filter)
  raise ArgumentError, "object_filter expects an instance of SoftLayer::ObjectFilter" if filter.nil? || !filter.kind_of?(SoftLayer::ObjectFilter)

  # we create a new object in case the user wants to store off the
  # filter chain and reuse it later
  APIParameterFilter.new(self.target, @parameters.merge({:object_filter => filter}));
end

#object_mask(*args) ⇒ Object

Use this as part of a method call chain to add an object mask to the request. The arguments to object mask should be well formed Extended Object Mask strings:

ticket_service.object_mask(
  "mask[createDate, modifyDate]",
  "mask(SoftLayer_Some_Type).aProperty").getObject

The object_mask becomes part of the request sent to the server The object mask strings are parsed into ObjectMaskProperty trees and those trees are stored with the parameters. The trees are converted to strings immediately before the mask is used in a call

Raises:

  • (ArgumentError) 


80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/softlayer/APIParameterFilter.rb', line 80

def object_mask(*args)
  raise ArgumentError, "object_mask expects object mask strings" if args.empty? || (1 == args.count && !args[0])
  raise ArgumentError, "object_mask expects strings" if args.find{ |arg| !arg.kind_of?(String) }

  mask_parser = ObjectMaskParser.new()
  object_masks = args.collect { |mask_string| mask_parser.parse(mask_string)}.flatten
  object_mask = (@parameters[:object_mask] || []) + object_masks

  # we create a new object in case the user wants to store off the
  # filter chain and reuse it later
  APIParameterFilter.new(self.target, @parameters.merge({ :object_mask => object_mask }));
end

#object_with_id(value) ⇒ Object

Adds an API filter that narrows the scope of a call to an object with a particular ID. For example, if you want to get the ticket with an ID of 12345 from the ticket service you might use

ticket_service.object_with_id(12345).getObject



60
61
62
63
64
 
# File 'lib/softlayer/APIParameterFilter.rb', line 60

def object_with_id(value)
  # we create a new object in case the user wants to store off the
  # filter chain and reuse it later
  APIParameterFilter.new(self.target, @parameters.merge({ :server_object_id => value }))
end

#result_limit(offset, limit) ⇒ Object

Adds a result limit which helps you page through a long list of entities

The offset is the index of the first item you wish to have returned The limit describes how many items you wish the call to return.

For example, if you wanted to get five open tickets from the account starting with the tenth item in the open tickets list you might call

.result_limit(10, 5).getOpenTickets



104
105
106
107
108
 
# File 'lib/softlayer/APIParameterFilter.rb', line 104

def result_limit(offset, limit)
  # we create a new object in case the user wants to store off the
  # filter chain and reuse it later
  APIParameterFilter.new(self.target, @parameters.merge({ :result_offset => offset, :result_limit => limit }))
end

#server_object_filter ⇒ Object

A utility method that returns the object filter (if any) stored with this filter.



182
183
184
 
# File 'lib/softlayer/APIParameterFilter.rb', line 182

def server_object_filter
  self.parameters[:object_filter].to_h if self.parameters.has_key?(:object_filter)
end

#server_object_id ⇒ Object

A utility method that returns the server object ID (if any) stored in this parameter set.



125
126
127
 
# File 'lib/softlayer/APIParameterFilter.rb', line 125

def server_object_id
  self.parameters[:server_object_id]
end

#server_object_mask ⇒ Object

A utility method that returns the object mask (if any) stored in this parameter set.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/softlayer/APIParameterFilter.rb', line 132

def server_object_mask
  if parameters[:object_mask] && !parameters[:object_mask].empty?

    # Reduce the masks found in this object to a minimal set
    #
    # If you pass the API a mask that asks for the same property twice (within
    # the same type scope), the API treats it as an error (and throws an exception)
    #
    # We get around that by parsing the various masks that have been given to us
    # merging their properties where possible, thereby removing the duplicates
    # from the mask that actually gets passed to the server. As a side benefit,
    # the mask we send to the server will be streamlined; without too many extraneous
    # characters
    reduced_masks = parameters[:object_mask].inject([]) do |merged_masks, object_mask|
      mergeable_mask = merged_masks.find { |mask| mask.can_merge_with? object_mask }
      if mergeable_mask
        mergeable_mask.merge object_mask
      else
        merged_masks.push object_mask
      end

      merged_masks
    end

    if reduced_masks.count == 1
      reduced_masks[0].to_s
    else
      "[#{reduced_masks.collect{|mask| mask.to_s}.join(',')}]"
    end
  else
    nil
  end
end

#server_result_limit ⇒ Object

A utility method that returns the starting index of the result limit (if any) stored in this parameter set.



169
170
171
 
# File 'lib/softlayer/APIParameterFilter.rb', line 169

def server_result_limit
  self.parameters[:result_limit]
end

#server_result_offset ⇒ Object

A utility method that returns the starting index of the result limit offset (if any) stored in this parameter set.



176
177
178
 
# File 'lib/softlayer/APIParameterFilter.rb', line 176

def server_result_offset
  self.parameters[:result_offset]
end

#service_name ⇒ Object

API Parameter filters will call through to a particular service but that service is defined by their target



49
50
51
 
# File 'lib/softlayer/APIParameterFilter.rb', line 49

def service_name
  return @target.service_name
end