Linux Certif

Toute la documentation sur la certification Linux LPI

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.

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