Provided by: libnetsds-perl_1.301-4_all bug

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.

       can_method() - method availability checking
           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.

       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.

CLASS API

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

       process_call($method, $params) - execute method call
           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:

           id - the same as request Id (see specification)
           result - method result

           Returns JSON 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 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