Class: Savon::SOAP

Inherits:
Object show all
Defined in:
lib/savon/soap.rb

Overview

Savon::SOAP

Savon::SOAP represents the SOAP request. Pass a block to your SOAP call and the SOAP object is passed to it as the first argument. The object allows setting the SOAP version, header, body and namespaces per request.

Body

The body method lets you specify parameters to be received by the SOAP action.

You can either pass in a hash (which will be translated to XML via Hash.to_soap_xml):

response = client.get_user_by_id do |soap|
  soap.body = { :id => 123 }
end

Or a string containing the raw XML:

response = client.get_user_by_id do |soap|
  soap.body = "<id>123</id>"
end

Request output:

<env:Envelope
    xmlns:wsdl="http://example.com/user/1.0/UserService"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <wsdl:getUserById><id>123</id></wsdl:getUserById>
  </env:Body>
</env:Envelope>

Please look at the documentation of Hash.to_soap_xml for some more information.

Version

Savon defaults to SOAP 1.1. In case your service uses SOAP 1.2, you can use the version method to change the default per request.

response = client.get_all_users do |soap|
  soap.version = 2
end

You can also change the default to SOAP 1.2 for all request:

Savon::SOAP.version = 2

Header

If you need to add custom XML into the SOAP header, you can use the header method.

The value is expected to be a hash (which will be translated to XML via Hash.to_soap_xml):

response = client.get_all_users do |soap|
  soap.header["specialApiKey"] = "secret"
end

Or a string containing the raw XML:

response = client.get_all_users do |soap|
  soap.header = "<specialApiKey>secret</specialApiKey>"
end

Request output:

<env:Envelope
    xmlns:wsdl="http://example.com/user/1.0/UserService"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header>
    <specialApiKey>secret</specialApiKey>
  </env:Header>
  <env:Body>
    <wsdl:getAllUsers></wsdl:getAllUsers>
  </env:Body>
</env:Envelope>

Namespaces

The namespaces method contains a hash of attributes for the SOAP envelope. You can overwrite it or add additional attributes.

response = client.get_all_users do |soap|
  soap.namespaces["xmlns:domains"] = "http://domains.example.com"
end

Request output:

<env:Envelope
    xmlns:wsdl="http://example.com/user/1.0/UserService"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:domains="http://domains.example.com">
  <env:Body>
    <wsdl:getAllUsers></wsdl:getAllUsers>
  </env:Body>
</env:Envelope>

Input

You can change the name of the SOAP input tag in case you need to.

response = client.get_all_users do |soap|
  soap.input = "GetAllUsersRequest"
end

Request output:

<env:Envelope
    xmlns:wsdl="http://example.com/user/1.0/UserService"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <wsdl:GetAllUsersRequest></wsdl:GetAllUsersRequest>
  </env:Body>
</env:Envelope>

Constant Summary collapse

Versions =

Supported SOAP versions.

[1, 2]
Namespace =

SOAP namespaces by SOAP version.

{
  1 => "http://schemas.xmlsoap.org/soap/envelope/",
  2 => "http://www.w3.org/2003/05/soap-envelope"
}
ContentType =

Content-Types by SOAP version.

{ 1 => "text/xml", 2 => "application/soap+xml" }
DateTimeFormat =

SOAP xs:dateTime format.

"%Y-%m-%dT%H:%M:%S%Z"
DateTimeRegexp =

SOAP xs:dateTime Regexp.

/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
@@version =

The global SOAP version.

1

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(action, input, endpoint) ⇒ SOAP

Initialzes the SOAP object. Expects a SOAP operation Hash along with an endpoint.



173
174
175
176
177
 
# File 'lib/savon/soap.rb', line 173

def initialize(action, input, endpoint)
  @action, @input = action, input
  @endpoint = endpoint.kind_of?(URI) ? endpoint : URI(endpoint)
  @builder = Builder::XmlMarkup.new
end

Instance Attribute Details

#action ⇒ Object

Returns the SOAP action.



186
187
188
 
# File 'lib/savon/soap.rb', line 186

def action
  @action ||= ""
end

#body ⇒ Object

Accessor for the SOAP body. Expected to be a Hash that can be translated to XML via Hash.to_soap_xml or any other Object responding to to_s.



212
213
214
 
# File 'lib/savon/soap.rb', line 212

def body
  @body
end

#endpoint ⇒ Object

Accessor for the SOAP endpoint.



199
200
201
 
# File 'lib/savon/soap.rb', line 199

def endpoint
  @endpoint
end

#header ⇒ Object

Returns the SOAP header. Defaults to an empty Hash.



206
207
208
 
# File 'lib/savon/soap.rb', line 206

def header
  @header ||= {}
end

#input ⇒ Object

Returns the SOAP input.



194
195
196
 
# File 'lib/savon/soap.rb', line 194

def input
  @input ||= ""
end

#namespaces ⇒ Object

Returns the namespaces. A Hash containing the namespaces (keys) and the corresponding URI’s (values). Defaults to a Hash containing an xmlns:env key and the namespace for the current SOAP version.



224
225
226
 
# File 'lib/savon/soap.rb', line 224

def namespaces
  @namespaces ||= { "xmlns:env" => Namespace[version] }
end

#wsse=(value) ⇒ Object (writeonly)

Sets the WSSE options.



180
181
182
 
# File 'lib/savon/soap.rb', line 180

def wsse=(value)
  @wsse = value
end

#xml ⇒ Object

Accessor for overwriting the default SOAP request. Let’s you specify completely custom XML.



215
216
217
 
# File 'lib/savon/soap.rb', line 215

def xml
  @xml
end

Class Method Details

.header ⇒ Object

Returns the global SOAP header. Defaults to an empty Hash.



156
157
158
 
# File 'lib/savon/soap.rb', line 156

def self.header
  @@header ||= {}
end

.header=(header) ⇒ Object

Sets the global SOAP header. Expected to be a Hash that can be translated to XML via Hash.to_soap_xml or any other Object responding to to_s.



151
152
153
 
# File 'lib/savon/soap.rb', line 151

def self.header=(header)
  @@header = header
end

.namespaces ⇒ Object

Returns the global namespaces. A Hash containing the namespaces (keys) and the corresponding URI’s (values).



168
169
170
 
# File 'lib/savon/soap.rb', line 168

def self.namespaces
  @@namespaces ||= {}
end

.namespaces=(namespaces) ⇒ Object

Sets the global namespaces. Expected to be a Hash containing the namespaces (keys) and the corresponding URI’s (values).



162
163
164
 
# File 'lib/savon/soap.rb', line 162

def self.namespaces=(namespaces)
  @@namespaces = namespaces if namespaces.kind_of? Hash
end

.version ⇒ Object

Returns the global SOAP version.



140
141
142
 
# File 'lib/savon/soap.rb', line 140

def self.version
  @@version
end

.version=(version) ⇒ Object

Sets the global SOAP version.



145
146
147
 
# File 'lib/savon/soap.rb', line 145

def self.version=(version)
  @@version = version if Versions.include? version
end

Instance Method Details

#namespace=(namespace) ⇒ Object

Convenience method for setting the xmlns:wsdl namespace.



229
230
231
 
# File 'lib/savon/soap.rb', line 229

def namespace=(namespace)
  namespaces["xmlns:wsdl"] = namespace
end

#to_xml ⇒ Object

Returns the SOAP envelope XML.



244
245
246
247
248
249
250
251
252
253
 
# File 'lib/savon/soap.rb', line 244

def to_xml
  unless @xml
    @builder.instruct!
    @xml = @builder.env :Envelope, merged_namespaces do |xml|
      xml.env(:Header) { xml << merged_header } unless merged_header.empty?
      xml_body xml
    end
  end
  @xml
end

#version ⇒ Object

Returns the SOAP version. Defaults to the global default.



239
240
241
 
# File 'lib/savon/soap.rb', line 239

def version
  @version ||= self.class.version
end

#version=(version) ⇒ Object

Sets the SOAP version.



234
235
236
 
# File 'lib/savon/soap.rb', line 234

def version=(version)
  @version = version if Versions.include? version
end