Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Event::RPC::Client(3) User Contributed Perl DocumentationEvent::RPC::Client(3)

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,
	   ssl_ca_file => "some/ca.crt",
	   ssl_ca_path => "some/ca/dir",

	   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 OPTIONS
       If the server accepts only SSL connections you need to enable ssl here
       in the client as	well. By default the SSL connection will be
       established without any peer verification, which	makes Man-in-the-
       Middle attacks possible.	If you want to prevent that, you need to set
       either ssl_ca_file or ssl_ca_path option.

       ssl Set this option to 1	to encrypt the network connection using	SSL.

       ssl_ca_file
	   Path	to the the Certificate Authority's certificate file (ca.crt),
	   your	server key was signed with.

       ssl_ca_path
	   Path	of a directory containing several trusted certificates with a
	   proper index. Please	refer to the OpenSSL documentation for details
	   about setting up such a directory.

   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<paragraph>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 it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 714:
	   Non-ASCII character seen before =encoding in	'JA<paragraph>rn'.
	   Assuming CP1252

perl v5.32.0			  2013-02-02		 Event::RPC::Client(3)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION OPTIONS | METHODS | READY ONLY ATTRIBUTES | AUTHORS | COPYRIGHT AND LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Event::RPC::Client&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help