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
RPC::ExtDirect::Config(3) User Contributed Perl Documentation RPC::ExtDirect::Config(3)

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

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

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.

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.

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.

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".

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.

More documentation can be found in RPC::ExtDirect::API and RPC::ExtDirect modules.
2015-01-30 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

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