NetSDS::App::JSRPC (3pm)

        #!/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;

\*(C`NetSDS::App::JSRPC\*(C' module implements framework for common JSON-RPC based server application. JSON-RPC is a \s-1HTTP\s0 based protocol providing remote procudure call (\s-1RPC\s0) functionality using \s-1JSON\s0 for requests and responses incapsulation.

This implementation is based on NetSDS::App::FCGI module and expected to be executed as FastCGI or \s-1CGI\s0 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 \s-1HTTP\s0 protocol as data of 'application/json' \s-1MIME\s0 type.

To develop new JSON-RPC server application you need to create application class inherited from \*(C`NetSDS::App::JSRPC\*(C':

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!"); } }

\*(C`NetSDS::App::JSRPC\*(C' module provides two methods that may be used to implement more complex logic than average \s-1RPC\s0 to one class.

can_method() - method availability checking

By default it is just wrapper around \*(C`UNIVERSAL::can\*(C' function. However it may be rewritten to check for methods in other classes or even construct necessary methods on the fly.

process_call() - method dispatching

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.

new(%params) - class constructor

It's internally used constructor that shouldn't be used from application directly.

process() - main JSON-RPC iteration

This is internal method that implements JSON-RPC call processing.

can_method($method_name) - check method availability

This method allows to check if some method is available for execution. By default it use \*(C`UNIVERSAL::can\*(C' 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 \s-1HTTP\s0 \s-1POST\s0

Paramters: \s-1HTTP\s0 \s-1POST\s0 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:

id - the same as request Id (see specification)

result - method result

Returns \s-1JSON\s0 encoded response message.

_make_error(%params) - prepare error response

Internal method implementing JSON-RPC error response. Paramters:

id - the same as request Id (see specification)

code - error code (default is -32603, internal error)

message - error message

Returns \s-1JSON\s0 encoded error message

See \*(C`samples/app_jsrpc.fcgi\*(C' appliction.

\s-1JSON\s0

\s-1JSON::RPC2\s0

<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

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

2. Implement objects/classes support.

Michael Bochkaryov <[email protected]>

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 \s-1GNU\s0 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 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the \s-1GNU\s0 General Public License for more details.

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