NAME
   Catalyst::Plugin::Server::JSONRPC -- Catalyst JSONRPC Server Plugin

SYNOPSIS
       package MyApp;
       use Catalyst qw/Server Server::JSONRPC/;

       package MyApp::Controller::Example;
       use base 'Catalyst::Controller';

       sub echo : JSONRPC {                     # available as: example.echo
           my ( $self, $c, @args ) = @_;
           $c->stash->{jsonrpc} = join ', ', @args;
       }

       sub ping : JSONRPCPath('/ping') {        # available as: ping
           my ( $self, $c ) = @_;
           $c->stash->{jsonrpc} = 'Pong';
       }

       sub world : JSONRPCRegex(/hello/) {      # available as: *hello*
           my ($self, $c) = @_;
           $c->stash->{jsonrpc} = 'World';
       }

       sub echo : JSONRPCLocal {                # available as: example.echo
           my ( $self, $c, @args ) = @_;
           $c->stash->{jsonrpc} = join ', ', @args;
       }

       sub ping : JSONRPCGlobal {               # available as: ping
           my ( $self, $c ) = @_;
           $c->stash->{jsonrpc} = 'Pong';
       }

DESCRIPTION
   JSONRPC Plugin for Catalyst which we tried to make compatible with the
   way Catalyst works with URLS. Main features are:

   *   Split JSONRPC methodNames by STRING to find out Controller.

   *   Single entrypoint for JSONRPC calls, like http://host.tld/rpc

   *   DispatchTypes (attributes) which work much the same as Catalyst
       attrs

   *   JSONRPC Parameter handling transparent to Catalyst parameter
       handling

HOW IT WORKS
   The default behaviour will handle JSONRPC Requests sent to "/rpc" by
   creating an OBJECT containing JSONRPC specific parameters in
   "$c->req->jsonrpc".

   Directly after, it will find out the Path of the Action to dispatch to,
   by splitting methodName by ".":

     methodName: hello.world
     path      : /hello/world

   From this point, it will dispatch to '/hello/world' when it exists, like
   Catalyst Urls would do. What means: you will be able to set Regexes,
   Paths etc on subroutines to define the endpoint.

   We discuss these custom JSONRPC attributes below.

   When the request is dispatched, we will return $c->stash->{jsonrpc} to
   the jsonrpc client, or, when it is not available, it will return
   $c->stash to the client. There is also a way of defining $c->stash keys
   to be send back to the client.

ATTRIBUTES
   You can mark any method in your Catalyst application as being available
   remotely by using one of the following attributes, which can be added to
   any existing attributes, except Private. Remember that one of the
   mentioned attributes below are automatically also Privates...

   JSONRPC
       Make this method accessible via JSONRPC, the same way as Local does
       when using catalyst by URL.

       The following example will be accessible by method "hello.world":

         package Catalyst::Controller::Hello
         sub world : JSONRPC {}

   JSONRPCLocal
       Identical version of attribute "JSONRPC"

   JSONRPCGlobal
       Make this method accessible via JSONRPC, the same way as GLOBAL does
       when using catalyst by URL.

       The following example will be accessible by method "ping":

         package Catalyst::Controller::Hello
         sub ping : JSONRPCGlobal {}

   JSONRPCPath('/say/hello')
       Make this method accessible via JSONRPC, the same way as Path does
       when using catalyst by URL.

       The following example will be accessible by method "say.hello":

         package Catalyst::Controller::Hello
         sub hello : JSONRPCPath('/say/hello') {}

   JSONRPCRegex('foo')
       Make this method accessible via JSONRPC, the same way as Regex does
       when using catalyst by URL.

       The following example will be accessible by example methods:
       "a.foo.method" "wedoofoohere" "foo.getaround"

         package Catalyst::Controller::Hello
         sub hello : JSONRPCPath('foo') {}

ACCESSORS
   Once you've used the plugin, you'll have an $c->request->jsonrpc
   accessor which will return an "Catalyst::Plugin::Server::JSONRPC"
   object.

   You can query this object as follows:

   $c->req->jsonrpc->is_jsonrpc_request
       Boolean indicating whether the current request has been initiated
       via JSONRPC

   $c->req->jsonrpc->config
       Returns a "Catalyst::Plugin::Server::JSONRPC::Config" object. See
       the "CONFIGURATION" below on how to use and configure it.

   $c->req->jsonrpc->body
       The body of the original JSONRPC call

   $c->req->jsonrpc->method
       The name of the original method called via JSONRPC

   $c->req->jsonrpc->args
       A list of parameters supplied by the JSONRPC call

   $c->req->jsonrpc->result_as_string
       The JSON body that will be sent back to the JSONRPC client

   $c->req->jsonrpc->error
       Allows you to set jsonrpc fault code and message

Server Accessors
   The following accessors are always available, whether you're in a
   jsonrpc specific request or not

   $c->server->jsonrpc->list_methods
       Returns a HASHREF containing the available jsonrpc methods in
       Catalyst as a key, and the "Catalyst::Action" object as a value.

CATALYST REQUEST
   To make things transparent, we try to put JSONRPC params into the
   Request object of Catalyst. But first we will explain something about
   the JSONRPC specifications.

   A full draft of these specifications can be found on:
   "http://www.jsonrpc.com/spec"

   In short, a jsonrpc-request consists of a methodName, like a subroutine
   name, and a list of parameters. This list of parameters may contain
   strings (STRING), arrays (LIST) and structs (HASH). Off course, these
   can be nested.

   $c->req->arguments
       We will put the list of arguments into $c->req->arguments, thisway
       you can fetch this list within your dispatched-to-subroutine:

         sub echo : JSONRPC {
             my ($self, $c, @args) = @_;
             $c->log->debug($arg[0]);              # Prints first JSONRPC parameter
                                                   # to debug log
         }

   $c->req->parameters
       Because JSONRPC parameters are a LIST, we can't just fill
       $c->req->paremeters. To keep things transparent, we made an extra
       config option what tells the JSONRPC server we can assume the
       following conditions on all JSONRPC requests: - There is only one
       JSONRPC parameter - This JSONRPC parameter is a struct (HASH)

       We will put this STRUCT as key-value pairs into $c->req->parameters.

   $c->req->params
       Alias of $c->req->parameters

   $c->req->param
       Alias of $c->req->parameters

INTERNAL JSONRPC FUNCTIONS
   The following system functions are available to the public.,

   system.listMethods
       returns a list of available RPC methods.

DEFINING RETURN VALUES
   The JSON-RPC response must contain a single parameter, which may contain
   an array (LIST), struct (HASH) or a string (STRING). To define the
   return values in your subroutine, you can alter $c->stash in three
   different ways.

 Defining $c->stash->{jsonrpc}
   When defining $c->stash->{jsonrpc}, the JSONRPC server will return these
   values to the client.

 When there is no $c->stash->{jsonrpc}
   When there is no "$c->stash->{jsonrpc}" set, it will return the complete
   "$c->stash"

CONFIGURATION
   The JSONRPC Plugin accepts the following configuration options, which
   can be set in the standard Catalyst way (See "perldoc Catalyst" for
   details):

       Your::App->config( jsonrpc => { key => value } );

   You can look up any of the config parameters this package uses at
   runtime by calling:

       $c->server->jsonrpc->config->KEY

   path
       This specifies the entry point for your jsonrpc server; all requests
       are dispatched from there. This is the url any JSONRCP client should
       post to. You can change this to any "Regex" wish.

       The default is: "qr!^(/?)rpc(/|$)!i", which matches on a top-level
       path begining with "rpc" preceeded or followed by an optional "/",
       like this:

           http://your-host.tld/rpc

   prefix
       This specifies the prefix of the forward url.

       For example, with a prefix of "rpc", and a method "foo", the forward
       path would be come "/rpc/foo".

       The default is '' (empty).

   separator
       This is a STRING used to split your method on, allowing you to use a
       hierarchy in your method calls.

       For example, with a separator of "." the method call "demo.echo"
       would be forwarded to "/demo/echo". To make "demo_echo" forward to
       the same path, you would change the separator to "_",

       The default is ".", splitting methods on a single "."

   convert_params
       Make the arguments in "$c->req->jsonrpc->params" available as
       "$c->req->params".

       Defaults to true.

   show_errors
       Make system errors in "$c->error" public to the rpc-caller in a
       JSON-RPC faultString. When show_errors is false, and your catalyst
       app generates a fault, it will return an JSON-RPC fault containing
       error number 500 and error string: "Internal Server Error".

       Defaults to false.

DIAGNOSTICS
   Invalid JSONRPC request: No such method
       There is no corresponding method in your application that can be
       forwarded to.

   Invalid JSONRPC request %s
       There was an error parsing the JSONRPC request

   Invalid JSONRPC request: Unknown error
       An unexpected error occurred

TODO
   Make error messages configurable/filterable
       Right now, whatever ends up on $c->error gets returned to the
       client. It would be nice to have a way to filter/massage these
       messages before they are sent back to the client.

   Make stash filterable before returning
       Just like the error messages, it would be nice to be able to filter
       the stash before returning so you can filter out keys you don't want
       to return to the client, or just return a certain list of keys. This
       all to make transparent use of JSONRPC and web easier.

SEE ALSO
   Catalyst::Manual, Catalyst::Request, Catalyst::Response,
   JSON::RPC::Common,

ACKNOWLEDGEMENTS
   For the original implementation of this module:

   Marcus Ramberg "[email protected]" Christian Hansen Yoshinori Sano Jos
   Boumans ([email protected]) Michiel Ootjers ([email protected])

AUTHORS
   Sergey Nosenko ([email protected])

   http://code.google.com/p/catalyst-server-jsonrpc

BUG REPORTS
   Please submit all bugs regarding "Catalyst::Plugin::Server::JSONRPC" to
   http://code.google.com/p/catalyst-server-jsonrpc/issues/entry

LICENSE
   This library is free software, you can redistribute it and/or modify it
   under the same terms as Perl itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.