Alex Efros > JSON-RPC2-v2.1.1 > JSON::RPC2::Server

Download:
JSON-RPC2-v2.1.1.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v2.1.1   Source  

NAME ^

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

VERSION ^

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

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()

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

register( $rpc_method_name, \&method_handler )
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( $rpc_method_name, \&nb_method_handler )
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( $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-2014 by Alex Efros <powerman@cpan.org>.

This is free software, licensed under:

  The MIT (X11) License
syntax highlighting: