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

FreeBSD Manual Pages

  
 
  

home | help
RPC::ExtDirect::ConfigUser Contributed Perl DocumentaRPC::ExtDirect::Config(3)

NAME
       RPC::ExtDirect::Config -	Centralized configuration handling for
       RPC::ExtDirect

SYNOPSIS
	   use RPC::ExtDirect::Config;

	   my $cfg = RPC::ExtDirect::Config->new(
	       option1 => 'value1',
	       option2 => 42,
	       ...
	   );

	   my $option1 = $cfg->option1();
	   $cfg->option1('value2');

DESCRIPTION
       This package implements configuration handling for various
       RPC::ExtDirect modules in a centralized and consistent fashion.

       RPC::ExtDirect::Config also supports the	legacy configuration approach
       via package global variables, as	implemented in RPC::ExtDirect 1.x and
       2.x.  Note that using package global vars is deprecated,	and Config
       will emit a warning for every such variable. The	value in the variable
       will still take effect, despite the warning.

CHAINED	OPTIONS
       Besides simple configuration options, RPC::ExtDirect::Config supports
       "chained" options that fall back	to another option when no value	is
       provided.

       Assume an option	"foo" that is chained to option	"bar". When assigning
       values, Config will set both "foo" and "bar" independently. When
       retrieving value	for option "bar", Config will first look if "bar" has
       any value defined for it	and return it if there is one. However,	when
       there is	no value defined for "bar", Config will	then "fall back" to
       the value of "foo", and return it instead.

       This allows for very granular configuration of different	parts of the
       RPC::ExtDirect stack. For example, you can turn on global debugging
       with the	"debug"	option,	and turn off Request debugging by setting
       "debug_request" to falsy	value.

       It is possible to add your own configuration options, both simple and
       chained.	Read RPC::ExtDirect::Config source to see how it is done.

ACCESSOR METHODS
       For every option	held in	a Config instance, there are two accessor
       methods created automatically: a	getter/setter, and a predicate.
       Assuming	an option named	"foo", these accessors will be:

       has_foo()
	   A predicate method is used to check if a value has been set for an
	   option, even	if that	value is undefined. Note that a	predicate is
	   never chained, and if a "foo" value does not	exist the predicate
	   will	return false without falling back to "bar".

       foo()
	   A getter/setter method can be used to read and write	the value.
	   Called with no arguments, it	acts as	a getter and returns the value
	   for an option; when called with one or more arguments, it will
	   replace the existing	value with the first argument, ignoring	any
	   others.

OPTIONS
       The stock RPC::ExtDirect::Config	supports the following options:

       api_action_class
	   Class name to use instead of	RPC::ExtDirect::API::Action when
	   creating the	API tree. Action objects instantiated from this	class
	   will	hold collections of Method objects.

	   Use this option to override or inject new functionality in Action
	   objects.

	   Default: 'RPC::ExtDirect::API::Action'.

       api_method_class
	   Class name to use instead of	RPC::ExtDirect::API::Method when
	   creating the	API tree. Method objects will be instantiated from
	   this	class.

	   Use this option to override or inject new functionality in Method
	   objects.

	   Default: 'RPC::ExtDirect::API::Method'.

       api_hook_class
	   Class name to be used instead of RPC::ExtDirect::API::Hook when
	   creating the	API tree. Hook objects will be instantiated from this
	   class.

	   Use this option to override or inject new functionality in Hook
	   objects.

	   Default: 'RPC::ExtDirect::API::Hook'.

       api_full_action_names
	   When	set to truthy value, API Action	names will default to package
	   name	with '::' replaced with	dots: 'Foo::Bar::Baz' ->
	   'Foo.Bar.Baz', instead of using only	the last chunk of the package
	   name: 'Foo::Bar::Baz' -> 'Baz'.

	   Default: "!1" (false).

       debug
	   Turn	global debugging flag on or off.

	   Default: "!1" (false).

       debug_api
	   Turn	API debugging on or off. At this time, the only	effect is that
	   the API JavaScript is pretty	printed	when debugging.

	   Default: "undef", chained to: "debug".

       debug_eventprovider
	   Turn	debugging on/off for RPC::ExtDirect::EventProvider module.

	   Default: "undef", chained to: "debug".

       debug_serialize
	   Turn	debugging on/off for serialization method in
	   "RPC::ExtDirect::Serializer"	module.	This option only affects "from
	   Perl	to JSON" conversion.

	   Default: "undef", chained to: "debug".

       debug_deserialize
	   Turn	debugging on/off for deserialization method in
	   "RPC::ExtDirect::Serializer"	module.	This option only affects "from
	   JSON	to Perl" conversion.

	   Default: "undef", chained to: "debug".

       debug_request
	   Turn	debugging on/off for "RPC::ExtDirect::Request" module. When
	   debugging is	on, Request will provide verbose exceptions. There is
	   no other effect at this time, but this can change in	the future.

	   To make exceptions informational without turning on debugging, set
	   "verbose_exceptions"	option.

	   Default: "undef", chained to: "debug".

       debug_router
	   Turn	debugging on/off for "RPC::ExtDirect::Router" module. When
	   debugging is	on, all	Requests or Exceptions generated in the	Router
	   will	provide	verbose	exceptions. There are no other effects at this
	   time, but this can change in	the future.

	   To make exceptions informational without turning on debugging, set
	   "verbose_exceptions"	option.

	   Default: "undef", chained to: "debug".

       exception_class
	   Class name to be used instead of "RPC::ExtDirect::Exception"	when
	   instantiating new Exception objects.

	   This	option will affect all places in the code that can throw
	   Exceptions, unless overridden by specific options below.

	   Default: 'RPC::ExtDirect::Exception'.

       exception_class_serialize
	   Class name to be used when instantiating Exception objects thrown
	   in serialization method of "RPC::ExtDirect::Serializer" module.

	   This	option will not	affect any other place in the code that	can
	   throw Exceptions.

	   Default: "undef", chained to: "exception_class".

       exception_class_deserialize
	   Class name to be used when instantiating Exception objects thrown
	   in deserialization method of	"RPC::ExtDirect::Serializer" module.

	   This	option will not	affect any other place in the code that	can
	   throw Exceptions.

	   Default: "undef", chained to: "exception_class".

       exception_class_request
	   Class name to be used when instantiating Exception objects thrown
	   in "RPC::ExtDirect::Request", when a	Request	is being processed.

	   This	option will not	affect any other place in the code that	can
	   throw Exceptions.

	   Default: "undef", chained to: "exception_class".

       request_class
	   Class name to be used instead of "RPC::ExtDirect::Request" when
	   instantiating new Request objects.

	   Default: 'RPC::ExtDirect::Request'.

       request_class_deserialize
	   Class name to be used when instantiating Request objects in
	   deserialization method of "RPC::ExtDirect::Serializer" module.

	   This	option will not	affect any other place in the code.

	   Default: "undef", chained to: "request_class".

       request_class_eventprovider
	   Class name to be used instead of
	   "RPC::ExtDirect::Request::PollHandler" when instantiating Request
	   objects in "RPC::ExtDirect::EventProvider" module.

	   PollHandler is a subclass of	Request; when configuring this option
	   use a subclass of PollHandler.

	   Default: 'RPC::ExtDirect::Request::PollHandler'.

       serializer_class
	   Class name to be used instead of "RPC::ExtDirect::Serializer" when
	   instantiating new objects to	be used	to serialize data (Perl	to
	   JSON).

	   Default: 'RPC::ExtDirect::Serializer'.

       serializer_class_api
	   Class name to be used when instantiating Serializer objects used to
	   serialize API data.

	   Default: "undef", chained to: "serializer_class".

       serializer_class_eventprovider
	   Class name to be used when instantiating Serializer objects used to
	   serialize Request results in	"RPC::ExtDirect::EventProvider"
	   module.

	   Default: "undef", chained to: "serializer_class".

       serializer_class_router
	   Class name to be used when instantiating Serializer objects used to
	   serialize Request results in	"RPC::ExtDirect::Router" module.

	   Default: "undef", chained to: "serializer_class".

       deserializer_class
	   Class name to be used instead of "RPC::ExtDirect::Serializer" when
	   instantiating new objects to	be used	to deserialize data (JSON to
	   Perl).

	   Default: 'RPC::ExtDirect::Serializer'.

       deserializer_class_router
	   Class name to be used when instantiating Serializer objects used to
	   deserialize incoming	Request	data in	"RPC::ExtDirect::Router"
	   module.

	   Default: "undef", chained to: "deserializer_class".

       json_options
	   Hashref of options to be passed to "JSON::to_json" and
	   "JSON::from_json" functions.	This is	a global option	that affects
	   both	directions for all JSON-related	operations.

	   See JSON for	explanation of the options.

	   Default: "undef".

       json_options_serialize
	   Options to be passed	to "JSON::to_json" when	serializing outbound
	   data.  This will affect only	"Perl to JSON" direction.

	   Default: "undef", chained to: "json_options".

       json_options_deserialize
	   Options to be passed	to "JSON::from_json" function when
	   deserializing inbound data. This will affect	only "JSON to Perl"
	   direction.

	   Default: "undef", chained to: "json_options".

       router_class
	   Class name to be used when instantiating Router objects instead of
	   "RPC::ExtDirect::Router". This config option	is not used directly
	   by the core RPC::ExtDirect code, but	rather by the gateways like
	   CGI::ExtDirect and Plack::Middleware::ExtDirect.

	   Default: 'RPC::ExtDirect::Router'.

       eventprovider_class
	   Class name to be used when instantiating EventProvider objects
	   instead of "RPC::ExtDirect::EventProvider". Similar to
	   "router_class", this	option is used by the gateway modules.

	   Default: 'RPC::ExtDirect::EventProvider'.

       verbose_exceptions
	   Turn	informative exceptions on/off. For whatever reason, Ext.Direct
	   spec	requires server	stack to return	detailed exceptions in
	   debugging mode only,	replacing them with generic "An	error has
	   occured" in production mode.	 Most probably this was	done to
	   increase application	security, but as the result it hinders
	   development and support greatly.

	   RPC::ExtDirect tries	to be spec compliant, but provides a way to
	   turn	on verbose exceptions via this config option. This will	not
	   affect debugging, only exceptions returned to the client side.

	   Default: "!1" (false).

       api_path
	   URI path for	the Ext.Direct API generator handler. This option is
	   not used directly by	the core RPC::ExtDirect	code; gateways like
	   CGI::ExtDirect and Plack::Middleware::ExtDirect use this option to
	   map incoming	HTTP GET requests to the RPC::ExtDirect::API code that
	   generates the JavaScript API	declaration for	the client side
	   service discovery request.

	   Default: '/extdirectapi'.

       router_path
	   URI path for	the Ext.Direct router handler. This path is advertised
	   in the Ext.Direct API declaration generated by the API handler, to
	   be used by the client side when making Ext.Direct routing requests.

	   Default: '/extdirectrouter'.

       poll_path
	   URI path for	the Ext.Direct poll handler. This path is advertised
	   in the Ext.Direct API declaration generated by the API handler, to
	   be used by the client side when making Ext.Direct event polling
	   requests.

	   Default: '/extdirectevents'.

       remoting_var
	   Name	of the JavaScript variable for the remoting API	declaration.
	   The JavaScript code generated by the	API handler will look like
	   this:

	   "Ext.app.REMOTING_API={...}"

	   Default: 'Ext.app.REMOTING_API'.

       polling_var
	   Name	of the JavaScript variable for the polling API declaration.
	   The JavaScript code generated by the	API handler will look like
	   this:

	   "Ext.app.POLLING_API={...}"

	   Default: 'Ext.app.POLLING_API'.

       namespace
	   JavaScript namespace	to be declared in the remoting API. See
	   Ext.direct.RemotingProvider
	   <http://docs.sencha.com/extjs/5.1/5.1.0-apidocs/#!/api/Ext.direct.RemotingProvider>
	   documentation for more detailed information on this option.

	   Default: '' (empty string).

       auto_connect
	   When	set to truthy value, RPC::ExtDirect::API will add JavaScript
	   code	to automatically set up	RemotingProvider and PollingProvider
	   on the client side to the Ext.Direct	declaration JavaScript chunk,
	   so that JavaScript application won't	need to	do that.

	   This	option is deprecated as	of RPC::ExtDirect 3.0, and should not
	   be used going forward.

	   Default: "!1" (false).

       no_polling
	   Explicitly disable polling API advertisements in the	generated
	   Ext.Direct API, even	if there are EventProvider modules registered
	   with	RPC::ExtDirect stack. This option is mostly used for testing
	   and debugging.

	   Default: "!1" (false).

       max_retries
	   Number of times for the client side to re-attempt delivery on
	   failure of a	call. (see Ext.direct.RemotingProvider.maxRetries
	   <http://docs.sencha.com/extjs/5.1/5.1.0-apidocs/#!/api/Ext.direct.RemotingProvider-
	   cfg-maxRetries>).

	   Default: "undef".

       timeout
	   The timeout for the client side to use for each request (see
	   Ext.direct.RemotingProvider.timeout
	   <http://docs.sencha.com/extjs/5.1/5.1.0-apidocs/#!/api/Ext.direct.RemotingProvider-
	   cfg-timeout>).

	   Default: "undef".

CONFIG OBJECT INTERFACE
       RPC::ExtDirect::Config provides several public methods:

       "new"
	   Constructor.	Returns	a new RPC::ExtDirect::Config object populated
	   with	key/value pairs	passed in the arguments. If an option is not
	   specified, a	default	value will be assumed; see "OPTIONS" for more
	   information.

	   The supported legacy	package	global variables will be read before
	   the arguments are processed;	thus any option	passed directly	to
	   constructor will override its namesake in a package global. This
	   won't prevent the warnings from being emitted; package global vars
	   are strongly	deprecated and should not be used. There is no way to
	   disable the warnings.

	   This	method accepts named arguments in a hash or hashref.

	   Parameters: see "OPTIONS".

       "clone"
	   Constructor,	instance method. Returns a new RPC::ExtDirect::Config
	   object with options copied from the instance	"clone"	was called on.
	   This	method only does shallow copying, i.e. any config option that
	   is a	reference will refer to	the same underlying object.

       "read_global_vars"
	   Instance method. Reads legacy package global	variables used to
	   configure RPC::ExtDirect in versions	1.x and	2.x; issues the
	   warnings about their	usage. The warnings cannot be turned off;
	   change your code not	to use package globals instead.

       "add_accessors"
	   Class/instance method. Adds accessor	methods	from arguments;	this
	   can be used in subclasses to	extend the list	of Config options.
	   This	method accepts named arguments in a hash.

       "set_options"
	   Instance method. Sets one or	more Config options in the object it
	   was called on. Accepts named	arguments in a hash or hashref.

	   Parameters: see "OPTIONS".

       "get_router_path"
	   Class method. Returns the current "router_path" value from the
	   global API Config instance.

	   This	method is DEPRECATED and provided only for backward
	   compatibility.  Use "router_path" accessor method on	a Config
	   instance instead.

       "get_poll_path"
	   Class method. Returns the current "poll_path" value from the	global
	   API Config instance.

	   This	method is DEPRECATED and provided only for backward
	   compatibility.  Use "poll_path" accessor method on a	Config
	   instance instead.

       "get_remoting_var"
	   Class method. Returns the current "remoting_var" value from the
	   global API Config instance.

	   This	method is DEPRECATED and provided only for backward
	   compatibility.  Use "remoting_var" accessor method on a Config
	   instance instead.

       "get_polling_var"
	   Class method. Returns the current "polling_var" value from the
	   global API Config instance.

	   This	method is DEPRECATED and provided only for backward
	   compatibility.  Use "polling_var" accessor method on	a Config
	   instance instead.

SEE ALSO
       More documentation can be found in RPC::ExtDirect::API and
       RPC::ExtDirect modules.

perl v5.32.0			  2015-01-30	     RPC::ExtDirect::Config(3)

NAME | SYNOPSIS | DESCRIPTION | CHAINED OPTIONS | ACCESSOR METHODS | OPTIONS | CONFIG OBJECT INTERFACE | SEE ALSO

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

home | help