RPC::ExtDirect::API::Hook - Ext.Direct Method wrappers
Hooks are RPC::ExtDirect's way of implementing Method modifiers for the (relatively) rare cases when you need them but don't want to bring in the whole nine yards of Moose.
A hook is a Perl subroutine (can be anonymous, too). Hooks can be of three types:
before
before hook is called before a Method is invoked, and can be used to change Method arguments or cancel Method execution. This hook must return numeric value 1 to allow Method call. Any other value will be interpreted as an Ext.Direct Result; it will be returned to the client side and the Method never gets called.
1
Note that RPC::ExtDirect will not make any assumptions about this hook's return value; a false value like '' or 0 will probably not look too helpful from the client side's point of view.
''
0
If this hook throws an exception, it will be returned as an Ext.Direct Exception to the client side, and the Method does not execute.
instead
instead hook replaces the Method it is assigned to. It is the hook sub's responsibility to invoke (or not) the Method code and return appropriate Result.
If this hook throws an exception, it is interpreted as if the Method threw it.
This hook is analogous to Moose's around method modifier, except that around would be a bit of a misnomer since the hook code is actually called instead of the Method. Hence the name.
around
after
after hook is called after the Method code or instead hook. This hook cannot affect Method execution, it is intended mostly for logging and testing purposes; its input includes Method's Result or Exception.
This hook's return value and thrown exceptions are ignored.
Hooks can be defined on three levels, in order of precedence: Method, Action, and global. For each Method, only one hook of each type can be applied. Hooks specified in Method definition take precedence over all other; if no Method hook is found then Action level hook applies; and if there is no Action hook then global hook gets called, if any.
To avoid using hooks for a particular method, use "NONE" or undef instead of coderef; this way you can specify global and/or Action hooks and exclude some specific Methods piecemeal.
"NONE"
undef
See more in the documentation for the constructor: "new".
Hook subroutine is called as a class method, i.e. first argument is name of the package in which this sub was defined. Ignore it if you don't need it.
Hooks receive a hash of the following arguments:
action
Ext.Direct Action name for the Method.
DEPRECATED. Use method_ref instead: $method_ref->action
$method_ref->action
method
Ext.Direct Method name
DEPRECATED. Use method_ref instead: $method_ref->name
$method_ref->name
package
Name of the package (not Action) where the Method is declared
DEPRECATED. Use method_ref instead: $method_ref->package
$method_ref->package
code
Coderef to the Method subroutine
DEPRECATED. Use method_ref instead: $method_ref->code
$method_ref->code
param_no
Number of parameters when Method accepts ordered arguments
DEPRECATED. Use method_ref instead: $method_ref->len
$method_ref->len
param_names
Arrayref with names of parameters when Method accepts named arguments
DEPRECATED. Use method_ref instead: $method_ref->params
$method_ref->params
formHandler
True if Method handles form submits
DEPRECATED. Use method_ref instead: $method_ref->formHandler
$method_ref->formHandler
pollHandler
True if Method handles Event poll requests
DEPRECATED. Use method_ref instead: $method_ref->pollHandler
$method_ref->pollHandler
arg
Arrayref with the invocation arguments when Method accepts ordered args, single Environment object for Poll handlers, hashref otherwise.
Note that this is a direct link to the Method's @_ so it is possible to modify the arguments in before hook if you need to.
@_
env
Environment object for the invocation. Like arg, this is a direct reference to the same object that will be passed to the Method, so it's possible to modify the env object in the before hook.
Coderef to before hook for that Method, or undef
DEPRECATED. Use before_ref instead: $before_ref->code
$before_ref->code
Coderef to instead hook for that Method, or undef
DEPRECATED. Use instead_ref instead: $instead_ref->code
$instead_ref->code
Coderef to "after" hook for that Method, or undef
DEPRECATED. Use after_ref instead: $after_ref->code
$after_ref->code
result
For after hooks, the Result returned by the Method or instead hook, whichever got called. Not defined for before and instead hooks.
exception
For after hooks, an exception ($@) thrown by the Method or instead hook, if any. Not defined for before and instead hooks.
$@
method_called
For after hooks, a reference to the actual code called as Method, if any. Can be either the Method code itself, instead hook or undef if the invocation was canceled.
orig
A closure that binds Method coderef to its current arguments, allowing to call it as easily as $params{orig}->()
$params{orig}->()
RPC::ExtDirect::API::Hook provides several public methods:
HOOK_TYPES
Class/instance method. Returns the list of supported hook types.
new
Constructor. Returns a new RPC::ExtDirect::API::Hook object. Accepts named arguments in a hash.
Parameters:
type
Hook type. This parameter is mandatory.
Hook code. This parameter is mandatory, and it can take one of the following forms:
'NONE' or undef to cancel hook execution for the corresponding type
'NONE'
A coderef for the hook sub to run for the corresponding type
Package and subroutine address to call at the hook execution time, like 'Foo::Bar::baz'. This allows late code binding without loading the corresponding package early.
'Foo::Bar::baz'
run
Run the hook and return the result. This method accepts named arguments in a hash.
api
An instance of RPC::ExtDirect::API.
This parameter is mandatory.
An environment object for this hook invocation.
Method arguments, either array- or hashref depending on the Method's calling convention.
The result of a Method's invocation for an after hook.
This parameter is mandatory for after hooks.
An exception thrown by a Method or a hook. This parameter is only meaningful for after hooks, and is optional.
method_ref
An instance of RPC::ExtDirect::API::Method.
callee
A reference to the code executed for a Method; can be either the Method code, or its instead hook code.
For RPC::ExtDirect::API::Hook, the following accessor methods are provided:
Return the "type" of this Hook object.
Return the "code" of this Hook object.
Return the package name for the Hook code.
sub_name
Return the subroutine name for the Hook code. This will yield meaningful result only when "code" was set to a string 'Package::sub'.
runnable
Return true if this Hook's code is runnable and can be executed.
To install RPC::ExtDirect, copy and paste the appropriate command in to your terminal.
cpanm
cpanm RPC::ExtDirect
CPAN shell
perl -MCPAN -e shell install RPC::ExtDirect
For more information on module installation, please visit the detailed CPAN module installation guide.