-------------------------------------------------------------------
Required libraries :

      this demo use xml-rpc protocol to connect to xmlBlaster server.
      the xml-rpc implementation used in this demo is Frontier.

      - XML Expat
      install expat (expat-1.95.2 at http://sourceforge.net/projects/expat/)
      on my linux redhat 7.2 it was already installed.
      
      - perl XML Parser :
      perl module XML-Parser (XML-Parser.2.30 at http://search.cpan.org/search?dist=XML-Parser)

      - perl XMLRPC :
      xml-rpc implemeted by Frontier (Frontier-RPC-x.xx).
      Look at CPAN for this package or
      http://bitsko.slc.ut.us/~ken/xml-rpc/
      (Frontier-RPC-0.07b4.tar.gz)
      cpan Frontier::Daemon
      (cpan Frontier::Daemon::Forking)
-------------------------------------------------------------------

-------------------------------------------------------------------
Howto start the Perl/XmlRpc demo:

 - Start xmlBlaster (with xmlrpc dumping switched on)

      cd xmlBlaster
      java -jar lib/xmlBlaster.jar -plugin/xmlrpc/debug true


 - Run a Perl demo client :

      (1) cd xmlBlaster/demo/perl/xmlrpc

      (2) hello.pl

      It will try to lookup xmlBlaster on the same machine, or try

      (3) perl hello.pl http://myHost:8080/

      If xmlBlaster is running on 'myHost'


 - Run another Perl demo client : xmlBlasterClient.pl

      1/ cd xmlBlaster/demo/perl/xmlrpc

      perl  xmlBlasterClient.pl  myhost:port

      2/ if it doesn't work, look at the file xmlBlasterClient.pl
      The only 2 configuration stuff are :
        authentification type (plugin default is htpasswd )
        two valid users on xmlBlaster server (default users are guest & admin ).

 - Run another Perl demo client : messagesList.pl

      1/ cd xmlBlaster/demo/perl/xmlrpc

      perl  messagesList.pl  myhost:port

      It will try to get all messages actually in xmlBlaster server.

Thats it!
-------------------------------------------------------------------



-------------------------------------------------------------------
Playing with the Frontier-XmlRpc command line client rpc-client.pl:

1. Create a login session (we need the sessionId):

   perl rpc-client.pl http://myHost:8080/RPC2 authenticate.login "marcel, secret, <qos/>,  ab123"

Somewhere the secret sessionId is returned like "sessionId:192.168.1.4-null-1064571259045-162717338-6"
(See xmlBlaster/src/java/org/xmlBlaster/protocol/xmlrpc/AuthenticateImpl.java for supported methods)

2. Now access the free memory in the server:

   perl rpc-client.pl http://myHost:8080/RPC2 xmlBlaster.get "'sessionId:192.168.1.4-null-1064571396303--606564280-8', '<key oid=\'__sys__freeMem\'/>', <qos/>"

Somewhere "$result = ARRAY(0x85402b0)" is returned which would
need to be inspected by Data::Dumper or as in MsgUnit.pm
(See xmlBlaster/src/java/org/xmlBlaster/protocol/xmlrpc/XmlBlasterImpl.java for supported methods)
-------------------------------------------------------------------


This is the simplest Perl client code:
-------------------------------------------------------------------
use Frontier::Client;
use Data::Dumper;

# Make an object to represent the XMLRPC server.
$server_url = 'http://myHost:8080/';
print "\nTrying to connect to xmlBlaster server on $server_url ...\n";

$server = Frontier::Client->new(url => $server_url);
print "Connected to xmlBlaster server on $server_url \n";

# Call the remote server and get our result.
$sessionId = $server->call('authenticate.login', "ben", "secret", "<qos></qos>", "");
print "\nLogin success with sessionId=$sessionId \n";

# Call the server and get its current memory consumption.
$message = $server->call('xmlBlaster.get', $sessionId, "<key oid='__cmd:?totalMem'></key>", "<qos></qos>");
print "\nResult for a get():\n----------------\n Dumper($message) \n----------------\n";
-------------------------------------------------------------------

See
   xmlBlaster/src/java/org/xmlBlaster/protocol/xmlrpc/XmlBlasterImpl.java
with all allowed server-methods you can invoke.

-------------------------------------------------------------------
CHANGES :

2004-08-30 Jason Martin <jhmartin@toger.us>
   * Print out Header / Messages / Qos of update messages.
   * Add a retries and delay option to the subscribe/callback tag to reduce
     the chance xmlblaster will attempt to ping the callback server
     before it is created and thus unsubscribe it.
   * Add ReuseAddr => 1 to the Frontier::Daemon invocation to
     prevent "Address already in use" errors due to TIME_WAIT's when
     the script is killed and restarted quickly.
   * Print out an error message if the xmlrpc server does not start
     properly.
   * Add commenting for the above.

2002-07-08 cyrille@ktaland.com
        - put xmlBlaster's perl packages in a folder
        - all xml-rpc calls are encapsuled in a XmlBlaster package.

2002-02-12 cyrille@ktaland.com

add demo scripts :
        xmlBlasterClient.pl
        messagesList.pl

and some packages to help in managing xmlBlaster stuff :
        messageUnit.pm : manage MsgUnit
        connectQos.pm : manage connectQos
        Exception.pm : not xmlBlaster specific, it's my Exception like management package.