The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
JSON-RPC2-v2.1.2
River stage one • 4 direct dependents • 4 total dependents
3 ++
/ JSON::RPC2::Client

NAME

JSON::RPC2::Client - Transport-independent JSON-RPC 2.0 client

VERSION

This document describes JSON::RPC2::Client version v2.1.2

SYNOPSIS

 use JSON::RPC2::Client;

 $client = JSON::RPC2::Client->new();

 $json_request = $client->notify('method', @params);
 $json_request = $client->notify_named('method', %params);
 ($json_request, $call) = $client->call('method', @params);
 ($json_request, $call) = $client->call_named('method', %params);

 ($json_request, @call) = $client->batch(
    $client->call('method1', @params),
    $client->call('method2', @params),
    $client->notify('method', @params),
    $client->call_named('method', %params),
    $client->notify_named('method', %params),
 );

 $client->cancel($call);

 ($failed, $result, $error, $call) = $client->response($json_response);

 for ($client->batch_response($json_response)) {
    ($failed, $result, $error, $call) = @{ $_ };
    ...
 }

 @call = $client->pending();

 #
 # EXAMPLE of simple blocking STDIN-STDOUT client
 #
 
 $client = JSON::RPC2::Client->new();
 $json_request = $client->call('method', @params);

 printf "%s\n", $json_request;
 $json_response = <STDIN>;
 chomp $json_response;

 ($failed, $result, $error) = $client->response($json_response);
 if ($failed) {
    die "bad response: $failed";
 } elsif ($error) {
    printf "method(@params) failed with code=%d: %s\n",
        $error->{code}, $error->{message};
 } else {
    print "method(@params) returned $result\n";
 }

DESCRIPTION

Transport-independent implementation of JSON-RPC 2.0 client. Can be used both in sync (simple, for blocking I/O) and async (for non-blocking I/O in event-based environment) mode.

INTERFACE

new

    $client = JSON::RPC2::Client->new();

Create and return new client object, which can be used to generate requests (notify(), call()), parse responses (responses()) and cancel pending requests (cancel(), pending()).

Each client object keep track of request IDs, so you must use dedicated client object for each connection to server.

notify

notify_named

    $json_request = $client->notify( $remote_method, @remote_params );
    $json_request = $client->notify_named( $remote_method, %remote_params );

Notifications doesn't receive any replies, so they unreliable.

Return ($json_request) - scalar which should be sent to server in any way.

call

call_named

    ($json_request, $call) = $client->call( $remote_method, @remote_params );
    ($json_request, $call) = $client->call_named( $remote_method, %remote_params );

Return ($json_request, $call) - scalar which should be sent to server in any way and identifier of this remote procedure call.

The $call is just empty HASHREF, which can be used to: 1) keep user data related to this call in hash fields - that $call will be returned by response() when response to this call will be received; 2) to cancel() this call before response will be received. There usually no need for user to keep $call somewhere unless he wanna be able to cancel() that call.

In scalar context return only $json_request - this enough for simple blocking clients which doesn't need to detect which of several pending() calls was just replied or cancel() pending calls.

batch

    ($json_request, @call) = $client->batch(
        $json_request1,
        $json_request2,
        $call2,
        $json_request3,
        ...
    );

Return ($json_request, @call) - scalar which should be sent to server in any way and identifiers of these remote procedure calls (they'll be in same order as they was in params). These two example are equivalent:

    ($json_request, $call1, $call3) = $client->batch(
        $client->call('method1'),
        $client->notify('method2'),
        $client->call('method3'),
    );

    ($json1, $call1) = $client->call('method1');
    $json2           = $client->notify('method2');
    ($json3, $call3) = $client->call('method3');
    $json_request = $client->batch($json1, $json2, $json3);

If you're using batch() to send some requests then you should process RPC server's responses using batch_response(), not response().

batch_response

    @responses = $client->batch_response( $json_response );

The $json_response can be either JSON string or ARRAYREF/HASHREF (useful with $handle->push_read(json => sub{...}) from AnyEvent::Handle).

Will parse $json_response and return list with ARRAYREFS, which contain 4 elements returned by response().

It is safe to always use batch_response() instead of response(), even if you don't send batch() requests at all.

response

    ($failed, $result, $error, $call) = $client->response( $json_response );

The $json_response can be either JSON string or HASHREF (useful with $handle->push_read(json => sub{...}) from AnyEvent::Handle).

Will parse $json_response and return list with 4 elements:

 ($failed, $result, $error, $call)

 $failed        parse error message if $json_response is incorrect
 $result        data returned by successful remote method call
 $error         error returned by failed remote method call
 $call          identifier of this call

If $failed defined then all others are undefined. Usually that mean either bug in JSON-RPC client or server.

Only one of $result and $error will be defined. Format of $result completely depends on data returned by remote method. $error is HASHREF with fields {code}, {message}, {data} - code should be integer, message should be string, and data is optional value in arbitrary format.

The $call should be used to identify which of currently pending() calls just returns - it will be same HASHREF as was initially returned by call() when starting this remote procedure call, and may contain any user data which was placed in it after calling call().

There also special case when all 4 values will be undefined - that happens if $json_response was related to call which was already cancel()ed by user.

If you're using batch() to send some requests then you should process RPC server's responses using batch_response(), not response().

cancel

    $client->cancel( $call );

Will cancel that $call. This doesn't affect server - it will continue processing related request and will send response when ready, but that response will be ignored by client's response().

Return nothing.

pending

    @call = $client->pending();

Return list with all currently pending $call's.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/powerman/perl-JSON-RPC2/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests.

https://github.com/powerman/perl-JSON-RPC2

    git clone https://github.com/powerman/perl-JSON-RPC2.git

Resources

AUTHOR

Alex Efros <powerman@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2009- by Alex Efros <powerman@cpan.org>.

This is free software, licensed under:

  The MIT (X11) License