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

FreeBSD Manual Pages

  
 
  

home | help
RPC::ExtDirect::API::MUserdContributed Perl DocuRPC::ExtDirect::API::Method(3)

NAME
       RPC::ExtDirect::API::Method - Ext.Direct	Method object

DESCRIPTION
       This package implements an Ext.Direct Method object that	holds Method's
       properties and can be subclassed	to change its behavior.

       This document does not provide an overview of a Method. For that
       information, see	"ACTIONS AND METHODS" in RPC::ExtDirect::API.

METHOD OBJECT INTERFACE
       RPC::ExtDirect::API::Method provides several public methods:

       "HOOK_TYPES"
	   Class/instance method. Returns the list of supported	hook types.
	   See "HOOKS" in RPC::ExtDirect for more information.

       "new"
	   Constructor.	Returns	a new RPC::ExtDirect::API::Method object.
	   Accepts named arguments in a	hash.

	   Parameters:

	   "config"
		   A RPC::ExtDirect::Config instance to	be used	with this
		   Method.

		   This	parameter is mandatory.

	   "action"
		   An Action name this Method belongs to.

		   This	parameter is mandatory.

	   "name"  This	Method's name. Should be unique	among the methods in
		   an Action.

		   This	parameter is mandatory.

	   "len"   Number of parameters	accepted by an ordered Method.

		   This	parameter is mandatory for ordered Methods, and	should
		   not be defined for Methods of other calling conventions.

	   "params"
		   An arrayref with names of parameters	accepted by a named
		   Method.

		   This	parameter is mandatory for named Methods, and should
		   not be defined for Methods of other calling conventions.

	   "formHandler"
		   A boolean flag indicating that this Method is a Form
		   Handler.

		   This	parameter is mandatory for Form	handler	Methods, and
		   should not be defined for Methods of	other calling
		   conventions.

	   "pollHandler"
		   A boolean flag indicating that this Method is a Poll
		   Handler.

		   This	parameter is mandatory for Poll	handler	Methods, and
		   should not be defined for Methods of	other calling
		   conventions.

	   "package"
		   Name	of the package this Method's code belongs to.

		   This	parameter is mandatory.

	   "strict"
		   A boolean flag that enables or disables lazy	parameter
		   checking for	a named	Method.

		   This	parameter is optional and should only be used with
		   named Methods.

	   "before|instead|after"
		   A Hook definition of	the specified type for this Method.
		   See "code" in RPC::ExtDirect::API::Hook for the list	of
		   supported options.

		   All three of	these parameters are optional.

	   "env_arg"
		   Use this parameter to indicate that this Method needs an
		   environment object passed to	it.  Before RPC::ExtDirect
		   3.0,	a Method was passed an environment object on every
		   invocation; this behavior caused problems in	certain	cases.

		   For ordered Methods and Poll	handler	Methods, "env_arg"
		   parameter should be a number	for the	@_ position that the
		   env object should be	spliced	in. To receive the env object
		   as the first	argument, use 0; to receive it as the last
		   argument, use some number greater than the number of
		   parameters accepted by the Method (e.g. 99).

		   For named Methods and Form handler Methods, "env_arg"
		   parameter should be a name of the hash key in which the
		   environment object is passed.

	   "upload_arg"
		   Use this parameter to change	the hash key name in which the
		   file	upload array is	passed to a Form handler Method.
		   Default is 'file_uploads'.

	   "decode_params"
		   This	optional parameter may contain the list	of fields that
		   should be decoded from JSON for a formHandler Method. Does
		   nothing for Methods with other calling conventions.

	   "metadata"
		   Use this parameter to declare that this Method supports
		   call	metadata. The value of this key	should be a hashref
		   with	the following properties:

		   "len"   Declares that this Method accepts ordered (by
			   position) metadata with this	number of mandatory
			   values, with	the number > 0.	 The metadata values
			   will	be passed to the Method	in arrayref.

			   This	parameter is mutually exclusive	with "params"
			   below.

		   "params"
			   Declares that this Method accepts named metadata
			   values in a hashref.	 The value of "params" is also
			   arrayref with the names of mandatory	metadata
			   values. The declaration arrayref may	be empty to
			   indicate that all metadata values are optional and
			   should not be checked for existence.

			   This	parameter is mutually exclusive	with "len"
			   above.

		   "strict"
			   Set this option to falsy value to have all metadata
			   key-value pairs passed to the Method. The default
			   behavior is similar to named	main arguments,	where
			   all undeclared parameters will be discarded and
			   only	the declared ones will be passed to the
			   Method.

		   "arg"   Defines the position	of the metadata	argument for
			   Ordered methods, or the name	of the metadata
			   argument for	Named methods. Note that this is about
			   the calling convention of the main arguments, not
			   metadata itself!

			   For Named methods, "arg" defaults to	"metadata";
			   for Ordered methods there is	no default and an
			   error will be raised	if "arg" is omitted.

	   other   Any other hash key with the corresponding value will	be
		   stored in the Method	object.

       "get_api_definition"
	   Instance method. Returns a hashref with the Method's	definition for
	   the API declaration,	or an empty list if the	Method should not be
	   included in the remoting API	published to the client	side.

	   If you need to affect Ext.Direct API	generation, this method	is the
	   place to do it. One example option is running a check on the	user's
	   credentials,	and deciding to	include	or exclude this	particular
	   Method from the API generated for this user.

	   Parameters (by position):

	   o	   An environment object for this invocation.

		   The stock "get_api_definition" method does not use this
		   environment object; it is provided to be potentially
		   utilized in subclasses.

       "get_api_definition_compat"
	   Instance method. Returns a hashref with the Method's	definition
	   that	is backwards compatible	with versions 1.x and 2.x of
	   RPC::ExtDirect.

	   This	method should not be used under	normal circumstances.

       "run"
	   Instance method. Runs the Method's subroutine code and returns the
	   Result of the invocation. Accepts named arguments in	a hash.

	   The Method subroutine code is always	called as a class method.  For
	   Poll	handlers, the code is called in	a list context;	for Methods of
	   other calling conventions, the code is called in scalar context.

	   Parameters:

	   "arg"   The actual arguments	that should be passed to the Method's
		   code. This should be	an arrayref for	ordered	Methods	and
		   Poll	handlers, or a hashref the other calling convention.

		   Note	that the value of this parameter is the	same as
		   returned by "prepare_method_arguments" method.

       "check_method_arguments"
	   Instance method. Accepts one	positional argument, which is incoming
	   data	that should be validated as Method's arguments.	A specific
	   checker method (see below) will be executed to run the actual
	   checks on this data;	that method is expected	to "die" with an
	   error, or return 1 if the arguments are valid.

       "check_ordered_arguments"
	   Instance method. Takes input	data and checks	that it's an arrayref,
	   and it has enough elements to satisfy the "len" requirement of the
	   Method.

       "check_ordered_metadata"
	   Instance method. Takes input	metadata and checks that it's an
	   arrayref, and it has	enough values to satisfy the metadata "len"
	   requirement of the Method.

	   Metadata will only be checked for Methods that accept it.

       "check_named_arguments"
	   Instance method. Takes input	data and checks	that it's a hashref,
	   and that keys for all mandatory "params" exist in that hashref.  If
	   the Method declares empty "params", the check will pass and
	   effectively all arguments will be passed on to the Method call.

       "check_named_metadata"
	   Instance method. Takes input	metadata and performs the checks
	   similar to those made for named arguments.

	   Metadata will only be checked for Methods that accept it.

       "check_formHandler_arguments"
	   Instance method. Takes input	data and checks	that it's a hashref.
	   Since a Form	Handler	arguments are not known	before invocation, no
	   other checks	are performed.

       "check_pollHandler_arguments"
	   Instance method. Does not in	fact run any checks, since Poll
	   Handler Methods are not supposed to be called directly and do not
	   receive any arguments.

       "prepare_method_arguments"
	   Instance method. Accepts named arguments in a hash, and runs	a
	   specific preparer method (see below)	on these arguments, depending
	   on the Method's calling convention.

	   The return value of this method is the arguments fed	to the
	   Method's code invoked in the	"run" method.

	   Parameters:

	   "env"   An environment object that is to be passed to the Method's
		   code	if Method has requested	it.

	   "input" Method arguments passed from	the client side. The type of
		   the input depends on	the Method's calling convention.

	   "upload"
		   Arrayref of file upload hashrefs. See "FILE UPLOADS"	in
		   RPC::ExtDirect for more information.

		   This	parameter is only defined for Form handler methods
		   when	uploaded files are present.

       "prepare_ordered_arguments"
	   Instance method. Takes "input" arguments for	the Method and returns
	   an arrayref conformant to the ordered Method's definition.  This
	   arrayref will optionally contain env	object if requested, and/or
	   metadata.

       "prepare_ordered_metadata"
	   Instance method. Takes input	metadata and returns an	arrayref
	   conformant to the Method's metadata definition.

       "prepare_named_arguments"
	   Instance method. Takes "input" arguments for	the Method and returns
	   a hashref conformant	to the named Method's definition.  This
	   hashref will	optionally contain env object if requested, and/or
	   metadata.

       "prepare_formHandler_arguments"
	   Instance method. Takes "input" arguments for	the Method and returns
	   a hashref conformant	to the Form Handler Method's definition. This
	   hashref will	optionally contain env object if requested, and/or
	   metadata.

       "prepare_pollHandler_arguments"
	   Instance method. Returns an arrayref	conformant to Poll handler
	   method's definition.	This arrayref will optionally contain env
	   object if requested.

ACCESSOR METHODS
       For RPC::ExtDirect::API::Method,	the following accessor methods are
       provided:

       "config"
	   Return the RPC::ExtDirect::Config instance assigned to this Method
	   object.

       "action"
	   Return the Action name for this Method object.

       "name"
	   Return the Method name for this Method object.

       "len"
	   Return the number of	the parameters accepted	by this	ordered
	   Method.

	   For any other calling convention, "len" should be "undef".

       "params"
	   Return the names of the mandatory parameters	accepted by this named
	   Method.

	   For any other calling convention, "params" should be	"undef".

       "formHandler"
	   Return true if this Method is a Form	Handler.

	   For any other calling convention, "formHandler" should be "undef".

       "pollHandler"
	   Return true if this Method is a Poll	Handler.

	   For any other calling convention, "pollHandler" should be "undef".

       "is_ordered"
	   Return true if this is an ordered Method.

       "is_named"
	   Return true if this is a named Method.

       "strict"
	   Return false	for Named methods with lazy parameter checking.

	   Defaults to true.

       "package"
	   Return the name of the package this Method's	code belongs to.

       "env_arg"
	   Return the name or position for the environment object parameter.

	   See "new".

       "upload_arg"
	   Return the name of the file upload parameter	for a Form handler.

	   See "new".

       "before|instead|after"
	   Return the Hook object for the corresponding	hook slot assigned to
	   this	Method.

perl v5.24.1			  2015-04-01	RPC::ExtDirect::API::Method(3)

NAME | DESCRIPTION | METHOD 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::Method&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help