NAME

xDash::Receiver - Module for Receiver's client script implementation

SYNOPSIS

 #!/usr/bin/perl 
 # xDash - Asynchronus Messaging and Instant Messaging reunited

 #===
 package EventLogger;
 use base xDash::Logger::File;
 # Check the correct file path for logger (absolute path if daemon!) and
 # Uncomment 1.line and comment out 2.line below after debugging.
 # sub Open { shift->SUPER::Open( '/home/xdash/receiver/event.log' ) }
 sub Open { shift->SUPER::Open( STDOUT ) }

 package ErrorLogger;
 use base xDash::Logger::File;
 # Check the correct file path for logger (absolute path if daemon!) and
 # Uncomment 1.line and comment out 2.line below after debugging.
 # sub Open { shift->SUPER::Open( '/home/xdash/receiver/error.log' ) }
 sub Open { shift->SUPER::Open( STDERR ) }

 package MessageLogger;
 # Uncomment the 1.line and comment out 2.&3.line below after debugging.
 # use base xDash::Logger::Dumb;
 use base xDash::Logger::File;
 sub Open { shift->SUPER::Open( STDOUT ) }
 #===

 package main;
 use strict;
 use warnings;
 use xDash::Receiver;
 
 # Establish first local communication to the application receiving jobs
 # (die, if not possible) and then...

 my $receiver = new xDash::Receiver;

 # After debugging change:
 # daemon => 1, for running as daemon (daemon => 0, console usage)
 # delay => 10, for waiting 10 seconds before becomming a daemon
 # timeout => 100, for waiting 100 seconds to try to reconnect
 # Test settings:
 $receiver->SetMode( daemon=> 0, delay=> 0, timeout=> 5 );

 # Parameters from receiver.xml and default connection parameters 
 # from package Net::Jabber::Client (::Connect()) can be overriden here:
 #      hostname => string, port => integer,
 #      connectiontype => tcpip|http, ssl => 0|1
 # Uncomment if needed, method is optional.
 # $receiver->SetConnectionParameters( ... => ... , );

 # Set Subject to everything, what helps to track better jobs
 # (below alias name from the archiv database).
 $receiver->SetJobSubject( 'receiver_1' );

 # Initiate receiver and Archivist JIDs (absolute path if daemon!)
 $receiver->SetParticipants( '/home/xdash/receiver/receiver.xml' );

 # Set job callback function for incomming jobs
 # (You habe to implement you own job handling - see some lines below...).
 $receiver->SetJobCallback( \&job_execution );

 # Go on ...
 $receiver->Process();

 #===========
 #  CUSTOM: This should be implemented as the script doing integration
 #===========
    
 sub job_execution {
    
     # Unique ID of the transported data
     my $thread = shift;  
    
     # Data transported inside of the message from Sender
     my $job = shift; 
            
     # Use for critical part of the internal script: eval{...}; if($!){...} 
     eval { 
      print "\n THIS JOB EXECUTION SCRIPT NEEDS STILL TO BE IMPLEMENTED !!!\n\n"
     };
     if ($!) { print "Ups, some error...!\n"};
    
     # If everything OK make return without any parameters or
     # only optional response of your choice:
     
     return { response => '  ~{:-)  ' };
        
     # if the were some troubles:
     return { 

            # Beware of jabber internal error codes: 400-409, 500-510
            # carried also by the coresponding jabber message tag    
            error_code => '1001',

            # Your optional error description
            error => 'hocus pocus',

            # Your optional response
            response => '  ~{:-(  '
            }
 }

DESCRIPTION

USAGE

For detailed description, how xDash framework works, please refer to http://xdash.jabberstudio.org.

A convenient way for using the module and auto generating Receiver's script is the utility xdscr from deployment directory. For script usage read the deployment/README.txt or usage information embedded into the script. The synopsis above is an example of the Receiver's client script generated by the xdscr. You can find an introduction to the deployment: Planning and deploying xDash in a sandbox at http://xdash.jabberstudio.org/deployment/perl.

The module is developed in the object orientated way. You have to provide base classes for logging tasks, which have to implement a fixed set of methods (driver pattern). You can use for logging xDash::Logger::File and xDash::Logger::Dumb in a way as it is proposed in the script generated by xdscr or provide your own implementation of the base class for EventLogger, ErrorLogger and MessageLogger. If you have to develop your own logger see, provided logger modules source code for further implementation hints. If you think, it can be reused, make it public over CPAN in the xDash::Logger namespace!

METHODS

SetMode( daemon=> 0|1, delay=> $time, timeout=> $time )

daemon => 1, for running script as daemon; daemon => 0, console usage of the script; delay=> $time, for waiting $time seconds before becoming a daemon; timeout => $time, for waiting $time seconds to try to reconnect.

SetConnectionParameters( hostname => $string, port => $integer, connectiontype => tcpip|http, ssl => 0|1 )

Overrides parameters <hostname> and <port> from the XML configuration file (usually receiver.xml) and default connection parameters from package Net::Jabber::Client (::Connect()). Method is optional.

SetJobSubject( $string )

Sets message subject to everything, what helps to track better jobs. Method is optional.

SetParticipants( $XML_configuration_file )

Initiate Receiver's and Archivist's JIDs with the absolute path to the XML configuration file, usually with the name receiver.xml.

SetJobCallback( \&job_execution )

Sets job callback function for incoming jobs as you have to implement you own job handling in the client script. Job thread and transported data (job) are passed as initial arguments to the registered function during the callback. For detailed example of the callback function see the script auto generated by the utility xdscr.

Process( )

Go on...

BUGS

Any suggestions for improvement are welcomed!

If a bug is detected or nonconforming behavior, please send an error report to <jwach@cpan.org>. Please attache log entries, if possible.

COPYRIGHT

Copyright 2005 Jerzy Wachowiak <jwach@cpan.org>

This library is free software; you can redistribute it and/or modify it under the terms of the Apache 2.0 license attached to the module.

SEE ALSO

xDash::Logger::File

xDash::Logger::Dumb

xDash::Sender

xDash::Archivist

http://xdash.jabberstudio.org