Scroll to navigation

NetSDS::App::JSRPC(3pm) User Contributed Perl Documentation NetSDS::App::JSRPC(3pm)

NAME

NetSDS::App::JSRPC - JSON-RPC server framework

SYNOPSIS

        #!/usr/bin/env perl
        # JSON-RPC server
        
        use 5.8.0;
        use warnings;
        use strict;
        JServer->run();
        1;
        # Server application logic
        package JServer;
        use base 'NetSDS::App::JSRPC';
        # This method is available via JSON-RPC
        sub sum {
                my ($self, $param) = @_;
                return $$param[0] + $$param[1];
        }
        1;

DESCRIPTION

"NetSDS::App::JSRPC" module implements framework for common JSON-RPC based server application. JSON-RPC is a HTTP based protocol providing remote procudure call (RPC) functionality using JSON for requests and responses incapsulation.

This implementation is based on NetSDS::App::FCGI module and expected to be executed as FastCGI or CGI application.

Diagram of class inheritance:

          [NetSDS::App::JSRPC] - JSON-RPC server
                   |
          [NetSDS::App::FCGI] - CGI/FCGI application
                   |
             [NetSDS::App] - common application
                   |
        [NetSDS::Class::Abstract] - abstract class

Both request and response are JSON-encoded strings represented in HTTP protocol as data of 'application/json' MIME type.

APPLICATION DEVELOPMENT

To develop new JSON-RPC server application you need to create application class inherited from "NetSDS::App::JSRPC":

It's just empty application:

        #!/usr/bin/env perl
        
        JSApp->run(
                conf_file => '/etc/NetSDS/jsonapp.conf'
        );
        package JSApp;
        use base 'NetSDS::App::JSRPC';
        1;

Alsoe you may want to add some specific code for application startup:

        sub start {
                my ($self) = @_;
                connect_to_dbms();
                query_for_external_startup_config();
                do_other_initialization();
        }

And of course you need to add methods providing necessary functions:

        sub send_sms {
                my ($self, $params) = @_;
                return $self->{kannel}->send(
                        from => $params{'from'},
                        to => $params{'to'},
                        text => $params{'text'},
                );
        }
        sub kill_smsc {
                my ($self, $params) = @_;
                # 1M of MT SM should be enough to kill SMSC!
                # Otherwise we call it unbreakable :-)
                for (my $i=1; $<100000000; $i++) {
                        $self->{kannel}->send(
                                %mt_sm_parameters,
                        );
                }
                if (smsc_still_alive()) {
                        return $self->error("Can't kill SMSC! Need more power!");
                }
        }

ADVANCED FUNCTIONALITY

"NetSDS::App::JSRPC" module provides two methods that may be used to implement more complex logic than average RPC to one class.

By default it is just wrapper around "UNIVERSAL::can" function. However it may be rewritten to check for methods in other classes or even construct necessary methods on the fly.
By default it just call local class method with the same name as in JSON-RPC call. Of course it can be overwritten and process query in some other way.

This code describes logic of call processing:

        # It's not real code
        if (can_method($json_method)) {
                process_call($json_method, $json_params);
        }

For more details read documentation below.

CLASS API

It's internally used constructor that shouldn't be used from application directly.
This is internal method that implements JSON-RPC call processing.
This method allows to check if some method is available for execution. By default it use "UNIVERSAL::can" but may be rewritten to implement more complex calls dispatcher.

Paramters: method name (string)

Return true if method execution allowed, false otherwise.

Example:

        # Rewrite can_method() to search in other class
        sub can_method {
                my ($self, $method) = @_;
                return Other::Class->can($method);
        }
Paramters: method name, parameters.

Returns parameters from executed method as is.

Example:

        # Rewrite process_call() to use other class
        sub process_call {
                my ( $self, $method, $params ) = @_;
                return Other::Class->$method($params);
        }
_request_parse($post_data) - parse HTTP POST
Paramters: HTTP POST data as string

Returns: request method, parameters, id

_make_result(%params) - prepare positive response
This is internal method for encoding JSON-RPC response string.

Paramters:

Returns JSON encoded response message.

_make_error(%params) - prepare error response
Internal method implementing JSON-RPC error response.

Paramters:

Returns JSON encoded error message

EXAMPLES

See "samples/app_jsrpc.fcgi" appliction.

SEE ALSO

JSON

JSON::RPC2

<http://json-rpc.org/wiki/specification> - JSON-RPC 1.0

<http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal> - JSON-RPC 2.0

TODO

1. Move error codes to constants to provide more clear code.

2. Implement objects/classes support.

AUTHOR

Michael Bochkaryov <misha@rattler.kiev.ua>

LICENSE

Copyright (C) 2008-2009 Net Style Ltd.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

2021-12-26 perl v5.32.1