Class: Handsoap::Service

Inherits:
Object
  • Object
show all
Defined in:
lib/handsoap/service.rb,
lib/handsoap/service.rb

Constant Summary collapse

@@logger = 
nil
@@instance = 
{}

Class Method Summary collapse

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args) ⇒ Object 



293
294
295
296
297
298
299
300
 
# File 'lib/handsoap/service.rb', line 293

def method_missing(method, *args)
  action = self.class.get_mapping(method)
  if action
    invoke(action, *args)
  else
    super
  end
end

Class Method Details

.endpoint(args = {}) ⇒ Object 



94
95
96
97
 
# File 'lib/handsoap/service.rb', line 94

def self.endpoint(args = {})
  @protocol_version = args[:version] || raise("Missing option :version")
  @uri = args[:uri] || raise("Missing option :uri")
end

.envelope_namespace ⇒ Object 



98
99
100
101
102
103
 
# File 'lib/handsoap/service.rb', line 98

def self.envelope_namespace
  if SOAP_NAMESPACE[@protocol_version].nil?
    raise "Unknown protocol version '#{@protocol_version.inspect}'"
  end
  SOAP_NAMESPACE[@protocol_version]
end

.fire_on_create_document(doc) ⇒ Object 



307
308
309
310
311
 
# File 'lib/handsoap/service.rb', line 307

def self.fire_on_create_document(doc)
  if @create_document_callback
    @create_document_callback.call doc
  end
end

.get_mapping(name) ⇒ Object 



290
291
292
 
# File 'lib/handsoap/service.rb', line 290

def self.get_mapping(name)
  @mapping[name] if @mapping
end

.instance ⇒ Object 



111
112
113
 
# File 'lib/handsoap/service.rb', line 111

def self.instance
  @@instance[self.to_s] ||= self.new
end

.logger=(io) ⇒ Object 



91
92
93
 
# File 'lib/handsoap/service.rb', line 91

def self.logger=(io)
  @@logger = io
end

.map_method(mapping) ⇒ Object

Registers a simple method mapping without any arguments and no parsing of response.

This is deprecated



284
285
286
287
288
289
 
# File 'lib/handsoap/service.rb', line 284

def self.map_method(mapping)
  if @mapping.nil?
    @mapping = {}
  end
  @mapping.merge! mapping
end

.method_missing(method, *args) ⇒ Object 



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

def self.method_missing(method, *args)
  if instance.respond_to?(method)
    instance.__send__ method, *args
  else
    super
  end
end

.on_create_document(&block) ⇒ Object

Registers a block to call when a request document is created.

This is deprecated, in favour of #on_create_document



304
305
306
 
# File 'lib/handsoap/service.rb', line 304

def self.on_create_document(&block)
  @create_document_callback = block
end

.request_content_type ⇒ Object 



104
105
106
 
# File 'lib/handsoap/service.rb', line 104

def self.request_content_type
  @protocol_version == 1 ? "text/xml" : "application/soap+xml"
end

.uri ⇒ Object 



107
108
109
 
# File 'lib/handsoap/service.rb', line 107

def self.uri
  @uri
end

Instance Method Details

#debug(message = nil) ⇒ Object

:nodoc:



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/handsoap/service.rb', line 184

def debug(message = nil) #:nodoc:
  if @@logger
    if message
      @@logger.puts(message)
    end
    if block_given?
      yield @@logger
    end
  end
end

#dispatch(doc, action) ⇒ Object

Send document and parses the response into a Response



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/handsoap/service.rb', line 209

def dispatch(doc, action)
  on_before_dispatch
  headers = {
    "Content-Type" => "#{self.class.request_content_type};charset=UTF-8"
  }
  headers["SOAPAction"] = action unless action.nil?
  body = doc.to_s
  debug do |logger|
    logger.puts "==============="
    logger.puts "--- Request ---"
    logger.puts "URI: %s" % [self.class.uri]
    logger.puts headers.map { |key,value| key + ": " + value }.join("\n")
    logger.puts "---"
    logger.puts body
  end
  response = send_http_request(self.class.uri, body, headers)
  debug do |logger|
    logger.puts "--- Response ---"
    logger.puts "HTTP Status: %s" % [response[:status]]
    logger.puts "Content-Type: %s" % [response[:content_type]]
    logger.puts "---"
    logger.puts Handsoap.pretty_format_envelope(response[:body])
  end
  soap_response = Response.new(response[:body], self.class.envelope_namespace)
  if soap_response.fault?
    return on_fault(soap_response.fault)
  end
  if response[:status] >= 300
    return on_http_error(response[:status], response[:body])
  end
  unless soap_response.document?
    return on_missing_document(soap_response)
  end
  on_response_document(soap_response.document)
  return soap_response
end

#invoke(action, options = { :soap_action => :auto }, &block) ⇒ Object

Creates an XML document and sends it over HTTP.

action is the QName of the rootnode of the envelope.

options currently takes one option :soap_action, which can be one of:

:auto sends a SOAPAction http header, deduced from the action name. (This is the default)

String sends a SOAPAction http header.

nil sends no SOAPAction http header.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/handsoap/service.rb', line 132

def invoke(action, options = { :soap_action => :auto }, &block) # :yields: Handsoap::XmlMason::Element
  if action
    if options.kind_of? String
      options = { :soap_action => options }
    end
    if options[:soap_action] == :auto
      options[:soap_action] = action.gsub(/^.+:/, "")
    elsif options[:soap_action] == :none
      options[:soap_action] = nil
    end
    doc = make_envelope do |body|
      body.add action
    end
    if block_given?
      yield doc.find(action)
    end
    dispatch(doc, options[:soap_action])
  end
end

#make_envelope ⇒ Object

Creates a standard SOAP envelope and yields the Body element.



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/handsoap/service.rb', line 246

def make_envelope # :yields: Handsoap::XmlMason::Element
  doc = XmlMason::Document.new do |doc|
    doc.alias 'env', self.class.envelope_namespace
    doc.add "env:Envelope" do |env|
      env.add "*:Header"
      env.add "*:Body"
    end
  end
  self.class.fire_on_create_document doc # deprecated .. use instance method
  on_create_document(doc)
  if block_given?
    yield doc.find("Body")
  end
  return doc
end

#on_before_dispatch ⇒ Object

Hook that is called before the message is dispatched.

You can override this to provide filtering and logging.



159
160
 
# File 'lib/handsoap/service.rb', line 159

def on_before_dispatch
end

#on_create_document(doc) ⇒ Object

Hook that is called when a new request document is created.

You can override this to add namespaces and other elements that are common to all requests (Such as authentication).



154
155
 
# File 'lib/handsoap/service.rb', line 154

def on_create_document(doc)
end

#on_fault(fault) ⇒ Object

Hook that is called if the dispatch returns a Fault.

Default behaviour is to raise the Fault, but you can override this to provide logging and more fine-grained handling faults.



175
176
177
 
# File 'lib/handsoap/service.rb', line 175

def on_fault(fault)
  raise fault
end

#on_http_error(status, content) ⇒ Object

Hook that is called if there is a HTTP level error.

Default behaviour is to raise an error.



169
170
171
 
# File 'lib/handsoap/service.rb', line 169

def on_http_error(status, content)
  raise "HTTP error #{status}"
end

#on_missing_document(soap_response) ⇒ Object

Hook that is called if the response does not contain a valid SOAP enevlope.

Default behaviour is to raise an error



181
182
183
 
# File 'lib/handsoap/service.rb', line 181

def on_missing_document(soap_response)
  raise "The response is not a valid SOAP envelope"
end

#on_response_document(doc) ⇒ Object

Hook that is called when there is a response.

You can override this to register common namespaces, useful for parsing the document.



164
165
 
# File 'lib/handsoap/service.rb', line 164

def on_response_document(doc)
end

#send_http_request(uri, post_body, headers) ⇒ Object

Does the actual HTTP level interaction.



195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/handsoap/service.rb', line 195

def send_http_request(uri, post_body, headers)
  if Handsoap.http_driver == :curb
    http_client = Curl::Easy.new(uri)
    http_client.headers = headers
    http_client.http_post post_body
    return { :status => http_client.response_code, :body => http_client.body_str, :content_type => http_client.content_type }
  elsif Handsoap.http_driver == :httpclient
    response = HTTPClient.new.post(uri, post_body, headers)
    return { :status => response.status, :body => response.content, :content_type => response.contenttype }
  else
    raise "Unknown http driver #{Handsoap.http_driver}"
  end
end