1Event::RPC::Client(3) User Contributed Perl DocumentationEvent::RPC::Client(3)
2
6 Event::RPC::Client - Client API to connect to Event::RPC Servers
7
9 use Event::RPC::Client;
10 my $rpc_client = Event::RPC::Client->new (
12 #-- Required arguments
13 host => "localhost",
14 port => 5555,
15 #-- Optional arguments
17 classes => [ "Event::RPC::Test" ],
18 class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" },
19 ssl => 1,
21 timeout => 10,
22 auth_user => "fred",
24 auth_pass => Event::RPC->crypt("fred",$password),
25 error_cb => sub {
27 my ($client, $error) = @_;
28 print "An RPC error occured: $error\n";
29 $client->disconnect;
30 exit;
31 },
32 );
33 $rpc_client->connect;
35 #-- And now use classes and methods the server
37 #-- allows to access via RPC, here My::TestModule
38 #-- from the Event::RPC::Server manpage SYNPOSIS.
39 my $obj = My::TestModule->new( data => "foobar" );
40 print "obj says hello: ".$obj->hello."\n";
41 $obj->set_data("new foobar");
42 print "updated data: ".$obj->get_data."\n";
43 $rpc_client->disconnect;
45
47 Use this module to write clients accessing objects and methods exported
48 by a Event::RPC driven server.
49 Just connect to the server over the network, optionally with SSL and
51 user authentication, and then simply use the exported classes and
52 methods like having them locally in the client.
53 General information about the architecture of Event::RPC driven
55 applications is collected in the Event::RPC manpage.
56 The following documentation describes the client connection options in
58 detail.
59
61 You need to specify at least the server hostname and TCP port to
62 connect a Event::RPC server instance. If the server requires a SSL
63 connection or user authentication you need to supply the corresponding
64 options as well, otherwise connecting will fail.
65 All options described here may be passed to the new() constructor of
67 Event::RPC::Client. As well you may set or modify them using set_OPTION
68 style mutators, but not after connect() was called! All options may be
69 read using get_OPTION style accessors.
70 REQUIRED OPTIONS
72 These are necessary to connect the server:
73 server
75 This is the hostname of the server running Event::RPC::Server. Use
76 a IP address or DNS name here.
77 port
79 This is the TCP port the server is listening to.
80 NETWORK OPTIONS
82 timeout
83 Specify a timeout (in seconds), which is applied when connecting
84 the server.
85 CLASS IMPORT OPTION
87 classes
88 This is reference to a list of classes which should be imported
89 into the client. You get a warning if you request a class which is
90 not exported by the server.
91 By default all server classes are imported. Use this feature if
93 your server exports a huge list of classes, but your client doesn't
94 need all of them. This saves memory in the client and connect
95 performance increases.
96 class_map
98 Optionally you can map the class names from the server to a
99 different name on the local client using the class_map hash.
100 This is necessary if you like to use the same classes locally and
102 remotely. Imported classes from the server are by default
103 registered under the same name on the client, so this conflicts
104 with local classes named identically.
105 On the client you access the remote classes under the name assigned
107 in the class map. For example with this map
108 class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" }
110 you need to write this on the client, if you like to create an
112 object remotely on the server:
113 my $server_job = _srv::Event::ExecFlow::Job->new ( ... );
115 and this to create an object on the client:
117 my $client_job = Event::ExecFlow::Job->new ( ... );
119 The server knows nothing of the renaming on client side, so you
121 still write this on the server to create objects there:
122 my $job = Event::ExecFlow::Job->new ( ... );
124 SSL OPTION
126 If the server accepts only SSL connections you need to enable ssl here
127 in the client as well:
128 ssl Set this option to 1 to encrypt the network connection using SSL.
130 AUTHENTICATION OPTIONS
132 If the server requires user authentication you need to set the
133 following options:
134 auth_user
136 A valid username.
137 auth_pass
139 The corresponding password, encrypted using Perl's crypt()
140 function, using the username as the salt.
141 Event::RPC has a convenience function for generating such a crypted
143 password, although it's currently just a wrapper around Perl's
144 builtin crypt() function, but probably this changes someday, so
145 better use this method:
146 $crypted_pass = Event::RPC->crypt($user, $pass);
148 If the passed credentials are invalid the Event::RPC::Client->connect()
150 method throws a correspondent exception.
151 ERROR HANDLING
153 Any exceptions thrown on the server during execution of a remote method
154 will result in a corresponding exception on the client. So you can use
155 normal exception handling with eval {} when executing remote methods.
156 But besides this the network connection between your client and the
158 server may break at any time. This raises an exception as well, but you
159 can override this behaviour with the following attribute:
160 error_cb
162 This subroutine is called if any error occurs in the network
163 communication between the client and the server. The actual
164 Event::RPC::Client object and an error string are passed as
165 arguments.
166 This is no generic exception handler for exceptions thrown from the
168 executed methods on the server! If you like to catch such
169 exceptions you need to put an eval {} around your method calls, as
170 you would do for local method calls.
171 If you don't specify an error_cb an exception is thrown instead.
173
175 $rpc_client->connect
176 This establishes the configured connection to the server. An
177 exception is thrown if something goes wrong, e.g. server not
178 available, credentials are invalid or something like this.
179 $rpc_client->disconnect
181 Closes the connection to the server. You may omit explicit
182 disconnecting since it's done automatically once the
183 Event::RPC::Client object gets destroyed.
184
186 $rpc_client->get_server_version
187 Returns the Event::RPC version number of the server after
188 connecting.
189 $rpc_client->get_server_protocol
191 Returns the Event::RPC protocol number of the server after
192 connecting.
193 $rpc_client->get_client_version
195 Returns the Event::RPC version number of the client.
196 $rpc_client->get_client_protocol
198 Returns the Event::RPC protocol number of the client.
199
201 JA~Xrn Reder <joern at zyn dot de>
202
204 Copyright (C) 2002-2006 by Joern Reder, All Rights Reserved.
205 This library is free software; you can redistribute it and/or modify it
207 under the same terms as Perl itself.
208perl v5.12.0 2008-10-25 Event::RPC::Client(3)