GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  RPC::EXTDIRECT::API::HOOK (3)

.ds Aq ’

NAME

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

CONTENTS

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.

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->action

method Ext.Direct Method name

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->name

package Name of the package (not Action) where the Method is declared

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->package

code Coderef to the Method subroutine

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->code

param_no Number of parameters when Method accepts ordered arguments

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->len

param_names Arrayref with names of parameters when Method accepts named arguments

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->params

formHandler True if Method handles form submits

<B>DEPRECATEDB>. Use method_ref instead: $method_ref->formHandler

pollHandler True if Method handles Event poll requests

<B>DEPRECATEDB>. 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

<B>DEPRECATEDB>. Use before_ref instead: $before_ref->code

instead Coderef to instead hook for that Method, or undef

<B>DEPRECATEDB>. Use instead_ref instead: $instead_ref->code

after Coderef to after hook for that Method, or undef

<B>DEPRECATEDB>. 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:
o NONE or undef to cancel hook execution for the corresponding type
o A coderef for the hook sub to run for the corresponding type
o 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 RPC::EXTDIRECT::API::HOOK (3) 2014-06-13

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.