https://github.com/mons/xml-rpc-fast

Fast and modular implementation for an XML-RPC client and server
https://github.com/mons/xml-rpc-fast

Last synced: 10 months ago
JSON representation

Fast and modular implementation for an XML-RPC client and server

• Host: GitHub
• URL: https://github.com/mons/xml-rpc-fast
• Owner: Mons
• License: other
• Created: 2011-02-04T11:21:48.000Z (over 15 years ago)
• Default Branch: master
• Last Pushed: 2012-07-19T11:41:06.000Z (almost 14 years ago)
• Last Synced: 2023-03-10T20:33:18.820Z (over 3 years ago)
• Language: Perl
• Homepage: http://search.cpan.org/dist/XML-RPC-Fast
• Size: 887 KB
• Stars: 2
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

          
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 $/;  };

        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  to report and view bugs.

AUTHOR

    Mons Anderson, ""

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.