Class: QBFC::Request

Inherits:
Object
  • Object
show all
Defined in:
lib/qbfc/request.rb

Overview

A QBFC::Request handles creating and sending a Request, including creating the RequestSet. Most often, RubyQBFC classes create and execute the Request internally, however, the Base.find, for example, accepts a QBFC::Request object as an argument if greater control is needed.

The WIN32OLE Request object is wrapped in OLEWrapper, so Ruby-esque methods can be used.

req = QBFC::Request.new(qb_session, "CustomerQuery").
  or_customer_list_query.customer_list_filter.max_returned = 2
puts req.response

Instance Method Summary collapse

Constructor Details

#initialize(sess, request_type, country = 'US', major_version = 6, minor_version = 0) ⇒ Request

session is a QBFC::Session object (or a Session object not created through Ruby QBFC) request_type is the name of the request, not including trailing ‘Rq’, e.g. ‘CustomerQuery’, ‘CustomerMod’



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/qbfc/request.rb', line 18

def initialize(sess, request_type, country = 'US', major_version = 6, minor_version = 0)
  @sess = sess
  
  begin
    @request_set = sess.CreateMsgSetRequest(country, major_version, minor_version)
  rescue WIN32OLERuntimeError => error
    if error.to_s =~ /error code:8004030A/
      raise QBFC::QBXMLVersionError, "Unsupported qbXML version"
    else
      raise
    end
  end
  
  begin
    @name = request_type
    @request = @request_set.send("Append#{request_type}Rq")
  rescue WIN32OLERuntimeError => error
    if error.to_s =~ /error code:0x80020006/
      raise QBFC::UnknownRequestError, "Unknown request name '#{request_type}'"
    else
      raise
    end
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(symbol, *params) ⇒ Object

Send missing methods to @ole_object (OLEWrapper)



268
269
270
 
# File 'lib/qbfc/request.rb', line 268

def method_missing(symbol, *params) #:nodoc:
  @request.qbfc_method_missing(@sess, symbol, *params)
end

Instance Method Details

#add_includes(inc) ⇒ Object

add_includes accepts an Array of elements to include in the return of the Request. The array may include either or both of elements that are additional to normal returns (such as Line Items, Linked Transactions) or elements that are normally included (to be added to the IncludeRetElementList).

If elements are given that would be added to IncludeRetElementList, this limits the elements returned to only those included in the array.

Another option is to give :all as the argument, which will always return as many elements as possible.

add_includes is typically called by #apply_options, typically called from Element.find, as seen in the examples below:

@sess.checks.find(:all, :include => [:linked_txns]) -> Include linked transactions
@sess.checks.find(:all, :include => [:txn_id]) -> Include +only+ TxnID
@sess.checks.find(:all, :include => :all) ->
  Includes all elements, including LinkedTxns and LineItems.



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/qbfc/request.rb', line 173

def add_includes(inc)
  return if inc.nil?
  
  inc = [inc] if (!inc.respond_to?(:each) || inc.kind_of?(String))
  
  if inc.include?(:all)
    ole_methods.each do |m|
      m = m.to_s
      if m =~ /\AInclude/ && m != 'IncludeRetElementList'
        @request.__send__("#{m.underscore}=", true)
      end
    end
    return
  end
  
  inc.each do |item|
    cam_item = item.to_s.camelize.gsub(/Id/, "ID")
    if @request.respond_to_ole?("Include#{cam_item}")
      @request.__send__("include_#{item}=", true)
    else
      @request.IncludeRetElementList.Add(cam_item)
    end
  end
end

#add_limit(limit) ⇒ Object

Set MaxReturned to limit the number of records returned.



150
151
152
 
# File 'lib/qbfc/request.rb', line 150

def add_limit(limit)
  filter.max_returned = limit if limit
end

#add_owner_ids(ids) ⇒ Object

Add one or more OwnerIDs to the Request. Used in retrieving custom fields (aka private data extensions). Argument should be a single ID or an Array of IDs.



140
141
142
143
144
145
146
147
 
# File 'lib/qbfc/request.rb', line 140

def add_owner_ids(ids)
  return if ids.nil?
  
  ids = [ids] unless ids.respond_to?(:each)
  ids.each do | id |
    @request.OwnerIDList.Add(id)
  end
end

#apply_options(options) ⇒ Object

Applies options from a Hash. This method is generally used by find methods (see Element.find for details)



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/qbfc/request.rb', line 87

def apply_options(options)      
  if options.kind_of? Hash
    conditions = options.delete(:conditions) || {}
    
    conditions.each do | c_name, c_value |
      c_name = c_name.to_s
      
      case c_name
      when /list\Z/i
        # List filters
        list = query.__send__(c_name.camelize)
        c_value = [c_value] unless c_value.kind_of?(Array)
        c_value.each { |i| list.Add(i) }
      when /range\Z/i
        # Range filters
        c_value = parse_range_value(c_value)
        range_filter = filter_for(c_name)
        range_name = c_name.match(/(.*)_range\Z/i)[1]
        if range_name == 'modified_date'
          # Modified Date Range use the IQBDateTimeType which requires a\
          # boolean 'asDateOnly' value.
          range_filter.__send__("from_#{range_name}=", c_value.first, true) if c_value.first
          range_filter.__send__("to_#{range_name}=", c_value.last, true) if c_value.last
        else
          range_filter.__send__("from_#{range_name}=", c_value.first) if c_value.first
          range_filter.__send__("to_#{range_name}=", c_value.last) if c_value.last
        end
      when /status\Z/i
        # Status filters
        filter.__send__("#{c_name}=", c_value)
      else
        # Reference filters - Only using FullNameList for now
        ref_filter = filter_for(c_name)
        c_value = [c_value] unless c_value.respond_to?(:each)
        c_value.each do | val |
          ref_filter.FullNameList.Add(val)
        end
      end
    end
      
    add_owner_ids(options.delete(:owner_id))
    add_limit(options.delete(:limit))
    add_includes(options.delete(:include))

    options.each do |key, value|
      self.send(key.to_s.camelize).SetValue(value)
    end
  end
end

#filter ⇒ Object

Get the *Filter object of the given Request For example, the ListFilter



69
70
71
72
73
74
75
 
# File 'lib/qbfc/request.rb', line 69

def filter
  q = self.query
  return nil if q.nil?
  filter_name = q.ole_methods.detect{|m| m.to_s =~ /Filter\Z/}
  return nil if filter_name.nil?
  q.send(filter_name.to_s.to_sym)
end

#filter_available? ⇒ Boolean

Returns where the filter is available for use. That is, that none of the query options other than filter have been used

Returns:

  • (Boolean) 


79
80
81
82
83
 
# File 'lib/qbfc/request.rb', line 79

def filter_available?
  # -1 = unused, 2 = Filter used
  self.query.ole_object.ortype == -1 ||
    self.query.ole_object.ortype == 2
end

#for_report? ⇒ Boolean

Is this Query for a Report? The ‘conditions’ are treated differently

Returns:

  • (Boolean) 


55
56
57
 
# File 'lib/qbfc/request.rb', line 55

def for_report?
  @name =~ /Report$/
end

#ole_methods ⇒ Object

Return Array of ole_methods for request WIN32OLE object. This is mostly useful for debugging.



274
275
276
 
# File 'lib/qbfc/request.rb', line 274

def ole_methods
  @request.ole_methods
end

#ole_object ⇒ Object

Return actual WIN32OLE object



291
292
293
 
# File 'lib/qbfc/request.rb', line 291

def ole_object
  @request.ole_object
end

#query ⇒ Object

Get the OR*Query object of the given Request For example, the ORListQuery



61
62
63
64
65
 
# File 'lib/qbfc/request.rb', line 61

def query
  query_name = @request.ole_methods.detect{|m| m.to_s =~ /Query\Z/}
  return nil if query_name.nil?
  @request.send(query_name.to_s.to_sym)
end

#response ⇒ Object

Submit the Request and return the response Detail, wrapped in OLEWrapper (unless nil). The response does not include any MsgSetResponse attributes.



50
51
52
 
# File 'lib/qbfc/request.rb', line 50

def response
  submit.ResponseList.GetAt(0).Detail
end

#response_xml ⇒ Object

Submit Request and return full response as XML. This is mostly useful for debugging.



286
287
288
 
# File 'lib/qbfc/request.rb', line 286

def response_xml
  @sess.DoRequests(@request_set).ToXMLString
end

#submit ⇒ Object

Submit the requests. This returns the full (not wrapped) response object.



44
45
46
 
# File 'lib/qbfc/request.rb', line 44

def submit
  @sess.DoRequests(@request_set)
end

#to_xml ⇒ Object

Return XML for the request WIN32OLE object. This is mostly useful for debugging.



280
281
282
 
# File 'lib/qbfc/request.rb', line 280

def to_xml
  @request_set.ToXMLString
end