Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RPC::ExtDirect(3)     User Contributed Perl Documentation    RPC::ExtDirect(3)

NAME
       RPC::ExtDirect -	Easily integrate Perl server code with JavaScript apps

SYNOPSIS
	   package Foo::Bar;

	   use RPC::ExtDirect Action =>	'FooBar';

	   sub sum : ExtDirect(len => 2) {
	       my ($class, $a, $b) = @_;

	       return $a + $b;
	   }

	   sub login : ExtDirect(params	=> ['user, 'pass']) {
	       my ($class, %arg) = @_;

	       if ( $arg{user} eq 'foo'	&& $arg{pass} eq 'bar' ) {
		   return {
		       success => \1,  # JSON::true
		   };
	       }
	       else {
		   return {
		       success => \0,  # JSON::false
		       error   => "You shall not pass!"
		   };
	       }
	   }

DESCRIPTION
       RPC::ExtDirect suite of modules provides	an easy, simple	and robust way
       to write	Perl server side code that could be used with HTML5 Rich
       Internet	Applications based on JavaScript frameworks Ext	JS
       <http://www.sencha.com/products/extjs/> and Sencha Touch
       <http://www.sencha.com/products/touch/>.

       The suite consists of the core RPC::ExtDirect module that implements
       Ext.Direct protocol and transport layer,	several	server environment-
       specific	peripheral gateways, a standalone pure Perl server, two	Perl
       clients,	and even its own specialized testing scaffold! We've got it
       covered front to	back. :)

INTRODUCTION AND EXAMPLES
       If you are not familiar with Ext.Direct,	start with
       RPC::ExtDirect::Intro for more explanations and a few examples, both
       easy and	more advanced.

WHEN TO	USE IT,	AND WHY
       Ext.Direct is a Remote Procedure	Call (RPC) protocol provided out of
       the box with JavaScript frameworks by Sencha <http://www.sencha.com>.
       It is deeply integrated in the data services, and is supported by a
       slew of components.  Besides that, Ext.Direct also has several major
       advantages over similar protocols like XML-RPC and JSON-RPC:

       o   Built in service discovery mechanism: server	side API is published
	   to the client via GET requests to a preconfigured URI

       o   Dead	simple client side invocation via functional stubs created
	   from	the API	declaration

       o   Support for call metadata that is handled separately	from the
	   arguments for method	invocation

       o   Support for request batching	with configurable timeout

       o   Easy	file uploads via form submits, with all	the complexity handled
	   behind the curtains by the framework	and the	server side stack

       o   Asynchronous	push notifications via event polling

       All this	makes Ext.Direct a no-brainer when developing Web apps with
       Ext JS or Sencha	Touch. And with	RPC::ExtDirect,	choosing Perl to write
       server side code	for Web	apps comes naturally, too. :)

HOW TO USE
       Since Ext.Direct	is just	a transport layer, you don't need to change
       your app	architecture to	work around it.	If you have an existing	server
       side API	you can	publish	it with	minimal	effort;	if you're starting
       from scratch, add the classes and methods as you	go.

       Note that with Ext.Direct, we're	talking	about classes and methods -
       that owes to the	fact that Ext.Direct originated	in Ext JS framework,
       which itself is written in JavaScript with object-oriented approach in
       mind. This does not mean	you can't go functional	or even	procedural
       with RPC::ExtDirect; it is perfectly possible to	cook your own flavor
       of spaghetti code under the light OOP sauce that	RPC::ExtDirect
       provides.

       In order	for a method to	be published to	the outside world, it needs to
       be declared in the Ext.Direct API. As of	version	3.0, it	can be done in
       two ways: either	with "ExtDirect" attribute as shown in the "SYNOPSIS",
       or by including the method in a hashref fed to RPC::ExtDirect::API
       constructor. See	"COMPILE VS RUN	TIME DEFINITION" in
       RPC::ExtDirect::API for more detail.

METHODS	AND CALLING CONVENTIONS
       Unlike Ext.Direct specification (and reference PHP implementation, too)
       RPC::ExtDirect does not impose strict architectural notation on server
       side code. There	is no mandatory	object instantiation and no assumption
       about the code called. That said, an RPC::ExtDirect Method should
       conform to the following	conventions:

       o   Be a	class method, i.e. be aware that its first argument will be
	   the package (class) name. Just ignore it if you don't want it.

       o   Ordered (numbered) arguments	are passed as list in @_, so $_[1] is
	   the first argument. No more than number of arguments	declared in
	   the Method definition will be passed	to the Method; any extra will
	   be dropped silently.	Less arguments than declared will result in an
	   Exception returned to the client side, and Method never gets
	   called.

       o   Named arguments are passed as a hash	in @_. No arguments other than
	   declared will be passed to the Method; extra	arguments will be
	   dropped silently. If	not all	arguments are present for the remoting
	   invocation, an Exception will be returned and the Method never gets
	   called.

	   Starting with Ext JS	4.2.2, it is possble to	relax the argument
	   checking requirements; see "Lazy parameter checking"	in
	   RPC::ExtDirect::API for more	information.

       o   Form	handlers are passed their arguments as a hash in @_. Standard
	   Ext.Direct form field values	are removed from the argument hash;
	   uploaded file(s) will be passed in the "file_uploads" hash element.
	   It will only	be present when	there are uploaded files. For more
	   info, see "FILE UPLOADS".

	   Note	that any field values in a submitted form will be JSON encoded
	   by the client side.

       o   All remoting	Methods	are called in scalar context. Returning	one
	   scalar value	is OK; returning array-	or hashref is OK too.

	   Do not return blessed objects; it is	almost always not obvious how
	   to serialize	them into JSON that is expected	by the client side.
	   JSON	encoder	will choke and an Exception will be returned to	the
	   client. Having said that, if	you know what you are doing, it	is
	   possible to adjust the Serializer's behavior	with "json_options" in
	   RPC::ExtDirect::Config Config option.

       o   If an error is encountered while processing request,	throw an
	   exception: "die "My error string\n"". Note that "\n"	at the end of
	   error string; if you	don't add it, "die()" will append file name
	   and line number to the error	message	which is probably not the best
	   idea	for errors that	are not	shown in server	console	but rather
	   passed on to	the JavaScript client.

	   RPC::ExtDirect will trim that last "\n" for you before sending the
	   Exception back to the client	side.

       o   Poll	handler	methods	are called in list context and do not receive
	   any arguments except	the environment	object.	Return value must be a
	   list	of instantiated	Event objects, see RPC::ExtDirect::Event for
	   more	detail.

CALL METADATA
       Imagine a Web application with an editable Grid populated with data
       from a database table. To update	the database when changes are saved,
       the client will send an array of	changed	records	that will be passed to
       the corresponding Ext.Direct Method as call arguments. But what about
       the table name?

       The usual approach is to	create a separate set of 4 CRUD	methods
       (Create,	Read, Update, Delete) for each table, and expose these methods
       as a separate Action. While tried and true, this	approach leads to
       bloated Ext.Direct API when there are many tables, with lots of
       packages	and code duplication just for the sake of editing a database
       table. This can be especially frustrating when the application has many
       similar tables differing	only in	the name.

       Call metadata allows solving this and many other	problems by passing
       some information	to the called Method along with	the main data but not
       as a part of the	arguments. In particular, using	metadata allows	for
       having one set of CRUD methods for all similar data tables and send
       different table name for	each call as metadata.

       More of it, Ext JS (and RPC::ExtDirect, too) allow having different
       calling convention for Method arguments and metadata, e.g. having a
       Named Method with ordered (by position) metadata, and vice versa.

       Call metadata is	a new feature in Ext JS	5.1+.

HOOKS
       Hooks provide an	option to intercept method calls and modify arguments
       passed to the methods, or cancel	their execution. Hooks are intended to
       be used as a shim between task-oriented Methods and Web specifics.

       Methods should not, to the reasonable extent, be	aware of their
       environment or care about it; Hooks are expected	to know	how to deal
       with Web	intricacies but	not be task oriented.

       The best	uses for Hooks are: application	or package-wide	pre-call
       setup, user authorization, logging, cleanup, testing, etc. Or you can
       think of	the Hooks as poor man's	method wrappers	without	Moose's	power
       (and associated costs).

       See more	in RPC::ExtDirect::API::Hook.

ENVIRONMENT OBJECTS
       Since Hooks, and	sometimes Methods too, need to be aware	of their Web
       environment, it is necessary to give them access	to it in some way
       without locking in on platform specifics. RPC::ExtDirect's answer to
       this problem is environment objects.

       An environment object provides platform-agnostic	interface for
       accessing HTTP headers, cookies,	form field values, etc.	Such object is
       guaranteed to have the same set of methods that behave the same way
       across all platforms supported by RPC::ExtDirect, avoiding portability
       issues.

       The interface is	modeled	after the de facto standard CGI.pm:

       o   "$value = $env->param('name')" will retrieve	a parameter by name

       o   "@list = $env->param()" will	get the	list of	available parameters

       o   "$cookie = $env->cookie('name')" will retrieve a cookie

       o   "@cookies = $env->cookie()" will return the list of cookies

       o   "$header = $env->http('name')" will return an HTTP header

       o   "@headers = $env->http()" will return the list of HTTP headers

       Of course it is possible	to use environment object in a more
       sophisticated way if you	like to, however do not	rely on	it having a
       well-known class	name as	it is not guaranteed. Environment objects are
       simple helpers held together by duck type.

       Starting	with RPC::ExtDirect 3.0, only Hooks will receive an
       environment object by default. For Methods to receive them as well, you
       need to specify a "env_arg" in RPC::ExtDirect::API::Method parameter in
       Method definition.

FILE UPLOADS
       Ext.Direct offers native	support	for file uploading by using temporary
       HTML forms. RPC::ExtDirect supports this	feature; upload	requests can
       be processed in a Form Handler Method.  The interface aims to be
       platform	agnostic and will try to do its	best to	provide	the same
       results in all HTTP environments	supported by RPC::ExtDirect.

       In a Form Handler Method, arguments are passed as a hash. If one	or
       more file uploads were associated with request, the argument hash will
       contain a key with value	set to arrayref	of file	hashrefs. The default
       name for	this key is "file_uploads"; this can be	configured using
       upload_arg Method parameter.

       Each file hashref will have the following keys:

       "type"
	   MIME	type of	the file, if provided

       "size"
	   File	size, in octets

       "path"
	   Path	to a temporary file that holds uploaded	content

       "handle"
	   Open	IO::Handle for the temporary file

       "basename"
	   Name	portion	of the originally submitted file name, if provided by
	   the client side

       "filename"
	   Full	original path as sent by the client, if	any

       All files passed	to a Method need to be processed in that Method;
       existence of temporary files is not guaranteed after Method returns.

GATEWAYS
       In RPC::ExtDirect parlance, a Gateway is	a module that deals with the
       specifics of a particular Web server environment. At the	time of
       writing this documentation, the following gateways are available	for
       RPC::ExtDirect:

       CGI gateway
	   CGI::ExtDirect is used with the ole goode CGI environment; it is
	   also	compatible with	the newer CGI::Simple module that is a drop-in
	   replacement for "CGI.pm".

	   This	gateway	is most	often used for testing Ext.Direct interfaces,
	   usually with	Test::ExtDirect	helper module. However,	CGI
	   environment is easy to use and set up practically anywhere, and it
	   can be used in the variety of situations where a full blown Perl
	   application server is not feasible.

	   One example of such usage would be retrofitting a legacy system
	   with	a modern HTML5 Web interface.

       Plack gateway
	   Plack::Middleware::ExtDirect	implements an RPC::ExtDirect interface
	   for Plack application server	environment. This gateway should also
	   be used instead of the Apache gateway in mod_perl environment.

       AnyEvent::HTTPD gateway
	   AnyEvent::HTTPD::ExtDirect implements a completely asynchronous
	   interface for RPC::ExtDirect, based on AnyEvent::HTTPD module.

       Apache gateway
	   Apache::ExtDirect is	a legacy gateway for Apache/mod_perl
	   environment.	Since it was written, Apache has fallen	out of usage
	   with	the author and so the gateway is mostly	unsupported. You can
	   use Plack gateway instead, with one of the built in Apache/Plack
	   handlers.

MIGRATING FROM PREVIOUS	VERSIONS
       If you are using	less than current RPC::ExtDirect version, please refer
       to RPC::ExtDirect::Migration document for the notes and explanations
       that might prove	useful for migration.

DEPENDENCIES
       RPC::ExtDirect is dependent on the following modules:
       Attribute::Handlers, JSON.

       The oldest Perl version RPC::ExtDirect is routinely tested against is
       5.6.2.

BUGS AND LIMITATIONS
       At this time there are no known bugs in this module. Please report
       problems	to the author, patches are always welcome.

       Use Github tracker <https://github.com/nohuhu/RPC-ExtDirect/issues> to
       open bug	reports, this is the easiest and quickest way to get your
       issue fixed.

SEE ALSO
       Take a look at these useful modules that	are a part of RPC::ExtDirect
       family:

       o   RPC::ExtDirect::Server - a prebuilt Ext.Direct server in Perl,
	   based on HTTP::Server::Simple.

       o   RPC::ExtDirect::Client - a synchronous Ext.Direct client in Perl.

       o   RPC::ExtDirect::Client::Async - a fully asynchronous	Ext.Direct
	   client in Perl, with	API compatible to RPC::ExtDirect::Client.

       o   Test::ExtDirect - a set of helper subroutines that make unit
	   testing Ext.Direct APIs a breeze.

       Also you	can find additional information	in the following Web site
       links:

       o   Ext JS product website <http://www.sencha.com/products/extjs/>

       o   Sencha Touch	product	website
	   <http://www.sencha.com/products/touch/>

       o   Ext.Direct specification
	   <http://www.sencha.com/products/extjs/extdirect/>

       o   Ext.Direct support forum
	   <http://www.sencha.com/forum/forumdisplay.php?47>

       o   Ext.Direct plugin for jQuery	<https://github.com/ha-sash/jquery-
	   ext-direct-client>

ACKNOWLEDGEMENTS
       I would like to thank IntelliSurvey, Inc	for sponsoring my work on
       versions	2.x and	3.x of the RPC::ExtDirect suite	of modules.

LICENSE	AND COPYRIGHT
       Copyright (c) 2011-2016 by Alex Tokarev <tokarev@cpan.org>.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself. See	"perlartistic".

perl v5.32.0			  2016-10-10		     RPC::ExtDirect(3)

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION AND EXAMPLES | WHEN TO USE IT, AND WHY | HOW TO USE | METHODS AND CALLING CONVENTIONS | CALL METADATA | HOOKS | ENVIRONMENT OBJECTS | FILE UPLOADS | GATEWAYS | MIGRATING FROM PREVIOUS VERSIONS | DEPENDENCIES | BUGS AND LIMITATIONS | SEE ALSO | ACKNOWLEDGEMENTS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RPC::ExtDirect&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help