Ruby Web Service Application - SOAP4R

What is SOAP?

Simple Object Access Protocol (SOAP) is a protocol specification for exchanging data.

SOAP is a simple XML-based protocol that enables applications to exchange information over HTTP.

Simple Object Access Protocol is a protocol specification for exchanging data. It is a lightweight, simple, XML-based (a subset of the Standard Generalized Markup Language) protocol designed to exchange structured and fixed information on the Web.

For more SOAP tutorials, please see:http://www.w3cschool.cc/soap/soap-tutorial.html。

SOAP4R Installation

SOAP4R was developed and implemented by Hiroshi Nakamura for Ruby SOAP applications.

SOAP4R download address:http://raa.ruby-lang.org/project/soap4r/。

Note:Your Ruby environment may already have this component installed.

On Linux, you can also use gem to install this component. The command is as follows:

gem install soap4r --include-dependencies

If you are developing in a Windows environment, you need to download the zip compressed file and install it by executing install.rb.

SOAP4R Service

SOAP4R supports two different service types:

  • CGI/FastCGI-based Service (SOAP::RPC::CGIStub)
  • Standalone Service (SOAP::RPC:StandaloneServer)

This tutorial will introduce how to set up a standalone SOAP service. The steps are as follows:

Step 1 - Inherit SOAP::RPC::StandaloneServer

To implement your own standalone server, you need to write a new class that is a subclass of SOAP::RPC::StandaloneServer:

class MyServer < SOAP::RPC::StandaloneServer ............... end

Note:If you want to write a FastCGI-based server, you need to inherit from the SOAP::RPC::CGIStub class; the rest of the program will remain unchanged.

Step 2 - Define Processing Methods

Next, we define the Web Service methods. Below we define two methods: one adds two numbers, and the other divides two numbers:

class MyServer < SOAP::RPC::StandaloneServer ............... #Processing methods def add(a, b) return a + b end def div(a, b) return a / b end end

Step 3 - Publish Processing Methods

Next, add the methods we defined on the server. The initialize method is public and used for external connections:

class MyServer < SOAP::RPC::StandaloneServer def initialize(*args) add_method(receiver, methodName, *paramArg) end end

The following is an explanation of each parameter:

ParameterDescription
receiverThe object containing the method with the method name. If you define the service method in the same class, this parameter isself。
methodNameThe method name called by the RPC request.
paramArgParameter names and parameter modes

To understandinoutandoutparameters, consider the following service method, which requires two input parameters: inParam and inoutParam. After the function completes execution, it returns three values: retVal, inoutParam, and outParam:

def aMeth(inParam, inoutParam) retVal = inParam + inoutParam outParam = inParam . inoutParam inoutParam = inParam * inoutParam return retVal, inoutParam, outParam end

The public calling method is as follows:

add_method(self, 'aMeth', [ %w(in inParam), %w(inout inoutParam), %w(out outParam), %w(retval return) ])

Step 4 - Start the Service

Finally, we instantiate the derived class and call the start method to launch the service:

myServer = MyServer.new('ServerName', 'urn:ruby:ServiceName', hostname, port) myServer.start

The following is an explanation of the request parameters:

ParameterDescription
ServerNameService name, you can choose whatever you like
urn:ruby:ServiceNameHere urn:rubyis fixed, but you can give your service a uniqueServiceName
hostnameSpecify the host name
portWeb service port

Example

Next, we create a standalone service using the above steps:

Example

require "soap/rpc/standaloneserver" begin class MyServer < SOAP::RPC::StandaloneServer # Expose our service 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

After running the above program, a local service listening on port 8080 is started, and two methods are exposed: add and div.

You can run the above service in the background:

$ ruby MyServer.rb &

SOAP4R Client

In Ruby, the SOAP::RPC::Driver class is used to develop SOAP clients. Next, let's take a detailed look at the usage of the SOAP::RPC::Driver class.

Calling a SOAP service requires the following information:

  • SOAP service URL address (SOAP Endpoint URL)
  • Method namespace of the service (Method Namespace URI)
  • Service method name and parameter information

Next, we will create a SOAP client step by step to call the above SOAP methods: add and div:

Step 1 - Create a SOAP Driver Instance

We can instantiate the SOAP::RPC::Driver class to call its new method, as shown below:

SOAP::RPC::Driver.new(endPoint, nameSpace, soapAction)

The following is a description of the parameters:

ParameterDescription
endPointThe URL address for connecting to the SOAP service
nameSpaceThe namespace used for all RPCs of the SOAP::RPC::Driver object.
soapActionThe SOAPAction field value used in the HTTP header. If it is the string "", the default isnil

Step 2 - Add Service Methods

To add SOAP service methods to SOAP::RPC::Driver, we can call the following methods through an instance of SOAP::RPC::Driver:

driver.add_method(name, *paramArg)

The following is an explanation of the parameters:

ParameterDescription
nameThe method name of the remote web service
paramArgSpecify the parameters of the remote program

Step 3 - Call the SOAP Service

Finally, we can use the SOAP::RPC::Driver instance to call the SOAP service:

result = driver.serviceMethod(paramArg...)

serviceMethod is the actual method name of the SOAP service, and paramArg is the parameter list of the method.

Example

Based on the above steps, we can write the following SOAP client:

Example

#!/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

Above, we have only briefly introduced Ruby's Web Service. If you want to learn more, you can check the official documentation:Ruby's Web Service

Other extensions