Reliable Messaging API manual

Wsf4php extension supports reliable messaging protocal version 1.0 now. For the beta release, both 1.0 and 1.1 will be supported. One way as well as two way reliable messaging is supported using single channel.

1.0 How to configure WSO2 WSF/PHP to use reliable messaging

We assume that you have installed the WSO2 WSF/PHP.

To implement reliable messaging wsf-php uses a database system to store state information related to messaging and for that two data base systems supported. They are sqlite3 and mysql. 

Using WSO2 WSF/PHP with sqlite3

you will need to have sqlite3 installed on your machine.

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

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

Using wsf/php with MySql for reliable messaging

You will need to have MySql database installed on your machine. You will find the relevent scripts to create the database tables and user account

in <WSO2 WSF/PHP>\wsf_c\bin\sandesha2. First  please create a user in MySql using the instructions in create_mysql_user.txt file. There the user account name is refered as 'g'. Then use init_mysql.bat file to create the database tables. Next you will need to build wsf/php with MySql enabled by specifying the optons WITH_MYSQL=1.

 

2.0 Writing a RM Web Service Client.

Since WS Addressing is needed WSRM to work, you need to specify the necessary WS addressing options along with RM Options. Lets implement the simplest rm client that can be written using WSO2 WSF/PHP.

First create a suitable payload to be send 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 addressing action is present, Addressing will be enabled with "reliable"=>TRUE option. This client will create an RM Sequence, send its only application message and terminate the sequence.

If you wish to send multiple application messages reliably to the reciving 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 a default sequenceExpiryTime. You can configure this value using "sequenceExpiryTime" option in WSClient. So we send the $msg2 using the currently opened sequence. On $msg3 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.

3.0 Writing a  RM Web Service

Following code demostrate how to write an rm Web Service client. 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 above eample client.

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