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