savon 0.7.4 → 0.7.5

data/readme/value_mapping.rdoc

@@ -0,0 +1,49 @@
+Of course both SOAP request and response are pure XML. Even though (assuming your XML applies to some defaults), Savon lets you specify the SOAP header and body as a Hash as well as returning the [[Response]] as a Hash.
+
+== SOAP header and body
+
+Some Hash keys and values passed to [[SOAP]] header and body are converted to SOAP compatible values automatically.
+
+* Hash keys specified as Symbols are converted to lowerCamelCase Strings
+* Hash keys specified as Strings are not converted and may contain namespaces
+* DateTime Hash values are converted to xs:dateTime Strings
+* Objects respond to to_datetime (except Strings) are converted to xs:dateTime Strings
+* TrueClass and FalseClass objects are converted to "true" and "false"
+* All other objects are expected to be converted to Strings using to_s
+
+Example:
+
+  date = DateTime.new 2010, 11, 22, 11, 22, 33
+  response = client.user_magic do |soap|
+    soap.body = {
+      :magic_request => {
+        :perform_move => true,
+        "perform_at" => date
+      }
+    }
+  end
+
+Request:
+
+  <env:Envelope
+      xmlns:wsdl="http://ws.user.example.com"
+      xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+    <env:Header></env:Header>
+    <env:Body>
+      <wsdl:userMagic>
+        <magicRequest>
+          <performMove>true</performMove>
+          <perform_at>2012-06-11T10:42:21</perform_at>
+        </magicRequest>
+      </wsdl:userMagic>
+    </env:Body>
+  </env:Envelope>
+
+== SOAP response as a Hash
+
+When translating the SOAP response to a Hash, some XML nodes and values are converted to more convenient Ruby objects. Translation is done using John Nunemaker's {Crack}[http://github.com/jnunemaker/crack] library. Afterward, Savon does some extra mapping.
+
+* Hash keys get converted to snake_case Symbols and namespaces are stripped off
+* SOAP nil values are converted to nil
+* Hash values specified in xs:DateTime format are converted to DateTime objects
+* Hash values of "true" and "false" are converted to TrueClass and FalseClass

data/readme/wsdl.rdoc

@@ -0,0 +1,39 @@
+Savon::WSDL represents the WSDL of your service, including information like the namespace URI and available SOAP actions.
+
+== Raw WSDL document
+
+  client.wsdl.to_s
+
+== Available SOAP actions
+
+  client.wsdl.soap_actions
+  => [:get_all_users, :get_user_by_id]
+
+== Namespace URI
+
+  client.wsdl.namespace_uri
+  => "http://ws.userservice.example.com"
+
+== Disable Savon::WSDL
+
+Especially with large services (i.e. Ebay), getting and parsing the WSDL document can really slow down your request. So in order to gain performance, you can disable the use of Savon::WSDL by simply appending an exclamation mark (!) to your SOAP call.
+
+  client.get_all_users!
+
+Disabling Savon::WSDL comes with some disadvantages though. First of all, you need to know and specify the namespace URI of your service per request.
+
+  client.get_user_by_id! do |soap|
+    soap.namespace = "http://example.com/UserService"
+    soap.body = { :id => 666 }
+  end
+
+Without a WSDL, Savon also has to guess the name of the SOAP action and input. It takes the name of the method called on its client instance, converts it to lowerCamelCase and uses the result. The SOAP call above expects a SOAP action with an original name of "getUserById".
+
+If that doesn't fit the naming conventions of your service, you need to specify the names yourself. Here is an example request for a SOAP action called "GetUserById", requiring an input tag named "GetUserByIdRequest".
+
+  client.get_user_by_id! do |soap|
+    soap.action = "GetUserById"
+    soap.input = "GetUserByIdRequest"
+    soap.namespace = "http://example.com/UserService"
+    soap.body = { :id => 666 }
+  end

data/readme/wsse.rdoc

@@ -0,0 +1,28 @@
+Savon::WSSE represents WSSE authentication. Pass a block to your SOAP call and the WSSE object is passed to it as the second argument. The object allows setting the WSSE username, password and whether to use digest authentication.
+
+== Username and password
+
+By default, Savon does not use WSSE authentication. Simply specify a username and password to change this.
+
+  response = client.get_all_users do |soap, wsse|
+    wsse.username = "gorilla"
+    wsse.password = "secret"
+  end
+
+== Digest
+
+To use WSSE digest authentication, just use the digest method to set digest authentication to true.
+
+  response = client.get_all_users do |soap, wsse|
+    wsse.username = "gorilla"
+    wsse.password = "secret"
+    wsse.digest = true
+  end
+
+== Default to WSSE
+
+In case all you're services require WSSE authentication, you can set your credentials and whether to use WSSE digest for every request:
+
+  Savon::WSSE.username = "dude"
+  Savon::WSSE.password = "secret"
+  Savon::WSSE.digest = true

data/spec/basic_spec_helper.rb

@@ -1,4 +1,3 @@
-require "rubygems"
 require "rake"
 require "spec"
 require "mocha"

data/spec/savon/client_spec.rb

@@ -37,7 +37,7 @@ describe Savon::Client do
 
   it "should disable the Savon::WSDL when passed a method with an exclamation mark" do
     @client.wsdl.enabled?.should be_true
-    [:respond_to?, :operations, :namespace_uri, :soap_endpoint].each do |method|
+    [:operations, :namespace_uri, :soap_endpoint].each do |method|
       Savon::WSDL.any_instance.expects(method).never
     end
 

data/spec/savon/core_ext/array_spec.rb

@@ -0,0 +1,19 @@
+require "spec_helper"
+
+describe Array do
+
+  describe "to_soap_xml" do
+    describe "should return SOAP request compatible XML" do
+      it "for an Array of Hashes" do
+        hash, result = [{ :name => "Eve" }], "<findUser><name>Eve</name></findUser>"
+        hash.to_soap_xml("findUser").should == result
+      end
+
+      it "for an Array of Strings and other Objects" do
+        hash, result = [:id, :name], "<someValues>id</someValues><someValues>name</someValues>"
+        hash.to_soap_xml("someValues").should == result
+      end
+    end
+  end
+
+end

data/spec/savon/core_ext/hash_spec.rb

@@ -3,135 +3,166 @@ require "spec_helper"
 describe Hash do
 
   describe "find_soap_body" do
-    it "returns the content from the 'soap:Body' element" do
-      { "soap:Envelope" => { "soap:Body" => "content" } }.find_soap_body.should == "content"
+    it "should return the content from the 'soap:Body' element" do
+      soap_body = { "soap:Envelope" => { "soap:Body" => "content" } }
+      soap_body.find_soap_body.should == "content"
     end
 
-    it "returns an empty Hash in case the 'soap:Body' element could not be found" do
-      { "some_hash" => "content" }.find_soap_body.should == {}
+    it "should return an empty Hash in case the 'soap:Body' element could not be found" do
+      soap_body = { "some_hash" => "content" }
+      soap_body.find_soap_body.should == {}
     end
   end
 
   describe "to_soap_xml" do
-    describe "returns SOAP request compatible XML" do
+    describe "should return SOAP request compatible XML" do
       it "for a simple Hash" do
-        { :some => "user" }.to_soap_xml.should == "<some>user</some>"
+        hash, result = { :some => "user" }, "<some>user</some>"
+        hash.to_soap_xml.should == result
       end
 
       it "for a nested Hash" do
-        { :some => { :new => "user" } }.to_soap_xml.
-          should == "<some><new>user</new></some>"
+        hash, result = { :some => { :new => "user" } }, "<some><new>user</new></some>"
+        hash.to_soap_xml.should == result
       end
 
       it "for a Hash with multiple keys" do
-        soap_xml = { :all => "users", :before => "whatever" }.to_soap_xml
-
-        soap_xml.should include("<all>users</all>")
-        soap_xml.should include("<before>whatever</before>")
+        hash = { :all => "users", :before => "whatever" }
+        hash.to_soap_xml.should include("<all>users</all>", "<before>whatever</before>")
       end
 
       it "for a Hash containing an Array" do
-        { :some => ["user", "gorilla"] }.to_soap_xml.
-          should == "<some>user</some><some>gorilla</some>"
+        hash, result = { :some => ["user", "gorilla"] }, "<some>user</some><some>gorilla</some>"
+        hash.to_soap_xml.should == result
       end
 
       it "for a Hash containing an Array of Hashes" do
-        { :some => [{ :new => "user" }, { :old => "gorilla" }] }.to_soap_xml.
-          should == "<some><new>user</new></some><some><old>gorilla</old></some>"
+        hash = { :some => [{ :new => "user" }, { :old => "gorilla" }] }
+        result = "<some><new>user</new></some><some><old>gorilla</old></some>"
+
+        hash.to_soap_xml.should == result
       end
     end
 
-    it "converts Hash key Symbols to lowerCamelCase" do
-      { :find_or_create => "user" }.to_soap_xml.
-        should == "<findOrCreate>user</findOrCreate>"
+    it "should convert Hash key Symbols to lowerCamelCase" do
+      hash, result = { :find_or_create => "user" }, "<findOrCreate>user</findOrCreate>"
+      hash.to_soap_xml.should == result
     end
 
-    it "does not convert Hash key Strings" do
-      { "find_or_create" => "user" }.to_soap_xml.
-        should == "<find_or_create>user</find_or_create>"
+    it "should not convert Hash key Strings" do
+      hash, result = { "find_or_create" => "user" }, "<find_or_create>user</find_or_create>"
+      hash.to_soap_xml.should == result
     end
 
-    it "converts DateTime objects to xs:dateTime compliant Strings" do
-      { :before => DateTime.new(2012, 03, 22, 16, 22, 33) }.to_soap_xml.
-        should == "<before>" << "2012-03-22T16:22:33Z" << "</before>"
+    it "should convert DateTime objects to xs:dateTime compliant Strings" do
+      hash = { :before => DateTime.new(2012, 03, 22, 16, 22, 33) }
+      result = "<before>2012-03-22T16:22:33Z</before>"
+
+      hash.to_soap_xml.should == result
     end
 
-    it "converts Objects responding to to_datetime to xs:dateTime compliant Strings" do
+    it "should convert Objects responding to to_datetime to xs:dateTime compliant Strings" do
       singleton = Object.new
       def singleton.to_datetime
         DateTime.new(2012, 03, 22, 16, 22, 33)
       end
 
-      { :before => singleton }.to_soap_xml.
-        should == "<before>" << "2012-03-22T16:22:33Z" << "</before>"
+      hash, result = { :before => singleton }, "<before>2012-03-22T16:22:33Z</before>"
+      hash.to_soap_xml.should == result
     end
 
-    it "calls to_s on Strings even if they respond to to_datetime" do
+    it "should call to_s on Strings even if they respond to to_datetime" do
       object = "gorilla"
       object.expects(:to_s).returns object
       object.expects(:to_datetime).never
 
-      { :name => object }.to_soap_xml.should == "<name>gorilla</name>"
+      hash, result = { :name => object }, "<name>gorilla</name>"
+      hash.to_soap_xml.should == result
     end
 
-    it "call to_s on any other Object" do
+    it "should call to_s on any other Object" do
       [666, true, false, nil].each do |object|
         { :some => object }.to_soap_xml.should == "<some>#{object}</some>"
       end
     end
 
-    it "preserves the order of Hash keys and values specified through :@inorder" do
-      { :find_user => { :name => "Lucy", :id => 666, :@inorder => [:id, :name] } }.to_soap_xml.
-        should == "<findUser><id>666</id><name>Lucy</name></findUser>"
+    it "should preserve the order of Hash keys and values specified through :order!" do
+      hash = { :find_user => { :name => "Lucy", :id => 666, :order! => [:id, :name] } }
+      result = "<findUser><id>666</id><name>Lucy</name></findUser>"
+      hash.to_soap_xml.should == result
 
-      { :find_user => { :by_name => { :mname => "in the", :lname => "Sky", :fname => "Lucy",
-        :@inorder => [:fname, :mname, :lname] } } }.to_soap_xml. should ==
-        "<findUser><byName><fname>Lucy</fname><mname>in the</mname><lname>Sky</lname></byName></findUser>"
+      hash = { :find_user => { :mname => "in the", :lname => "Sky", :fname => "Lucy", :order! => [:fname, :mname, :lname] } }
+      result = "<findUser><fname>Lucy</fname><mname>in the</mname><lname>Sky</lname></findUser>"
+      hash.to_soap_xml.should == result
     end
 
-    it "raises an error if the :@inorder Array does not match the Hash keys" do
-      lambda { { :name => "Lucy", :id => 666, :@inorder => [:name] }.to_soap_xml }.
-        should raise_error(RuntimeError)
+    it "should raise an error if the :order! Array does not match the Hash keys" do
+      hash = { :name => "Lucy", :id => 666, :order! => [:name] }
+      lambda { hash.to_soap_xml }.should raise_error(ArgumentError)
 
-      lambda { { :by_name => { :name => "Lucy", :lname => "Sky", :@inorder => [:mname, :name] } }.to_soap_xml }.
-        should raise_error(RuntimeError)
+      hash = { :by_name => { :name => "Lucy", :lname => "Sky", :order! => [:mname, :name] } }
+      lambda { hash.to_soap_xml }.should raise_error(ArgumentError)
+    end
+
+    it "should add attributes to Hash keys specified through :attributes!" do
+      hash = { :find_user => { :person => "Lucy", :attributes! => { :person => { :id => 666 } } } }
+      result = '<findUser><person id="666">Lucy</person></findUser>'
+      hash.to_soap_xml.should == result
+
+      hash = { :find_user => { :person => "Lucy", :attributes! => { :person => { :id => 666, :city => "Hamburg" } } } }
+      soap_xml = hash.to_soap_xml
+      soap_xml.should include('id="666"', 'city="Hamburg"')
     end
   end
 
   describe "map_soap_response" do
-    it "converts Hash key Strings to snake_case Symbols" do
-      { "userResponse" => { "accountStatus" => "active" } }.map_soap_response.
-        should == { :user_response => { :account_status => "active" } }
+    it "should convert Hash key Strings to snake_case Symbols" do
+      soap_response = { "userResponse" => { "accountStatus" => "active" } }
+      result = { :user_response => { :account_status => "active" } }
+
+      soap_response.map_soap_response.should == result
     end
 
-    it "strips namespaces from Hash keys" do
-      { "ns:userResponse" => { "ns2:id" => "666" } }.map_soap_response.
-        should == { :user_response => { :id => "666" } }
+    it "should strip namespaces from Hash keys" do
+      soap_response = { "ns:userResponse" => { "ns2:id" => "666" } }
+      result = { :user_response => { :id => "666" } }
+
+      soap_response.map_soap_response.should == result
     end
 
-    it "converts Hash keys and values in Arrays" do
-      { "response" => [{ "name" => "dude" }, { "name" => "gorilla" }] }.map_soap_response.
-        should == { :response=> [{ :name => "dude" }, { :name => "gorilla" }] }
+    it "should convert Hash keys and values in Arrays" do
+      soap_response = { "response" => [{ "name" => "dude" }, { "name" => "gorilla" }] }
+      result = { :response=> [{ :name => "dude" }, { :name => "gorilla" }] }
+
+      soap_response.map_soap_response.should == result
     end
 
-    it "converts xsi:nil values to nil Objects" do
-      { "userResponse" => { "xsi:nil" => "true" } }.map_soap_response.
-        should == { :user_response => nil }
+    it "should convert xsi:nil values to nil Objects" do
+      soap_response = { "userResponse" => { "xsi:nil" => "true" } }
+      result = { :user_response => nil }
+
+      soap_response.map_soap_response.should == result
     end
 
-    it "converts Hash values matching the xs:dateTime format into DateTime Objects" do
-      { "response" => { "at" => "2012-03-22T16:22:33" } }.map_soap_response.
-        should == { :response => { :at => DateTime.new(2012, 03, 22, 16, 22, 33) } }
+    it "should convert Hash values matching the xs:dateTime format into DateTime Objects" do
+      soap_response = { "response" => { "at" => "2012-03-22T16:22:33" } }
+      result = { :response => { :at => DateTime.new(2012, 03, 22, 16, 22, 33) } }
+
+      soap_response.map_soap_response.should == result
     end
 
-    it "converts Hash values matching 'true' to TrueClass" do
-      { "response" => { "active" => "false" } }.map_soap_response.
-        should == { :response => { :active => false } }
+    it "should convert Hash values matching 'true' to TrueClass" do
+      soap_response = { "response" => { "active" => "false" } }
+      result = { :response => { :active => false } }
+
+      soap_response.map_soap_response.should == result
     end
 
-    it "converts Hash values matching 'false' to FalseClass" do
-      { "response" => { "active" => "true" } }.map_soap_response.
-        should == { :response => { :active => true } }
+    it "should convert Hash values matching 'false' to FalseClass" do
+      soap_response = { "response" => { "active" => "true" } }
+      result = { :response => { :active => true } }
+
+      soap_response.map_soap_response.should == result
     end
   end
 

data/spec/savon/core_ext/string_spec.rb

@@ -30,6 +30,21 @@ describe String do
     end
   end
 
+  describe "starts_with?" do
+    it "should return whether it starts with a given suffix" do
+      "authenticate".starts_with?("auth").should be_true
+      "authenticate".starts_with?("cate").should be_false
+    end
+  end
+
+  describe "ends_with?" do
+    it "should return whether it ends with a given suffix" do
+      "authenticate!".ends_with?("!").should be_true
+      "authenticate".ends_with?("cate").should be_true
+      "authenticate".ends_with?("?").should be_false
+    end
+  end
+
   describe "strip_namespace" do
     it "strips the namespace from a namespaced String" do
       "ns:customer".strip_namespace.should == "customer"

data/spec/savon/request_spec.rb

@@ -76,8 +76,8 @@ describe Savon::Request do
   end
 
   it "executes a SOAP request and returns the Net::HTTP response" do
-    soap = Savon::SOAP.new
-    soap.endpoint = URI EndpointHelper.wsdl_endpoint
+    some_operation = WSDLFixture.authentication(:operations)[:authenticate]
+    soap = Savon::SOAP.new some_operation, EndpointHelper.soap_endpoint
     soap_response = @request.soap soap
 
     soap_response.should be_a(Net::HTTPResponse)

data/spec/savon/soap_spec.rb

@@ -2,24 +2,42 @@ require "spec_helper"
 
 describe Savon::SOAP do
   before do
-    @soap = Savon::SOAP.new
-    @soap.action = WSDLFixture.authentication(:operations)[:authenticate][:action]
+    @authenticate_operation = WSDLFixture.authentication(:operations)[:authenticate]
+    @soap = Savon::SOAP.new @authenticate_operation, EndpointHelper.soap_endpoint
   end
 
   it "contains the SOAP namespace for each supported SOAP version" do
-    Savon::SOAPVersions.each do |soap_version|
-      Savon::SOAP::SOAPNamespace[soap_version].should be_a(String)
-      Savon::SOAP::SOAPNamespace[soap_version].should_not be_empty
+    Savon::SOAP::Versions.each do |soap_version|
+      Savon::SOAP::Namespace[soap_version].should be_a(String)
+      Savon::SOAP::Namespace[soap_version].should_not be_empty
     end
   end
 
   it "contains the Content-Types for each supported SOAP version" do
-    Savon::SOAPVersions.each do |soap_version|
+    Savon::SOAP::Versions.each do |soap_version|
       Savon::SOAP::ContentType[soap_version].should be_a(String)
       Savon::SOAP::ContentType[soap_version].should_not be_empty
     end
   end
 
+  it "contains an Array of supported SOAP versions" do
+    Savon::SOAP::Versions.should be_an(Array)
+    Savon::SOAP::Versions.should_not be_empty
+  end
+
+  it "contains the xs:dateTime format" do
+    Savon::SOAP::DateTimeFormat.should be_a(String)
+    Savon::SOAP::DateTimeFormat.should_not be_empty
+
+    DateTime.new(2012, 03, 22, 16, 22, 33).strftime(Savon::SOAP::DateTimeFormat).
+      should == "2012-03-22T16:22:33Z"
+  end
+
+  it "contains a Regexp matching the xs:dateTime format" do
+    Savon::SOAP::DateTimeRegexp.should be_a(Regexp)
+    (Savon::SOAP::DateTimeRegexp === "2012-03-22T16:22:33").should be_true
+  end
+
   it "defaults to SOAP 1.1" do
     Savon::SOAP.version.should == 1
   end
@@ -35,15 +53,22 @@ describe Savon::SOAP do
     @soap.wsse = Savon::WSSE.new
   end
 
-  it "is has both getter and setter for the SOAP action" do
-    @soap.action.should == WSDLFixture.authentication(:operations)[:authenticate][:action]
+  it "has both getter and setter for the SOAP action" do
+    @soap.action.should == @authenticate_operation[:action]
 
     @soap.action = "someAction"
     @soap.action.should == "someAction"
   end
 
-  it "has a setter for the SOAP input" do
-    @soap.input = "FindUserRequest", { "username" => "auser", "anotherAttr" => "someVal" }
+  it "has both getter and setter for the SOAP input" do
+    @soap.input.should == @authenticate_operation[:input]
+
+    @soap.input = "whatever"
+    @soap.input.should == "whatever"
+
+    args = "FindUserRequest", { "username" => "auser", "anotherAttr" => "someVal" }
+    @soap.input = *args
+    @soap.input.should == [*args]
   end
 
   it "has both getter and setter for global SOAP headers" do
@@ -75,12 +100,12 @@ describe Savon::SOAP do
 
   describe "has a getter for namespaces" do
     it "which defaults to include the SOAP 1.1 namespace" do
-      @soap.namespaces.should == { "xmlns:env" => Savon::SOAP::SOAPNamespace[1] }
+      @soap.namespaces.should == { "xmlns:env" => Savon::SOAP::Namespace[1] }
     end
 
     it "which contains the SOAP 1.2 namespace if specified" do
       @soap.version = 2
-      @soap.namespaces.should == { "xmlns:env" => Savon::SOAP::SOAPNamespace[2] }
+      @soap.namespaces.should == { "xmlns:env" => Savon::SOAP::Namespace[2] }
     end
   end
 
@@ -101,9 +126,8 @@ describe Savon::SOAP do
   end
 
   it "has both getter and setter for the SOAP endpoint" do
-    @soap.endpoint.should be_nil
-
     soap_endpoint = URI EndpointHelper.soap_endpoint
+
     @soap.endpoint = soap_endpoint
     @soap.endpoint.should == soap_endpoint
   end
@@ -147,12 +171,12 @@ describe Savon::SOAP do
 
     it "uses the SOAP namespace for the specified SOAP version" do
       @soap.version = 2
-      @soap.to_xml.should include(Savon::SOAP::SOAPNamespace[2])
+      @soap.to_xml.should include(Savon::SOAP::Namespace[2])
     end
 
     it "uses the SOAP namespace for the default SOAP version otherwise" do
       Savon::SOAP.version = 2
-      @soap.to_xml.should include(Savon::SOAP::SOAPNamespace[2])
+      @soap.to_xml.should include(Savon::SOAP::Namespace[2])
     end
 
     it "merges global and per request headers defined as Hashes" do