.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "JSON::RPC 3pm"
.TH JSON::RPC 3pm "2014-10-13" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
JSON::RPC \- JSON RPC 2.0 Server Implementation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # app.psgi
\&    use strict;
\&    use JSON::RPC::Dispatch;
\&
\&    my $dispatch = JSON::RPC::Dispatch\->new(
\&        prefix => "MyApp::JSONRPC::Handler",
\&        router => Router::Simple\->new( ... )
\&    );
\&
\&    sub {
\&        my $env = shift;
\&        $dispatch\->handle_psgi($env);
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1JSON::RPC\s0 is a set of modules that implement \s-1JSON RPC 2.0\s0 protocol.
.PP
.Vb 3
\&    If you are using old JSON::RPC code (up to 0.96), DO NOT EXPECT
\&    YOUR CODE TO WORK WITH THIS VERSION. THIS VERSION IS 
\&    ****BACKWARDS INCOMPATIBLE****
.Ve
.SH "BASIC USAGE"
.IX Header "BASIC USAGE"
The JSON::RPC::Dispatch object is responsible for marshalling the request.
.PP
.Vb 3
\&    my $dispatch = JSON::RPC::Dispatch\->new(
\&        router => ...,
\&    );
.Ve
.PP
The routing between the \s-1JSON RPC\s0 methods and their implementors are handled by
Router::Simple. For example, if you want to map method \*(L"foo\*(R" to a \*(L"MyApp::JSONRPC::Handler\*(R" object instance's \*(L"handle_foo\*(R" method, you specify something like the following in your router instance:
.PP
.Vb 7
\&    use Router::Simple::Declare;
\&    my $router = router {
\&        connect "foo" => {
\&            handler => "+MyApp::JSONRPC::Handler",
\&            action  => "handle_foo"
\&        };
\&    };
\&
\&    my $dispatch = JSON::RPC::Dispatch\->new(
\&        router => $router,
\&    );
.Ve
.PP
The \*(L"+\*(R" prefix in the handler classname denotes that it is already a fully qualified classname. Without the prefix, the value of \*(L"prefix\*(R" in the dispatch object will be used to qualify the classname. If you specify it in your Dispatch instance, you may omit the prefix part to save you some typing:
.PP
.Vb 2
\&    use JSON::RPC::Dispatch;
\&    use Router::Simple::Declare;
\&
\&    my $router = router {
\&        connect "foo" => {
\&            handler => "Foo",
\&            action  => "process",
\&        };
\&        connect "bar" => {
\&            handler => "Bar",
\&            action => "process"
\&        }
\&    };
\&    my $dispatch = JSON::RPC::Dispatch\->new(
\&        prefix => "MyApp::JSONRPC::Handler",
\&        router => $router,
\&    );
\&
\&    # The above will roughly translate to the following:
\&    #
\&    # for method "foo"
\&    #    my $handler = MyApp::JSONRPC::Handler::Foo\->new;
\&    #    $handler\->process( ... );
\&    #
\&    # for method "bar"
\&    #    my $handler = MyApp::JSONRPC::Handler::Bar\->new;
\&    #    $handler\->process( ... );
.Ve
.PP
The implementors are called handlers. Handlers are simple objects, and will be instantiated automatically for you. Their return values are converted to \s-1JSON\s0 objects automatically.
.PP
You may also choose to pass objects in the handler argument to connect in  your router. This will save you the cost of instantiating the handler object, and you also don't have to rely on us instantiating your handler object.
.PP
.Vb 2
\&    use Router::Simple::Declare;
\&    use MyApp::JSONRPC::Handler;
\&
\&    my $handler = MyApp::JSONRPC::Handler\->new;
\&    my $router = router {
\&        connect "foo" => {
\&            handler => $handler,
\&            action  => "handle_foo"
\&        };
\&    };
.Ve
.SH "HANDLERS"
.IX Header "HANDLERS"
Your handlers are objects responsible for returning some sort of reference structure that can be properly encoded via \s-1JSON/JSON::XS.\s0 The handler only needs to implement the methods that you specified in your router.
.PP
The handler methods will receive the following parameters:
.PP
.Vb 2
\&    sub your_handler_method {
\&        my ($self, $params, $procedure, @extra_args) = @_;
\&
\&        return $some_structure;
\&    }
.Ve
.PP
In most cases you will only need the parameters. The exact format of the \f(CW$params\fR is dependent on the caller \*(-- you will be passed whatever \s-1JSON\s0 structure that caller used to call your handler.
.PP
\&\f(CW$procedure\fR is an instance of JSON::RPC::Procedure. Use it if you need to figure out more about the procedure.
.PP
\&\f(CW@extra_args\fR is optional, and will be filled with whatever extra arguments you passed to \fIhandle_psgi()\fR. For example,
.PP
.Vb 4
\&    # app.psgi
\&    sub {
\&        $dispatch\->handle_psgi($env, "arg1", "arg2", "arg3");
\&    }
.Ve
.PP
will cause your handlers to receive the following arguments:
.PP
.Vb 2
\&    sub your_handler_method {
\&        my ($self, $params, $procedure, $arg1, $arg2, $arg3) = @_;
\&
\&    }
.Ve
.PP
This is convenient if you have application-specific data that needs to be passed to your handlers.
.SH "EMBED IT IN YOUR WEBAPP"
.IX Header "EMBED IT IN YOUR WEBAPP"
If you already have a web app (and whatever framework you might already have), you may choose to embed \s-1JSON::RPC\s0 in your webapp instead of directly calling it in your \s-1PSGI\s0 application.
.PP
For example, if you would like to your webapp's \*(L"rpc\*(R" handler to marshall the \s-1JSON RPC\s0 request, you can do something like the following:
.PP
.Vb 2
\&    package MyApp;
\&    use My::Favorite::WebApp;
\&
\&    sub rpc {
\&        my ($self, $context) = @_;
\&
\&        my $dispatch =  ...; # grab it from somewhere
\&        $dispatch\->handle_psgi( $context\->env );
\&    }
.Ve
.SH "ERRORS"
.IX Header "ERRORS"
When your handler dies, it is automatically included in the response hash, unless no response was requested (see \*(L"\s-1NOTIFICATIONS\*(R"\s0).
.PP
For example, something like below
.PP
.Vb 6
\&    sub rpc {
\&        ...
\&        if ($bad_thing_happend) {
\&            die "Argh! I failed!";
\&        }
\&    }
.Ve
.PP
Would result in a response like
.PP
.Vb 6
\&    {
\&        error => {
\&            code => \-32603,
\&            message => "Argh! I failed! at ...",
\&        }
\&    }
.Ve
.PP
However, you can include custom data by \fIdie()\fR'ing with a hash:
.PP
.Vb 6
\&    sub rpc {
\&        ...
\&        if ($bad_thing_happend) {
\&            die { message => "Argh! I failed!", data => time() };
\&        }
\&    }
.Ve
.PP
This would result in:
.PP
.Vb 7
\&    {
\&        error => {
\&            code => \-32603,
\&            message => "Argh! I failed! at ...",
\&            data => 1339817722,
\&        }
\&    }
.Ve
.SH "NOTIFICATIONS"
.IX Header "NOTIFICATIONS"
Notifications are defined as procedures without an id.
Notification handling does not produce a response. When all procedures are notifications no content is returned (if the request is valid).
To maintain some basic compatibility with relaxed client implementations, JSON::RPC::Dispatch includes responses when procedures do not have a \*(L"jsonrpc\*(R" field set to \*(L"2.0\*(R".
.PP
Note that no error is returned in response to a notification when the handler dies or when the requested method is not available.
.PP
For example, a request structure like this:
.PP
.Vb 6
\&    [
\&        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
\&        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
\&        {"jsonrpc": "2.0", "method": "keep_alive"},
\&        {"jsonrpc": "2.0", "method": "get_data", "id": "9"}
\&    ]
.Ve
.PP
Would result in a response like
.PP
.Vb 4
\&    [
\&        {"jsonrpc": "2.0", "result": 7, "id": "1"},
\&        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
\&    ]
.Ve
.SH "BACKWARDS COMPATIBILITY"
.IX Header "BACKWARDS COMPATIBILITY"
Eh, not compatible at all. \s-1JSON RPC 0\s0.xx was fine, but it predates \s-1PSGI,\s0 and things are just... different before and after \s-1PSGI.\s0
.PP
Code at version 0.96 has been moved to JSON::RPC::Legacy namespace, so change your application to use JSON::RPC::Legacy if you were using the old version.
.SH "AUTHORS"
.IX Header "AUTHORS"
Daisuke Maki
.PP
Shinichiro Aska
.PP
Yoshimitsu Torii
.SH "AUTHOR EMERITUS"
.IX Header "AUTHOR EMERITUS"
Makamaka Hannyaharamitu, <makamaka[at]cpan.org> \- \s-1JSON::RPC\s0 modules up to 0.96
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
The \s-1JSON::RPC\s0 module is
.PP
Copyright (C) 2011 by Daisuke Maki
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.0 or,
at your option, any later version of Perl 5 you may have available.
.PP
See JSON::RPC::Legacy for copyrights and license for previous versions.