WSO2 WSF/Perl API

WSO2 Web Services Framework/Perl is a Perl extension that can be used to consume Web services. This document covers the API of WSO2 WSF/Perl extension.

Member Classes

WSClient

Constructor

Constructs a new WSClient object.

Parameters:

Parameter

Default Value

Description

options

None

A hash of options. Both message related properties, defined for WSMessage as well as WSClient specific options defined below, can be included in the options hash here. Please note that the "to" option must be specified at some level in order to convey the service endpoint to be invoked.

The following table shows the possible client specific options and related details. Please refer to the WSMessage constructor documentation for information on message level properties that can be used as options.

Option

Data Type

Value Domain

Default Value

Description

Transport Binding/Protocol Related Options
"log_file" scalar /tmp/wsf_perl_client.log The name of the log file that the client log messages would get logged into.

"useSOAP"

scalar

"TRUE" | "FALSE" | "true" | "false" |
"1.1" | "1.2"

TRUE

Specifies whether to use SOAP bindings, or not. If "FALSE", a REST style invocation will take place with the given HTTP method as specified by the "HTTPMethod" option. "1.1" would make the message use SOAP 1.1. "1.2" would make the message use SOAP 1.2. "TRUE" means use SOAP 1.2.

"HTTPMethod"

scalar

"GET" | "POST" | "post" | "get"

"POST"

Specifies which HTTP method to be used.

XOP/MTOM Related Options

"useMTOM"

scalar

"TRUE" | "FALSE" | "true" | "false"

"TRUE"

Indicates whether the attachments should be sent MTOM optimized or not. If "TRUE", the attachments will be sent out of the SOAP message, optimized, with MIME headers in place. If "FALSE", attachments will be sent within the SOAP payload, as base64 binary.

"responseXOP"

scalar

"TRUE" | "FALSE" | 1 | 0

"FALSE"

Controls whether XOP elements in a response with MTOM are resolved into the logically equivalent straight XML infoset or not. If "TRUE", the options "attachments" and "cid_2_content_type" of the message returned as a result of the calling request method would be set. If "FALSE", the binary content will be present in the response payload in base64 format.

WS-Addressing Related Options

"useWSA"

scalar

"TRUE" | "FALSE" |  "1.0" | "submission"

"1.0"

Indicates whether to use WS-Addressing. If "TRUE", or "1.0", the WS-Addressing 1.0 version will be used. If "submission" the WS-Addressing submission version will be used. When "1.0" or "submission" is specified, the "action" must be present. If "FALSE", no addressing headers will be sent.
WS-Security Related Options
"policy" WSPolicy object WSPolicy object None WSPolicy Object
"securityToken" WSSecurityToken None WSSecurityToken object which contain the security related options
Proxy and SSL settings related properties
"proxy_host" scalar scalar None proxy host to be used.
"proxy_port" scalar scalar None proxy port to use.

Methods

Sends a request payload in XML format and receives a response payload in the XML format.

Parameters:

Parameter

Description

message

The request message payload to be sent. The type of the parameter can be any one of the following types:

  • String

  • WSMessage

The message payload is expected to be in valid XML format as expected by the service. If MTOM/XOP is to be used, you must use WSMessage to represent the message payload.

Return Values:

The response will be returned as a WSMessage object instance.

Throws WSFault on error.


Sends a request message payload in XML. The invocation model is one way, hence no response will be expected.

Parameters:

Parameter

Description

message

The request message payload to be sent. The type of the parameter can be any one of the following types:

  • String

  • WSMessage

The message payload is expected to be in valid XML format as expected by the service. If MTOM/XOP is to be used, you must use WSMessage to represent the message payload.

Return Values:

void

Throws WSFault on error.

Member Variables

None

Example

my $reqest_payload = '
        <ns1:echoString xmlns:ns1="http://perl.wsf.wso2.net/samples">
            <text>Hello World!</text>
        </ns1:echoString>
';

my $client = new WSO2::WSF::WSClient( { 'to' => 'http://localhost/hello_service/greet' } );

my $request = $client->request( { 'payload' => $request_payload } );

print $request->{str};


WSMessage

The WSMessage class represents a message passed between a client and a service. This class encapsulates the XML payload, the WS-Addressing action information related to the message, the MTOM attachment data, and other properties related to a message.

Constructor

Constructs a new WSMessage object.

Parameters:

Parameter

Default Value

Description

payload

None

A string representing the payload being sent or being received. The payload is expected to be in valid XML format as expected by the service.

properties

A hash of properties.

The following table shows the possible message level properties and related details.

Option

Data Type

Value Domain

Default Value

Description

General Properties:

"to"

scalar

A URI

None

A URI representing the endpoint URI of the service to be consumed. This must be present on the server side. In case WS-Addressing is in use, this will be used as the WSA "to" header

WS-Addressing Related Properties:

"action"

scalar

A URI

None

xs:anyURI
The WS-A action to use when constructing the WS-A headers. A URI representing the WSA action that helps uniquely identify the operation to be invoked. This is also used as the SOAP Action regardless of whether the useWSA option is specified or not.

"from"

scalar

A URI

None

xs:anyURI

WS-Addressing From. A URI indicating where the response or request came from.(Note: This doesn't support reference parameters.)

"replyTo"

scalar

A URI

None

xs:anyURI

WS-Addressing ReplyTo. A URI indicating where the response should be sent to. The default value is the anonymous URI (depending on the version). (Note: This doesn't support reference parameters.)

"faultTo"

scalar

A URI

None

xs:anyURI

WS-Addressing FaultTo. A URI indicating where the fault should be sent to in case of an error. (Note: This doesn't support reference parameters.)

XOP/MTOM Related Properties:

"default_attachment_content_type"

scalar

MTOM content type

"application/octet-stream"

Specify a default MTOM content type to be used with MTOM attachments. You can also specify xmlmime:contentType on the xop:Include element, which will override this setting.

WSFault

Constructor

Constructs a new WSFault object.

Parameters:

Parameter

Default Value

Description

code

None

SOAP fault code. SOAP fault codes are intended to provide a means by which faults are classified.
Please see SOAP 1.2 spec for more information

reason

None

SOAP fault reason. Provides a human readable explanation of the fault.

role

""

SOAP fault role. Identifies the role in which the SOAP processing node was operating at the time the fault occurred.

detail

""

SOAP Fault detail. Contains application specific error information.

xml

""

SOAP fault as an XML string.

Members

Returns SOAP fault code as a string. SOAP fault codes are intended to provide a means by which faults are classified.

Returns SOAP fault reason as a string. Provides a human readable explanation of the fault.

Returns SOAP fault role as a string. Identifies the role in which the SOAP processing node was operating at the time the fault occurred.

Returns SOAP fault detail as a string. Contains application specific error information.

Returns the SOAP fault as an XML string.