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

FreeBSD Manual Pages

  
 
  

home | help
RPC::ExtDirect::API::HUser3Contributed Perl DocumeRPC::ExtDirect::API::Hook(3)

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:

		   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.

perl v5.24.1			  2014-06-13	  RPC::ExtDirect::API::Hook(3)

NAME | DESCRIPTION | TYPES | HIERARCHY | CALLING CONVENTION | HOOK OBJECT INTERFACE | ACCESSOR METHODS

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

home | help