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

Default: undef.

timeout

The timeout for the client side to use for each request (see Ext.direct.RemotingProvider.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.