9. Reliable Messaging Manual

The WSO2 WSF/PHP extension supports reliable messaging (RM) protocol versions 1.0 and 1.1. It also supports one way as well as two way reliable messaging.

9.1. How to Configure WSO2 WSF/PHP to use Reliable Messaging

To implement reliable messaging, WSO2 WSF/PHP uses a database system to store state information related to messaging. Two DBMS systems are supported, SQLite and MySQL.

Using WSO2 WSF/PHP with SQLite

You will need to have SQLite version 3 installed on your machine.

Note: For the Windows binary, the SQLite3 binary and executable will be packed with the WSO2 WSF/PHP binary. So what you will need is to add the <WSO2 WSF/PHP>\wsf_c\lib directory to the path.

You will find a script (sqlite_schema.sh | sqlite_schema.bat )  for creating the databases that are used by WSO2 WSF/PHP in the <WSO2 WSF/PHP> directory. Make sure to run this script before starting the server. When you run this script, it will create two database files "sandesha2_client_db" and "sandesha2_svr_db" in the directory where you executed the script. For Linux, put these databases to your Linux environment's /tmp directory, and these files should have the read and write permissions for the user that runs your Web server.

On Windows, add the following php.ini entry.

wsf.rm_db_dir=<database location>

You can do the same on Linux if you have provided proper read and write permissions.

Using WSO2 WSF/PHP with MySQL

You will need to have the MySQL database installed on your machine. You will find the relevant scripts to create the database tables and the user account in <WSO2 WSF/PHP>\wsf_c\bin\sandesha2. First  create a user in MySQL using the instructions in the create_mysql_user.txt file. There the user account name is referred to as 'g'. Then use init_mysql.bat or init_mysql.sh file to create the database tables. Next you will need to build WSO2 WSF/PHP with MySQL enabled by specifying the option WITH_MYSQL=1 on Windows or --enable-mysql on Linux.

 

9.2. Writing RM Enabled Web Service Client.

Since WS-Addressing is required for WS-RM to work, you need to specify the necessary WS-Addressing options along with RM Options. Let's implement a simple RM client with WSO2 WSF/PHP.

First create a suitable payload to be sent to the echo service.

$req_payload_string =  <<<XML <ns1:echoString xmlns="http://www.wsf.org/echo/echoString"><text>Hello RM!</text></ns1:echoString>XML;

try {

          $msg =   new WSMessage($reqPayloadString,  array("action" => "http://php.axis2.org/samples/echoString") );

          $client = new WSClient(array( "to"=>"http://localhost/echo_service_rm.php", "reliable"=>TRUE));

          $result = $client->request($msg);

          echo $result->str;

} catch (Exception $e) { 

           if ($e instanceof WSFault) {

               printf("Soap Fault: %s\n", $e->code);

          } else {

         printf("Message = %s\n",$e->getMessage()); }

}

Note that we set the addressing action in WSMessage options and "reliable"=>TRUE option in WSClient options to enable RM. Since the WS-Addressing action is present, addressing will be enabled with "reliable"=>TRUE option. This client will create an RM Sequence, send its application message and terminate the sequence.

If you wish to send multiple application messages reliably to the receiving RM endpoint, you can configure the above Web service client as follows.

          $msg0 =   new WSMessage($reqPayloadString,  array("action" => "http://php.axis2.org/samples/echoString") );

          $msg1 = new WSMessage($reqPayloadString, array("action"=>"http://php.axis2.org/samples/echoString"));

          $msg2 = new WSMessage($reqPayloadString, array("action"=>"http://php.axis2.org/samples/echoString",                                                                                                                                "lastMessage"=>TRUE));

          $client = new WSClient(array( "to"=>"http://localhost:8080/echo_service_rm.php",

                                                      "reliable"=>TRUE,

                                                      "willContinueSequence"=>TRUE));

          $result = $client->request($msg0);

          $client->request($msg1);

          $client->request($msg2);

Since we specified "willContinueSequence"=>TRUE option in WSClient , it will not terminate the sequence after sending the first message. It keeps the sequence open till the default sequenceExpiryTime expires. You can configure this value using the "sequenceExpiryTime" option in WSClient. So we send the $msg1 using the currently opened sequence. On $msg2 we specify that this will be the last message that will be sent using the current sequence using the option "lastMessage"=>TRUE. Now WSClient will terminate the current sequence after sending $msg2.

9.3. Writing RM Enabled Web Service

The following code demonstrates how to write a RM Web service. This echo_service_rm.php was used as the above client's receiving endpoint.

function echoFunction($inMessage){

         return new WSMessage($inMessage->str);

}

$operations = array("echoString" => "echoFunction");

$actions      = array("http://php.axis2.org/samples/echoString"=>"echoString");

$service = new WSService(array("operations"=>$operations,

                                                 "reliable"=>TRUE));

$service->reply();

Note how we map "echoString" operation to "http://php.axis2.org/samples/echoString"  which is the same action URI used in the above example client.

On WSService options, "reliable"=>TRUE option is used to tell the service to use the RM protocol.