NAME

RPC::ExtDirect::API::Hook - Ext.Direct Method wrappers

DESCRIPTION

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.

TYPES

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.

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.

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.

"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.

HIERARCHY

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.

See more in the documentation for the constructor: "new".

CALLING CONVENTION

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": Ext.Direct Method name
DEPRECATED. Use method_ref instead: "$method_ref->name"
"package": Name of the package (not Action) where the Method is declared
DEPRECATED. Use method_ref instead: "$method_ref->package"
"code": Coderef to the Method subroutine
DEPRECATED. Use method_ref instead: "$method_ref->code"
"param_no": Number of parameters when Method accepts ordered arguments
DEPRECATED. Use method_ref instead: "$method_ref->len"
"param_names": Arrayref with names of parameters when Method accepts named arguments
DEPRECATED. Use method_ref instead: "$method_ref->params"
"formHandler": True if Method handles form submits
DEPRECATED. Use method_ref instead: "$method_ref->formHandler"
"pollHandler": True if Method handles Event poll requests
DEPRECATED. Use method_ref instead: "$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.
"before": Coderef to "before" hook for that Method, or undef
DEPRECATED. Use before_ref instead: "$before_ref->code"
"instead": Coderef to "instead" hook for that Method, or undef
DEPRECATED. Use instead_ref instead: "$instead_ref->code"
"after": Coderef to "after" hook for that Method, or undef
DEPRECATED. Use after_ref instead: "$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}->()"

HOOK OBJECT INTERFACE

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.
"code": 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
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.

"run": Run the hook and return the result. This method accepts named arguments in a hash.
Parameters:

"api": An instance of RPC::ExtDirect::API.
This parameter is mandatory.
"env": An environment object for this hook invocation.
This parameter is mandatory.
"arg": Method arguments, either array- or hashref depending on the Method's calling convention.
This parameter is mandatory.
"result": The result of a Method's invocation for an "after" hook.
This parameter is mandatory for "after" hooks.
"exception": 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.
This parameter is mandatory.
"callee": A reference to the code executed for a Method; can be either the Method code, or its "instead" hook code.
This parameter is mandatory for "after" hooks.

ACCESSOR METHODS

For RPC::ExtDirect::API::Hook, the following accessor methods are provided:

"type": Return the "type" of this Hook object.
"code": Return the "code" of this Hook object.
"package": 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.