/ 
JSON-RPC2-v2.1.3
River stage one • 4 direct dependents • 4 total dependents
/ JSON::RPC2::Server

NAME

JSON::RPC2::Server - Transport-independent JSON-RPC 2.0 server

VERSION

This document describes JSON::RPC2::Server version v2.1.3

SYNOPSIS

use JSON::RPC2::Server;

my $rpcsrv = JSON::RPC2::Server->new();

$rpcsrv->register('func1', \&func1);
$rpcsrv->register_nb('func2', \&func2);
$rpcsrv->register_named('func3', \&func3);
$rpcsrv->register_named_nb('func4', \&func4);

# receive remote request in $json_request somehow, then:
$rpcsrv->execute( $json_request, \&send_response );

sub send_response {
    my ($json_response) = @_;
    # send $json_response somehow
}

sub func1 {
    my (@remote_params) = @_;
    if (success) {
        return ($result);
    } else {
        return (undef, $err_code, $err_message);
    }
}

sub func2 {
    my ($callback, @remote_params) = @_;
    # setup some event to call func2_finished($callback) later
}
sub func2_finished {
    my ($callback) = @_;
    if (success) {
        $callback->($result);
    } else {
        $callback->(undef, $err_code, $err_message);
    }
    return;
}

sub func3 {
    my (%remote_params) = @_;
    # rest the same as in func1
}

sub func4 {
    my ($callback, %remote_params) = @_;
    # rest the same as in func2
}

#
# EXAMPLE of simple blocking STDIN-STDOUT server
#

my $rpcsrv = JSON::RPC2::Server->new();
$rpcsrv->register('method1', \&method1);
$rpcsrv->register('method2', \&method2);
while (<STDIN>) {
    chomp;
    $rpcsrv->execute($_, sub { printf "%s\n", @_ });
}
sub method1 {
    return { my_params => \@_ };
}
sub method2 {
    return (undef, 0, "don't call me please");
}

DESCRIPTION

Transport-independent implementation of JSON-RPC 2.0 server. Server methods can be blocking (simpler) or non-blocking (useful if method have to do some slow tasks like another RPC or I/O which can be done in non-blocking way - this way several methods can be executing in parallel on server).

INTERFACE

new

$rpcsrv = JSON::RPC2::Server->new();

Create and return new server object, which can be used to register and execute user methods.

register

register_named

$rpcsrv->register( $rpc_method_name, \&method_handler );
$rpcsrv->register_named( $rpc_method_name, \&method_handler );

Register $rpc_method_name as allowed method name for remote procedure call and set \&method_handler as BLOCKING handler for that method.

If there already was some handler set (using register() or register_named() or register_nb() or register_named_nb()) for that $rpc_method_name - it will be replaced by \&method_handler.

While processing request to $rpc_method_name user handler will be called with parameters provided by remote side (as ARRAY for register() or HASH for register_named()), and should return it result as list with 4 elements:

($result, $code, $message, $data) = method_handler(@remote_params);
($result, $code, $message, $data) = method_handler(%remote_params);

$result        scalar or complex structure if method call success
$code          error code (integer, > -32600) if method call failed
$message       error message (string) if message call failed
$data          optional scalar with additional error-related data

If $code is defined then $result shouldn't be defined; $message required only if $code defined.

Return nothing.

register_nb

register_named_nb

$rpcsrv->register_nb( $rpc_method_name, \&nb_method_handler );
$rpcsrv->register_named_nb( $rpc_method_name, \&nb_method_handler );

Register $rpc_method_name as allowed method name for remote procedure call and set \&method_handler as NON-BLOCKING handler for that method.

If there already was some handler set (using register() or register_named() or register_nb() or register_named_nb()) for that $rpc_method_name - it will be replaced by \&method_handler.

While processing request to $rpc_method_name user handler will be called with callback needed to return result in first parameter and parameters provided by remote side as next parameters (as ARRAY for register_nb() or HASH for register_named_nb()), and should call provided callback with list with 4 elements when done:

nb_method_handler($callback, @remote_params);
nb_method_handler($callback, %remote_params);

# somewhere in that method handlers:
$callback->($result, $code, $message, $data);
return;

Meaning of ($result, $code, $message, $data) is same as documented in register() above.

Return nothing.

execute

$rpcsrv->execute( $json_request, $callback );

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

Parse $json_request and execute registered user handlers. Reply will be sent into $callback, when ready:

$callback->( $json_response );

The $callback will be always executed after finishing processing $json_request - even if request type was "notification" (in this case $json_response will be an empty string).

Return nothing.

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