NAME

MojoX::Dispatcher::Qooxdoo::Jsonrpc - Dispatcher for Qooxdoo Json Rpc Calls

SYNOPSIS

# lib/your-application.pm

use base 'Mojolicious';

use RpcService;

sub startup {
   my $self = shift;
   
   # instantiate all services
   my $services= {
       Test => RpcService->new(),
       
   };
   
   
   # add a route to the Qooxdoo dispatcher and route to it
   my $r = $self->routes;
   $r->route('/qooxdoo') -> to(
               'Jsonrpc#dispatch', 
               services    => $services, 
               debug       => 0,
               namespace   => 'MojoX::Dispatcher::Qooxdoo'
           );
       
}

   

DESCRIPTION

MojoX::Dispatcher::Qooxdoo::Jsonrpc dispatches incoming rpc requests from a qooxdoo application to your services and renders a (hopefully) valid json reply.

EXAMPLE

This example exposes a service named "Test" in a folder "RpcService". The Mojo application is named "QooxdooServer". The scripts are in the 'example' directory. First create this application using "mojolicious generate app QooxdooServer".

Then, lets write the service:

Change to the root directory "qooxdoo_server" of your fresh Mojo-Application and make a dir named 'qooxdoo-services' for the services you want to expose.

Our "Test"-service could look like:

package RpcService;

use Mojo::Base -base;

# if this attribute is created it will hold the mojo cookie session hash
# it is a hash pointer use it to store little bits of session information
# the session is signed and written into a browser cookie.
has 'mojo_session';

# if this attribute exists it will provide access to the mojo stash
# the mojo stash holds all sorts of information on the actual request
has 'mojo_stash';

# MANDADROY access check method. The method is called right before the actual
# method call, after assigning mojo_session and mojo_stash properties are set.
# These can be used for providing dynamic access control

our %access = (
   add => 1,
);

sub allow_rpc_access {
   my $self = shift;
   my $method = shift;          
   # check if we can access
   return $access{$method};
}

sub add{
   my $self = shift;
   my @params = @_;
   
   # Debug message on Mojo-server console (or log)
   print "Debug: $params[0] + $params[1]\n";
   
   # uncomment if you want to die without further handling
   # die;
   
   # uncomment if you want to die with a message in a hash
   # die {code => 20, message => "Test died on purpose :-)"};
   
   
   # uncomment if you want to die with your homemade error object 
   # (simple example see below)
  
   # use Error;
   # my $error = new Error('stupid error message', '56457');
   # die $error;
   
   my $result =  $params[0] + $params[1]
   return $result;    
}

1;


# Example of simple Error object class:

package Error;

sub new{
   my $class = shift;
   
   my $error = {
       message => shift;
       code    => shift;
   };
   
   bless $error, $class;
   return $error;
}

sub message{
   my $self = shift;
   return $self->{message};
}

sub code{
   my $self = shift;
   return $self->{code};
}

1;

Please create a constructor (like "new" here) which instantiates an object because we are going to use this in our 'lib/QooxdooServer.pm' below.

Notice the exception handling: You can die without or with a message (see example above). MojoX::Dispatcher::Qooxdoo::Jsonrpc will catch the "die" like an exception an send a message to the client. Happy dying! :-)

Now, lets write our application. Almost everything should have been prepared by Mojo when you invoked "mojolicious generate app QooxdooServer" (see above).

Change to "lib/" and open "QooxdooServer.pm" in your favourite editor. Then add some lines to make it look like this:

package QooxdooServer;

use strict;
use warnings;

use RpcService::Test;

use Mojo::Base 'Mojolicious';

# This method will run once at server start
sub startup {
   my $self = shift;
   
   my $services= {
       Test => new RpcService::Test(),
       # more services here
   };
   
   # tell Mojo about your services:
   my $r = $self->routes;
   
   # this sends all requests for "/qooxdoo" in your Mojo server 
   # to our little dispatcher.
   # change this at your own taste.
   $r->route('/qooxdoo')->to('
       jsonrpc#dispatch', 
       services    => $services, 
       debug       => 0,
       namespace   => 'MojoX::Dispatcher::Qooxdoo'
   );
   
}

1;

Now start your Mojo Server by issuing 'script/QooxdooServer daemon'. If you want to change any options, type 'script/QooxdooServer help'.

Security

MojoX::Dispatcher::Qooxdoo::Jsonrpc 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.

AUTHOR

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

This Module is sponsored by OETIKER+PARTNER AG

COPYRIGHT

Copyright (C) 2010 by :m)

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.