Debian Codegraph @

README

raw
1 NAME
2 XML::RPC::Fast - Fast and modular implementation for an XML-RPC client
3 and server
4
5 SYNOPSIS
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
62 DESCRIPTION
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
68 METHODS
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
131 OPTIONS
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
175 ACCESSORS
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
185 FUNCTIONS
186 rpcfault(faultCode, faultString)
187 Returns hash structure, that may be returned by serverside handler,
188 instead of die. Not exported by default
189
190 CUSTOM 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
206 BUGS & 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
216 AUTHOR
217 Mons Anderson, "<[email protected]>"
218
219 COPYRIGHT & 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