Event::RPC::Client(3) User Contributed Perl DocumentationEvent::RPC::Client(3)NAMEEvent::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 methods exported
by a Event::RPC driven server.
Just connect to the server over the network, optionally with SSL and
user authentication, and then simply use the exported classes and
methods like having them locally in the client.
General information about the architecture of Event::RPC driven
applications is collected in the Event::RPC manpage.
The following documentation describes the client connection options in
detail.
CONFIGURATION OPTIONS
You need to specify at least the server hostname and TCP port to
connect a Event::RPC server instance. If the server requires a SSL
connection or user authentication you need to supply the corresponding
options as well, otherwise connecting will fail.
All options described here may be passed to the new() constructor of
Event::RPC::Client. As well you may set or modify them using set_OPTION
style mutators, 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 connecting
the server.
CLASS IMPORT OPTION
classes
This is reference to a list of classes which should be imported
into the client. You get a warning if you request a class which is
not exported by the server.
By default all server classes are imported. Use this feature if
your server exports a huge list of classes, but your client doesn't
need all of them. This saves memory in the client and connect
performance increases.
class_map
Optionally you can map the class names from the server to a
different name on the local client using the class_map hash.
This is necessary if you like to use the same classes locally and
remotely. Imported classes from the server are by default
registered under the same name on the client, so this conflicts
with local classes named identically.
On the client you access the remote classes under the name assigned
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 create an
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 you
still 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 enable ssl 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 set the
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 crypted
password, although it's currently just a wrapper around Perl's
builtin crypt() function, but probably this changes someday, so
better use 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 remote method
will result in a corresponding exception on the client. So you can use
normal exception handling with eval {} when executing remote methods.
But besides this the network connection between your client and the
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 network
communication between the client and the server. The actual
Event::RPC::Client object and an error string are passed as
arguments.
This is no generic exception handler for exceptions thrown from the
executed methods on the server! If you like to catch such
exceptions 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
exception is thrown if something goes wrong, e.g. server not
available, credentials are invalid or something like this.
$rpc_client->disconnect
Closes the connection to the server. You may omit explicit
disconnecting since it's done automatically once the
Event::RPC::Client object gets destroyed.
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
JA~Xrn 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 it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2008-10-25 Event::RPC::Client(3)
