Replace boost thread with std thread; update rest book example; move soap tutorials to wiki.
Adam Gu
7 years ago
parent
6475a3fd35
commit
33f2b84f8c
@ -1,101 +0,0 @@
|
||||
# SOAP Client Tutorial
|
||||
|
||||
Firstly, please install **SoapUI** if you don't have it. We need SoapUI to generate sample requests for each web service operation. The open source version is good enough.
|
||||
|
||||
Take the calculator web service provided by ParaSoft as an example. Download the WSDL from http://ws1.parasoft.com/glue/calculator.wsdl, create a SOAP project within SoapUI (remember to check "**Create sample requests for all operations?**"), you will see the sample request for "add" operation as the following:
|
||||
```xml
|
||||
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cal="http://www.parasoft.com/wsdl/calculator/">
|
||||
<soapenv:Header/>
|
||||
<soapenv:Body>
|
||||
<cal:add>
|
||||
<cal:x>1</cal:x>
|
||||
<cal:y>2</cal:y>
|
||||
</cal:add>
|
||||
</soapenv:Body>
|
||||
</soapenv:Envelope>
|
||||
```
|
||||
|
||||
In order to call the "add" operation, we have to send a HTTP request with the above SOAP envelope as the content. Let's see how to do this with *webcc*.
|
||||
|
||||
Firstly, create a class `CalcClient` which is derived from `webcc::SoapClient`:
|
||||
|
||||
```cpp
|
||||
#include <string>
|
||||
#include "webcc/soap_client.h"
|
||||
|
||||
class CalcClient : public webcc::SoapClient {
|
||||
public:
|
||||
CalcClient() {
|
||||
Init();
|
||||
}
|
||||
```
|
||||
|
||||
Initialize the URL, host, port, etc. in `Init()`:
|
||||
```cpp
|
||||
private:
|
||||
void Init() {
|
||||
url_ = "/glue/calculator";
|
||||
host_ = "ws1.parasoft.com";
|
||||
port_ = ""; // Default to "80".
|
||||
service_ns_ = { "cal", "http://www.parasoft.com/wsdl/calculator/" };
|
||||
result_name_ = "Result";
|
||||
}
|
||||
```
|
||||
|
||||
Because four calculator operations (*add*, *subtract*, *multiply* and *divide*) all have two parameters, we create a wrapper for `SoapClient::Call()`, name is as `Calc`:
|
||||
```cpp
|
||||
bool Calc(const std::string& operation,
|
||||
const std::string& x_name,
|
||||
const std::string& y_name,
|
||||
double x,
|
||||
double y,
|
||||
double* result) {
|
||||
// Prepare parameters.
|
||||
std::vector<webcc::Parameter> parameters{
|
||||
{ x_name, x },
|
||||
{ y_name, y }
|
||||
};
|
||||
|
||||
// Make the call.
|
||||
std::string result_str;
|
||||
webcc::Error error = Call(operation, std::move(parameters), &result_str);
|
||||
|
||||
// Error handling if any.
|
||||
if (error != webcc::kNoError) {
|
||||
std::cerr << "Error: " << error;
|
||||
std::cerr << ", " << webcc::GetErrorMessage(error) << std::endl;
|
||||
return false;
|
||||
}
|
||||
|
||||
// Convert the result from string to double.
|
||||
try {
|
||||
*result = boost::lexical_cast<double>(result_str);
|
||||
} catch (boost::bad_lexical_cast&) {
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
Note that the local parameters are moved (with `std::move()`). This is to avoid expensive copy of long string parameters, e.g., XML strings.
|
||||
|
||||
Finally, we implement the four operations simply as the following:
|
||||
```cpp
|
||||
bool Add(double x, double y, double* result) {
|
||||
return Calc("add", "x", "y", x, y, result);
|
||||
}
|
||||
|
||||
bool Subtract(double x, double y, double* result) {
|
||||
return Calc("subtract", "x", "y", x, y, result);
|
||||
}
|
||||
|
||||
bool Multiply(double x, double y, double* result) {
|
||||
return Calc("multiply", "x", "y", x, y, result);
|
||||
}
|
||||
|
||||
bool Divide(double x, double y, double* result) {
|
||||
return Calc("divide", "numerator", "denominator", x, y, result);
|
||||
}
|
||||
```
|
||||
See? It's not that complicated. Check folder ***demo/calculator_client*** for the full example.
|
||||
@ -1,137 +0,0 @@
|
||||
# SOAP Server Tutorial
|
||||
|
||||
Suppose you want to provide a calculator web service just like the one from [ParaSoft](http://ws1.parasoft.com/glue/calculator.wsdl).
|
||||
|
||||
Firstly, create a class `CalcService` which is derived from `webcc::SoapService`, override the `Handle` method:
|
||||
```cpp
|
||||
// calc_service.h
|
||||
|
||||
#include "webcc/soap_service.h"
|
||||
|
||||
class CalcService : public webcc::SoapService {
|
||||
public:
|
||||
bool Handle(const webcc::SoapRequest& soap_request,
|
||||
webcc::SoapResponse* soap_response) override;
|
||||
};
|
||||
```
|
||||
|
||||
The `Handle` method has two parameters, one for request (input), one for response (output).
|
||||
|
||||
The implementation is quite straightforward:
|
||||
|
||||
- Get operation (e.g., add) from request;
|
||||
- Get parameters (e.g., x and y) from request;
|
||||
- Calculate the result.
|
||||
- Set namespaces, result name and so on to response.
|
||||
- Set result to response.
|
||||
|
||||
```cpp
|
||||
// calc_service.cpp
|
||||
|
||||
#include "calc_service.h"
|
||||
|
||||
#include "boost/lexical_cast.hpp"
|
||||
|
||||
#include "webcc/soap_request.h"
|
||||
#include "webcc/soap_response.h"
|
||||
|
||||
bool CalcService::Handle(const webcc::SoapRequest& soap_request,
|
||||
webcc::SoapResponse* soap_response) {
|
||||
try {
|
||||
if (soap_request.operation() == "add") {
|
||||
double x = boost::lexical_cast<double>(soap_request.GetParameter("x"));
|
||||
double y = boost::lexical_cast<double>(soap_request.GetParameter("y"));
|
||||
|
||||
double result = x + y;
|
||||
|
||||
soap_response->set_soapenv_ns(webcc::kSoapEnvNamespace);
|
||||
soap_response->set_service_ns({ "cal", "http://www.example.com/calculator/" });
|
||||
soap_response->set_operation(soap_request.operation());
|
||||
soap_response->set_result_name("Result");
|
||||
soap_response->set_result(std::to_string(result));
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
// Other operations ...
|
||||
|
||||
} catch (boost::bad_lexical_cast&) {
|
||||
// ...
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
Next step, create a `SoapServer` and register `CalcService` to it with a URL.
|
||||
|
||||
```cpp
|
||||
int main(int argc, char* argv[]) {
|
||||
// Check argc and argv ...
|
||||
|
||||
unsigned short port = std::atoi(argv[1]);
|
||||
|
||||
// Number of worker threads.
|
||||
std::size_t workers = 2;
|
||||
|
||||
try {
|
||||
webcc::SoapServer server(port, workers);
|
||||
|
||||
server.RegisterService(std::make_shared<CalcService>(), "/calculator");
|
||||
|
||||
server.Run();
|
||||
|
||||
} catch (std::exception& e) {
|
||||
std::cerr << "Exception: " << e.what() << std::endl;
|
||||
return 1;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The server is created with a **port number** which will be listened on to **asynchnously** accept client connections. The connections will be firstly put into a **queue** and then processed by the **worker threads**. The number of worker threads is determined by the `workers` parameter.
|
||||
|
||||
When register service, the URL is what the clients will put in the HTTP request to access your service:
|
||||
```
|
||||
POST /calculator HTTP/1.1
|
||||
```
|
||||
|
||||
Registering multiple services to a server is allowed, but the URL must be unique for each service.
|
||||
|
||||
To invoke the `add` operation of the calculator service, an example of the client HTTP request would be:
|
||||
```
|
||||
POST /calculator HTTP/1.1
|
||||
Content-Type: text/xml; charset=utf-8
|
||||
Content-Length: 263
|
||||
Host: localhost:8080
|
||||
SOAPAction: add
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
|
||||
<soap:Body>
|
||||
<ser:add xmlns:ser="http://www.example.com/calculator/">
|
||||
<ser:x>1.000000</ser:x>
|
||||
<ser:y>2.000000</ser:y>
|
||||
</ser:add>
|
||||
</soap:Body>
|
||||
</soap:Envelope>
|
||||
```
|
||||
|
||||
And the HTTP response is:
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/xml; charset=utf-8
|
||||
Content-Length: 262
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
|
||||
<soap:Body>
|
||||
<cal:addResponse xmlns:cal="http://www.example.com/calculator/">
|
||||
<cal:Result>3.000000</cal:Result>
|
||||
</cal:addResponse>
|
||||
</soap:Body>
|
||||
</soap:Envelope>
|
||||
```
|
||||
|
||||
See [example/soap_calc_server](https://github.com/sprinfall/webcc/tree/master/example/soap_calc_server) for the full example.
|
||||
Loading…
Reference in New Issue