view release on metacpan or  search on metacpan

lib/JSON/RPC.pm  view on Meta::CPAN

    );

    # 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( ... );


The implementors are called handlers. Handlers are simple objects, and will be instantiated automatically for you. Their return values are converted to JSON objects automatically.

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.

    use Router::Simple::Declare;
    use MyApp::JSONRPC::Handler;

    my $handler = MyApp::JSONRPC::Handler->new;
    my $router = router {
        connect "foo" => {
            handler => $handler,
            action  => "handle_foo"
        };
    };

=head1 HANDLERS

Your handlers are objects responsible for returning some sort of reference structure that can be properly encoded via JSON/JSON::XS. The handler only needs to implement the methods that you specified in your router.

The handler methods will receive the following parameters:

    sub your_handler_method {
        my ($self, $params, $procedure, @extra_args) = @_;

        return $some_structure;
    }

In most cases you will only need the parameters. The exact format of the $params is dependent on the caller -- you will be passed whatever JSON structure that caller used to call your handler.

$procedure is an instance of JSON::RPC::Procedure. Use it if you need to figure out more about the procedure.

@extra_args is optional, and will be filled with whatever extra arguments you passed to handle_psgi(). For example, 

    # app.psgi
    sub {
        $dispatch->handle_psgi($env, "arg1", "arg2", "arg3");
    }

will cause your handlers to receive the following arguments:

    sub your_handler_method {
        my ($self, $params, $procedure, $arg1, $arg2, $arg3) = @_;

    }

This is convenient if you have application-specific data that needs to be passed to your handlers.

=head1 EMBED IT IN YOUR WEBAPP

If you already have a web app (and whatever framework you might already have), you may choose to embed JSON::RPC in your webapp instead of directly calling it in your PSGI application.

For example, if you would like to your webapp's "rpc" handler to marshall the JSON RPC request, you can do something like the following:

    package MyApp;
    use My::Favorite::WebApp;

    sub rpc {
        my ($self, $context) = @_;

        my $dispatch =  ...; # grab it from somewhere
        $dispatch->handle_psgi( $context->env );
    }

=head1 ERRORS

When your handler dies, it is automatically included in the response hash, unless no response was requested (see L</NOTIFICATIONS>).

For example, something like below 

    sub rpc {
        ...
        if ($bad_thing_happend) {
            die "Argh! I failed!";
        }
    }

Would result in a response like

    {
        error => {
            code => -32603,
            message => "Argh! I failed! at ...",
        }
    }

However, you can include custom data by die()'ing with a hash:

    sub rpc {
        ...
        if ($bad_thing_happend) {
            die { message => "Argh! I failed!", data => time() };
        }
    }

This would result in:

    {
        error => {
            code => -32603,
            message => "Argh! I failed! at ...",
            data => 1339817722,
        }
    }

=head1 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).