Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update SOAP module spec #83

Merged
merged 8 commits into from
Aug 14, 2023
Merged

Update SOAP module spec #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fe6930c
[Automated] Update the native jar versions
madhukaw Aug 14, 2023
7dde25f
Update lang dependency to stable version
madhukaw Aug 14, 2023
1f6d86b
Update spec
madhukaw Aug 14, 2023
1173f3f
Refactor spec
madhukaw Aug 14, 2023
e84ff94
Refactor spec
madhukaw Aug 14, 2023
ca7964a
Fix typo in spec
madhukaw Aug 14, 2023
cdf4331
Add soap version sample to spec
madhukaw Aug 14, 2023
c401e99
Fix code review suggestion
madhukaw Aug 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ballerina/Ballerina.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
org = "ballerina"
name = "soap"
version = "0.2.0"
version = "0.1.0"
authors = ["Ballerina"]
keywords = ["soap"]
repository = "https://github.com/ballerina-platform/module-ballerina-soap"
Expand Down
4 changes: 2 additions & 2 deletions ballerina/Dependencies.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

[ballerina]
dependencies-toml-version = "2"
distribution-version = "2201.8.0-20230726-145300-b2bdf796"
distribution-version = "2201.7.0"

[[package]]
org = "ballerina"
Expand Down Expand Up @@ -269,7 +269,7 @@ dependencies = [
[[package]]
org = "ballerina"
name = "soap"
version = "0.2.0"
version = "0.1.0"
dependencies = [
{org = "ballerina", name = "http"},
{org = "ballerina", name = "lang.xml"},
Expand Down
118 changes: 61 additions & 57 deletions docs/spec/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
_Owners_: @shafreenAnfar @MadhukaHarith92
_Reviewers_: @shafreenAnfar
_Created_: 2023/06/07
_Updated_: 2023/06/07
_Updated_: 2023/08/14
_Edition_: Swan Lake

## Introduction
Expand All @@ -18,83 +18,87 @@ The conforming implementation of the specification is released and included in t
## Contents

1. [Overview](#1-overview)
2. [Compatibility](#2-compatibility)
3. [Usage Example](#3-usage-example)
2. [Components](#2-components)
* 2.1 [Client](#21-client)
* 2.1.1 [Initializing the Client](#211-initializing-the-client)
* 2.1.2 [SendReceive](#211-sendreceive)
* 2.1.3 [SendOnly](#213-sendonly)
3. [Supported SOAP Versions](#3-supported-soap-versions)

## 1. Overview
This specification elaborates on the functions available in the Soap library.

The soap module abstracts out the details of the creation of a SOAP envelope, headers, and the body in a SOAP message.

## 2. Compatibility
## 2. Components
This section describes the components of the Ballerina SOAP package. To use the Ballerina SOAP package, a user must import the Ballerina SOAP package first.
```ballerina
import ballerina/soap;
```

### 2.1 Client

The SOAP client can be used to connect to a SOAP service and retrieve data.

#### 2.1.1 Initializing the Client

The `soap:Client` `init` method requires a valid URL and optional configuration to initialize the client.

#### 2.1.2 SendReceive

The `sendReceive` function sends SOAP request and expects a response.

```ballerina
import ballerina/io;
import ballerina/soap;
import ballerina/mime;

public function main () returns error? {

soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl");

| | Versions |
|:------------------------:|:------------------:|
| Ballerina Language | 2201.6.0 |
| SOAP Version | 0.1 |
xml body = xml `<quer:CheckPhoneNumber xmlns:quer="http://ws.cdyne.com/PhoneVerify/query">
<quer:PhoneNumber>18006785432</quer:PhoneNumber>
<quer:LicenseKey>0</quer:LicenseKey>
</quer:CheckPhoneNumber>`;

xml|mime:Entity[] response = check soapClient->sendReceive(body);
io:println(response);
}
```

#### 2.1.3 SendOnly

## 3. Usage Example
The `sendOnly` function fires and forgets requests. It sends the request without the possibility of any response from the service (even an error).

```ballerina
import ballerina/io;
import ballerina/soap;
import ballerina/mime;

public function main () {
public function main () returns error? {

soap:Soap12Client soapClient = new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl");
soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl");

xml body = xml `<quer:CheckPhoneNumber xmlns:quer="http://ws.cdyne.com/PhoneVerify/query">
<quer:PhoneNumber>18006785432</quer:PhoneNumber>
<quer:LicenseKey>0</quer:LicenseKey>
</quer:CheckPhoneNumber>`;

var response = soapClient->sendReceive(body);
if (response is soap:SoapResponse) {
io:println(response["payload"]);
} else {
io:println(response.message());
}
_ = check soapClient->sendOnly(body);
}
```

Follow the steps below to run this example.

1. Save the example in a Ballerina file (e.g., `soapExample.bal`).
2. Execute the `ballerina run soapExample.bal` command to run the file.
You will get a response similar to the following.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Body xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<CheckPhoneNumberResponse xmlns="http://ws.cdyne.com/PhoneVerify/query">
<CheckPhoneNumberResult>
<Company>Toll Free</Company>
<Valid>true</Valid>
<Use>Assigned to a code holder for normal use.</Use>
<State>TF</State>
<RC />
<OCN />
<OriginalNumber>18006785432</OriginalNumber>
<CleanNumber>8006785432</CleanNumber>
<SwitchName />
<SwitchType />
<Country>United States</Country>
<CLLI />
<PrefixType>Landline</PrefixType>
<LATA />
<sms>Landline</sms>
<Email />
<AssignDate>Unknown</AssignDate>
<TelecomCity />
<TelecomCounty />
<TelecomState>TF</TelecomState>
<TelecomZip />
<TimeZone />
<Lat />
<Long />
<Wireless>false</Wireless>
<LRN />
</CheckPhoneNumberResult>
</CheckPhoneNumberResponse>
</soap:Body>
## 3. Supported SOAP Versions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section has not been included into table-of-content.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added.


The soap module supports SOAP 1.1 and 1.2 versions. By default, the soap client is configured to work with SOAP 1.1. Users can overwrite this to support SOAP 1.2 by passing `soapVersion`
parameter during client initialization.

```ballerina
import ballerina/soap;

public function main () returns error? {

soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl", soapVersion = SOAP12);
}
```
4 changes: 2 additions & 2 deletions gradle.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
org.gradle.caching=true
group=io.ballerina.stdlib
version=0.2.0-SNAPSHOT
version=0.1.0-SNAPSHOT

checkstylePluginVersion=8.18
spotbugsPluginVersion=4.5.1
Expand All @@ -9,7 +9,7 @@ downloadPluginVersion=4.0.4
releasePluginVersion=2.6.0
ballerinaGradlePluginVersion=1.0.0

ballerinaLangVersion=2201.8.0-20230726-145300-b2bdf796
ballerinaLangVersion=2201.7.0
dilanSachi marked this conversation as resolved.
Show resolved Hide resolved

#stdlib dependencies
stdlibIoVersion=1.5.0
Expand Down
Loading