NAME

Mojolicious::Plugin::Qooxdoo::JsonRpcController - A controller base class for Qooxdoo JSON-RPC Calls

SYNOPSIS

# lib/MyApp.pm

use base 'Mojolicious';

sub startup {
   my $self = shift;
   
   # add a route to the Qooxdoo dispatcher and route to it
   my $r = $self->routes;
   $r->route('/RpcService') -> to(
       controller => 'MyJsonRpcController',
       action => 'dispatch',
   );        
}

package MyApp::MyJsonRpcController;

use Mojo::Base qw(Mojolicious::Plugin::Qooxdoo::JsonRpcController);
use Mojo::Promise;

has service => sub { 'Test' };

out %allow = ( echo => 1, bad =>  1, async => 1);

sub allow_rpc_access {
   my $self = shift;
   my $method = shift;
   return $allow{$method};;
}

sub echo {
   my $self = shift;
   my $text = shift;
   return $text;
} 

sub bad {

   die MyException->new(code=>1323,message=>'I died');

   die { code => 1234, message => 'another way to die' };
}

sub async {
   my $self=shift;
   $self->render_later;
   xyzWithCallback(callback=>sub{
       eval {
           local $SIG{__DIE__};
           $self->renderJsonRpcResult('Late Reply');
       }
       if ($@) {
           $self->renderJsonRpcError($@);
       }
   });
}

sub async_p {
   my $self=shift;
   my $p = Mojo::Promise->new;
   xyzWithCallback(callback => sub {
       eval {
           local $SIG{__DIE__};
           $p->resolve('Late Reply');
       }
       if ($@) {
           $p->reject($@);
       }
   });
   return $p;
}

package MyException;

use Mojo::Base -base;
has 'code';
has 'message';
1;

DESCRIPTION

All you have todo to process incoming JSON-RPC requests from a qooxdoo application, is to make your controller a child of Mojolicious::Plugin::Qooxdoo::JsonRpcController. And then route all incoming requests to the inherited dispatch method in the new controller.

If you want your Mojolicious app to also serve the qooxdoo application files, you can use Mojolicous::Plugin::Qooxdoo to have everything setup for you.

Exception processing

Errors within the methods of your controller are handled by an eval call, encapsulating the method call. So if you run into trouble, just die. If if you die with a object providing a code and message property or with a hash containing a code and message key, this information will be used to populate the JSON-RPC error object returned to the caller.

Security

The dispatcher method provided by Mojolicious::Plugin::Qooxoo::JsonRpcController calls the allow_rpc_access method to check if rpc access should be allowed. The result of this request is NOT cached, so you can use this method to provide dynamic access control or even do initialization tasks that are required before handling each request.

Async Processing

If you want to do async data processing, call the render_later method to let the dispatcher know that it should not bother with trying to render anyting. In the callback, call the renderJsonRpcResult method to render your result. Note that you have to take care of any exceptions in the callback yourself and use the renderJsonRpcError method to send the exception to the client.

Mojo::Promise Support

If your method returns a promise, all will workout as expected. See the example above.

Debugging

To see full details of your rpc request and the answers sent back to the browser in your debug log, set the MOJO_QX_FULL_RPC_DETAILS environment variable to 1. Otherwise you will only see the first 60 characters even when logging at debug level.

AUTHOR

Matthias Bloch, <matthias@puffin.ch>, Tobias Oetiker, <tobi@oetiker.ch>.

This Module is sponsored by OETIKER+PARTNER AG.

COPYRIGHT

Copyright (C) 2010,2013

LICENSE

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.8 or, at your option, any later version of Perl 5 you may have available.