SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

Event::RPC::Client

Section: User Contributed Perl Documentation (3)
Updated: 2008-10-25
Index 

NAME

Event::RPC::Client - Client API to connect to Event::RPC Servers 

SYNOPSIS

  use Event::RPC::Client;  my $rpc_client = Event::RPC::Client->new (    #-- Required arguments    host => "localhost",    port => 5555,        #-- Optional arguments    classes   => [ "Event::RPC::Test" ],    class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" },    ssl       => 1,    timeout   => 10,    auth_user => "fred",    auth_pass => Event::RPC->crypt("fred",$password),    error_cb => sub {      my ($client, $error) = @_;      print "An RPC error occured: $error\n";      $client->disconnect;      exit;    },  );  $rpc_client->connect;    #-- And now use classes and methods the server  #-- allows to access via RPC, here My::TestModule  #-- from the Event::RPC::Server manpage SYNPOSIS.  my $obj = My::TestModule->new( data => "foobar" );  print "obj says hello: ".$obj->hello."\n";  $obj->set_data("new foobar");  print "updated data: ".$obj->get_data."\n";  $rpc_client->disconnect;
 

DESCRIPTION

Use this module to write clients accessing objects and methodsexported by a Event::RPC driven server.

Just connect to the server over the network, optionally withSSL and user authentication, and then simply use the exported classesand methods like having them locally in the client.

General information about the architecture of Event::RPC drivenapplications is collected in the Event::RPC manpage.

The following documentation describes the client connectionoptions in detail. 

CONFIGURATION OPTIONS

You need to specify at least the server hostname and TCP portto connect a Event::RPC server instance. If the server requiresa SSL connection or user authentication you need to supplythe corresponding options as well, otherwise connecting willfail.

All options described here may be passed to the new() constructor ofEvent::RPC::Client. As well you may set or modify them using set_OPTION stylemutators, but not after connect() was called!All options may be read using get_OPTION style accessors. 

REQUIRED OPTIONS

These are necessary to connect the server:
server
This is the hostname of the server running Event::RPC::Server.Use a IP address or DNS name here.
port
This is the TCP port the server is listening to.
 

NETWORK OPTIONS

timeout
Specify a timeout (in seconds), which is applied when connectingthe server.
 

CLASS IMPORT OPTION

classes
This is reference to a list of classes which should be importedinto the client. You get a warning if you request a class whichis not exported by the server.

By default all server classes are imported. Use this feature ifyour server exports a huge list of classes, but your clientdoesn't need all of them. This saves memory in the client andconnect performance increases.

class_map
Optionally you can map the class names from the server to adifferent name on the local client using the class_map hash.

This is necessary if you like to use the same classes locallyand remotely. Imported classes from the server are by defaultregistered under the same name on the client, so this conflictswith local classes named identically.

On the client you access the remote classes under the nameassigned in the class map. For example with this map

  class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" }

you need to write this on the client, if you like to createan object remotely on the server:

  my $server_job = _srv::Event::ExecFlow::Job->new ( ... );

and this to create an object on the client:

  my $client_job = Event::ExecFlow::Job->new ( ... );

The server knows nothing of the renaming on client side, so youstill write this on the server to create objects there:

  my $job = Event::ExecFlow::Job->new ( ... );
 

SSL OPTION

If the server accepts only SSL connections you need to enablessl here in the client as well:
ssl
Set this option to 1 to encrypt the network connection using SSL.
 

AUTHENTICATION OPTIONS

If the server requires user authentication you need to setthe following options:
auth_user
A valid username.
auth_pass
The corresponding password, encrypted using Perl's crypt() function,using the username as the salt.

Event::RPC has a convenience function for generating such a cryptedpassword, although it's currently just a wrapper around Perl'sbuiltin crypt() function, but probably this changes someday, so betteruse this method:

  $crypted_pass = Event::RPC->crypt($user, $pass);

If the passed credentials are invalid the Event::RPC::Client->connect()method throws a correspondent exception. 

ERROR HANDLING

Any exceptions thrown on the server during execution of a remotemethod will result in a corresponding exception on the client. Soyou can use normal exception handling with eval {} when executingremote methods.

But besides this the network connection between your client andthe server may break at any time. This raises an exception as well,but you can override this behaviour with the following attribute:

error_cb
This subroutine is called if any error occurs in the networkcommunication between the client and the server. The actualEvent::RPC::Client object and an error string are passedas arguments.

This is no generic exception handler for exceptions thrown from theexecuted methods on the server! If you like to catch suchexceptions you need to put an eval {} around your method calls,as you would do for local method calls.

If you don't specify an error_cb an exception is thrown instead.

 

METHODS

$rpc_client->connect
This establishes the configured connection to the server. An exceptionis thrown if something goes wrong, e.g. server not available, credentialsare invalid or something like this.
$rpc_client->disconnect
Closes the connection to the server. You may omit explicit disconnectingsince it's done automatically once the Event::RPC::Client object getsdestroyed.
 

READY ONLY ATTRIBUTES

$rpc_client->get_server_version
Returns the Event::RPC version number of the server after connecting.
$rpc_client->get_server_protocol
Returns the Event::RPC protocol number of the server after connecting.
$rpc_client->get_client_version
Returns the Event::RPC version number of the client.
$rpc_client->get_client_protocol
Returns the Event::RPC protocol number of the client.
 

AUTHORS

  Jo.rn Reder <joern at zyn dot de>
 

COPYRIGHT AND LICENSE

Copyright (C) 2002-2006 by Joern Reder, All Rights Reserved.

This library is free software; you can redistribute itand/or modify it under the same terms as Perl itself.


 

Index

NAME
SYNOPSIS
DESCRIPTION
CONFIGURATION OPTIONS
REQUIRED OPTIONS
NETWORK OPTIONS
CLASS IMPORT OPTION
SSL OPTION
AUTHENTICATION OPTIONS
ERROR HANDLING
METHODS
READY ONLY ATTRIBUTES
AUTHORS
COPYRIGHT AND LICENSE

This document was created byman2html,using the manual pages.