---

什么是 soap？

简单对象访问协议(soap,全写为simple object access protocol)是交换数据的一种协议规范。

soap 是一种简单的基于 xml 的协议，它使应用程序通过 http 来交换信息。

简单对象访问协议是交换数据的一种协议规范，是一种轻量的、简单的、基于xml（标准通用标记语言下的一个子集）的协议，它被设计成在web上交换结构化的和固化的信息。

更多 soap 教程请查看：//www.w3cschool.cn/soap/soap-intro.html。

---

soap4r 安装

soap4r 由hiroshi nakamura开发实现，用于 ruby 的 soap 应用。

soap4r 下载地址：http://raa.ruby-lang.org/soap4r/。

注意：你的ruby环境可能已经安装了该该组件。

linux 环境下你也可以使用 gem 来安装该组件，命令如下：

$ gem install soap4r --include-dependencies

如果你是window环境下开发，你需要下载zip压缩文件，并通过执行 install.rb 来安装。

---

soap4r 服务

soap4r 支持两种不同的服务类型：

• 基于 cgi/fastcgi 服务 (soap::rpc::cgistub)
• 独立服务 (soap::rpc:standaloneserver)

本教程将为大家介绍如何建立独立的 soap 服务。步骤如下：

第1步 - 继承soap::rpc::standaloneserver

为了实现自己的独立的服务器，你需要编写一个新的类，该类为 soap::rpc::standaloneserver 的子类：

class myserver < soap::rpc::standaloneserver   ............... end 

注意：如果你要编写一个基于fastcgi的服务器，那么你需要继承 soap::rpc::cgistub 类，程序的其余部分将保持不变。

第二步 - 定义处理方法

接下来我们定义web services的方法，如下我们定义两个方法，一个是两个数相加，一个是两个数相除：

class myserver < soap::rpc::standaloneserver
   ...............

   # 处理方法
   def add(a, b)
      return a + b
   end
   def div(a, b) 
      return a / b 
   end
end

第三步 - 公布处理方法

接下来添加我们在服务器上定义的方法，initialize方法是公开的，用于外部的连接：

class myserver < soap::rpc::standaloneserver
   def initialize(*args)
      add_method(receiver, methodname, *paramarg)
   end
end

以下是各参数的说明：

参数	描述
receiver	包含方法名的方法的对象。 如果你在同一个类中定义服务方法，该参数为 self。
methodname	调用 rpc 请求的方法名。
paramarg	参数名和参数模式

为了理解 inout 和 out 参数，考虑以下服务方法，需要输入两个参数:inparam 和 inoutparam，函数执行完成后返回三个值：retval、inoutparam 、outparam:

def ameth(inparam, inoutparam)
   retval = inparam + inoutparam
   outparam = inparam . inoutparam
   inoutparam = inparam * inoutparam
   return retval, inoutparam, outparam
end

公开的调用方法如下：

add_method(self, 'ameth', [
    %w(in inparam),
    %w(inout inoutparam),
    %w(out outparam),
    %w(retval return)
])

第四步 - 开启服务

最后我们通过实例化派生类，并调用 start 方法来启动服务：

myserver = myserver.new('servername',
                        'urn:ruby:servicename', hostname, port)

myserver.start

以下是请求参数的说明：

参数	描述
servername	服务名，你可以取你喜欢的
urn:ruby:servicename	here urn:ruby 是固定的，但是你可以为你的服务取一个唯一的 servicename
hostname	指定主机名
port	web 服务端口

实例

接下来我们通过以上的步骤，创建一个独立的服务：

require "soap/rpc/standaloneserver"

begin
   class myserver < soap::rpc::standaloneserver

      # expose our services
      def initialize(*args)
         add_method(self, 'add', 'a', 'b')
         add_method(self, 'div', 'a', 'b')
      end

      # handler methods
      def add(a, b)
         return a + b
      end
      def div(a, b) 
         return a / b 
      end
  end
  server = myserver.new("myserver", 
            'urn:ruby:calculation', 'localhost', 8080)
  trap('int){
     server.shutdown
  }
  server.start
rescue => err
  puts err.message
end

执行以上程序后，就启动了一个监听 8080 端口的本地服务，并公开两个方法：add 和 div。

你可以再后台执行以上服务：

$ ruby myserver.rb&

---

soap4r 客户端

ruby 中使用 soap::rpc::driver 类开发 soap 客户端。接下来我们来详细看下 soap::rpc::driver 类的使用。

调用 soap 服务需要以下信息：

• soap 服务 url 地址 (soap endpoint url)
• 服务方法的命名空间（method namespace uri）
• 服务方法名及参数信息

接下来我们就一步步来创建 soap 客户端来调用以上的 soap 方法：add 、 div:

第一步 - 创建 soap driver 实例

我们可以通过实例化 soap::rpc::driver 类来调用它的新方法，如下所示：

soap::rpc::driver.new(endpoint, namespace, soapaction)

以下是参数的描述：

参数	描述
endpoint	连接 soap 服务的 url 地址
namespace	命名空间用于 soap::rpc::driver 对象的所有 rpc .
soapaction	用于 http 头部的 soapaction 字段值。如果是字符串是"" 则默认为 nil

第二步 - 添加服务方法

为 soap::rpc::driver 添加 soap 服务方法，我们可以通过实例 soap::rpc::driver 来调用以下方法：

driver.add_method(name, *paramarg)

以下是参数的说明：

参数	描述
name	远程web服务的方法名
paramarg	指定远程程序的参数

第三步 - 调用soap服务

最后我们可以使用 soap::rpc::driver 实例来调用 soap 服务：

result = driver.servicemethod(paramarg...)

servicemethod soap服务的实际方法名，paramarg为方法的参数列表。

实例

基于以上的步骤，我们可以编写以下的 soap 客户端：

#!/usr/bin/ruby -w

require 'soap/rpc/driver'

namespace = 'urn:ruby:calculation'
url = 'http://localhost:8080/'

begin
   driver = soap::rpc::driver.new(url, namespace)
   
   # add remote sevice methods
   driver.add_method('add', 'a', 'b')

   # call remote service methods
   puts driver.add(20, 30)
rescue => err
   puts err.message
end

以上我们只是简单介绍 ruby 的 web services 。 如果你想了解更多可以查看官方文档：ruby 的 web services