NAME

AnyEvent::JSONRPC::HTTP::Client - Simple HTTP-based JSONRPC client

SYNOPSIS

    use AnyEvent::JSONRPC::HTTP::Client;
    
    my $client = AnyEvent::JSONRPC::HTTP::Client->new(
        url      => 'http://rpc.example.net/issues',
        username => "pmakholm",
        password => "secret",
    );
    
    # blocking interface
    my $res = $client->call( echo => 'foo bar' )->recv; # => 'foo bar';
    
    # non-blocking interface
    $client->call( echo => 'foo bar' )->cb(sub {
        my $res = $_[0]->recv;  # => 'foo bar';
    });

DESCRIPTION

This module is the HTTP client part of the AnyEvent::JSONRPC manpage.

AnyEvent condvars

The main thing you have to remember is that all the data retrieval methods return an AnyEvent condvar, $cv. If you want the actual data from the request, there are a few things you can do.

You may have noticed that many of the examples in the SYNOPSIS call recv on the condvar. You're allowed to do this under 2 circumstances:

Either you're in a main program,

Main programs are "allowed to call recv blockingly", according to the author of AnyEvent.

or you're in a Coro + AnyEvent environment.

When you call recv inside a coroutine, only that coroutine is blocked while other coroutines remain active. Thus, the program as a whole is still responsive.

If you're not using Coro, and you don't want your whole program to block, what you should do is call cb on the condvar, and give it a coderef to execute when the results come back. The coderef will be given a condvar as a parameter, and it can call recv on it to get the data. The final example in the SYNOPSIS gives a brief example of this.

Also note that recv will throw an exception if the request fails, so be prepared to catch exceptions where appropriate.

Please read the AnyEvent documentation for more information on the proper use of condvars.

METHODS

new (%options)

Create new client object and return it.

    my $client = AnyEvent::JSONRPC::HTTP::Client->new(
        host => '127.0.0.1',
        port => 4423,
        %options,
    );

Available options are:

url => 'Str'

URL to json-RPC endpoint to connect. (Required)

username => 'Str'

Username to use for authorization (Optional).

If this is set an Authorization header containing basic auth credential is always sent with request.

password => 'Str'

Password used for authorization (optional)

call ($method, @params)

Call remote method named $method with parameters @params. And return condvar object for response.

    my $cv = $client->call( echo => 'Hello!' );
    my $res = $cv->recv;

If server returns an error, $cv->recv causes croak by using $cv->croak. So you can handle this like following:

    my $res;
    eval { $res = $cv->recv };
    
    if (my $error = $@) {
        # ...
    }

notify ($method, @params)

Same as call method, but not handle response. This method just notify to server.

    $client->notify( echo => 'Hello' );

AUTHOR

Peter Makholm <peter@makholm.net>

COPYRIGHT AND LICENSE

Copyright (c) 2010 by Peter Makholm.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.