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.