1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
NAME
XML::RPC::Fast - Fast and modular implementation for an XML-RPC client
and server
SYNOPSIS
Generic usage
use XML::RPC::Fast;
my $server = XML::RPC::Fast->new( undef, %args );
my $client = XML::RPC::Fast->new( $uri, %args );
Create a simple XML-RPC service:
use XML::RPC::Fast;
my $rpc = XML::RPC::Fast->new(
undef, # the url is not required by server
external_encoding => 'koi8-r', # any encoding, accepted by Encode
#internal_encoding => 'koi8-r', # not supported for now
);
my $xml = do { local $/; <STDIN> };
length($xml) == $ENV{CONTENT_LENGTH} or warn "Content-Length differs from actually received";
print "Content-type: text/xml; charset=$rpc->{external_encoding}\n\n";
print $rpc->receive( $xml, sub {
my ( $methodname, @params ) = @_;
return { you_called => $methodname, with_params => \@params };
} );
Make a call to an XML-RPC service:
use XML::RPC::Fast;
my $rpc = XML::RPC::Fast->new(
'http://your.hostname/rpc/url'
);
# Syncronous call
my @result = $rpc->req(
call => [ 'examples.getStateStruct', { state1 => 12, state2 => 28 } ],
url => 'http://...',
);
# Syncronous call (compatibility method)
my @result = $rpc->call( 'examples.getStateStruct', { state1 => 12, state2 => 28 } );
# Syncronous or asyncronous call
$rpc->req(
call => ['examples.getStateStruct', { state1 => 12, state2 => 28 }],
cb => sub {
my @result = @_;
},
);
# Syncronous or asyncronous call (compatibility method)
$rpc->call( sub {
my @result = @_;
}, 'examples.getStateStruct', { state1 => 12, state2 => 28 } );
DESCRIPTION
XML::RPC::Fast is format-compatible with XML::RPC, but may use different
encoders to parse/compose xml. Curerntly included encoder uses
XML::LibXML, and is 3 times faster than XML::RPC and 75% faster, than
XML::Parser implementation
METHODS
new ($url, %args)
Create XML::RPC::Fast object, server if url is undef, client if url is
defined
req( %ARGS )
Clientside. Make syncronous or asyncronous call (depends on UA).
If have cb, will invoke $cb with results and should not croak
If have no cb, will return results and croak on error (only syncronous
UA)
Arguments are
call => [ methodName => @args ]
array ref of call arguments. Required
cb => $cb->(@results)
Invocation callback. Optional for syncronous UA. Behaviour is same
as in call with $cb and without
url => $request_url
Alternative invocation URL. Optional. By default will be used
defined from constructor
headers => { http-headers hashref }
Additional http headers to request
external_encoding => '...,
Specify the encoding, used inside XML container just for this
request. Passed to encoder
call( 'method_name', @arguments ) : @results
Clientside. Make syncronous call and return results. Croaks on error.
Just a simple wrapper around "req"
call( $cb->(@res), 'method_name', @arguments ): void
Clientside. Make syncronous or asyncronous call (depends on UA) and
invoke $cb with results. Should not croak. Just a simple wrapper around
"req"
receive ( $xml, $handler->($methodName,@args) ) : xml byte-stream
Serverside. Process received XML and invoke $handler with parameters
$methodName and @args and returns response XML
On error conditions $handler could set $XML::RPC::Fast::faultCode and
die, or return "rpcfault($faultCode,$faultString)"
->receive( $xml, sub {
# ...
return rpcfault( 3, "Some error" ) if $error_condition
$XML::RPC::Fast::faultCode = 4 and die "Another error" if $another_error_condition;
return { call => $methodname, params => \@params };
})
registerType
Proxy-method to encoder. See XML::RPC::Enc
registerClass
Proxy-method to encoder. See XML::RPC::Enc
OPTIONS
Below is the options, accepted by new()
ua
Client only. Useragent object, or package name
->new( $url, ua => 'LWP' ) # same as XML::RPC::UA::LWP
# or
->new( $url, ua => 'XML::RPC::UA::LWP' )
# or
->new( $url, ua => XML::RPC::UA::LWP->new( ... ) )
# or
->new( $url, ua => XML::RPC::UA::Curl->new( ... ) )
timeout
Client only. Timeout for calls. Passed directly to UA
->new( $url, ua => 'LWP', timeout => 10 )
useragent
Client only. Useragent string. Passed directly to UA
->new( $url, ua => 'LWP', useragent => 'YourClient/1.11' )
encoder
Client and server. Encoder object or package name
->new( $url, encoder => 'LibXML' )
# or
->new( $url, encoder => 'XML::RPC::Enc::LibXML' )
# or
->new( $url, encoder => XML::RPC::Enc::LibXML->new( ... ) )
internal_encoding NOT IMPLEMENTED YET
Specify the encoding you are using in your code. By default option is
undef, which means flagged utf-8 For translations is used Encode, so the
list of accepted encodings fully derived from it.
external_encoding
Specify the encoding, used inside XML container. By default it's utf-8.
Passed directly to encoder
->new( $url, encoder => 'LibXML', external_encoding => 'koi8-r' )
ACCESSORS
url
Get or set client url
encoder
Direct access to encoder object
ua
Direct access to useragent object
FUNCTIONS
rpcfault(faultCode, faultString)
Returns hash structure, that may be returned by serverside handler,
instead of die. Not exported by default
CUSTOM TYPES
sub {{ 'base64' => encode_base64($data) }}
When passing a CODEREF as a value, encoder will simply use the returned
hashref as a type => value pair.
bless( do{\(my $o = encode_base64('test') )}, 'base64' )
When passing SCALARREF as a value, package name will be taken as type
and dereference as a value
bless( do{\(my $o = { something =>'complex' } )}, 'base64' )
When passing REFREF as a value, package name will be taken as type and
XML::Hash::LX"::hash2xml(deref)" would be used as value
customtype( $type, $data )
Easily compose SCALARREF based custom type
BUGS & SUPPORT
Bugs reports and testcases are welcome.
It you write your own Enc or UA, I may include it into distribution
If you have propositions for default custom types (see Enc), send me
patches
See <http://rt.cpan.org> to report and view bugs.
AUTHOR
Mons Anderson, "<mons@cpan.org>"
COPYRIGHT & LICENSE
Copyright (c) 2008-2009 Mons Anderson.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
|
