NAME

RPC::ExtDirect::Migration - Migration notes for RPC::ExtDirect

MIGRATING TO 3.x FROM 1.X AND 2.X

RPC::ExtDirect version 3.0 represents a major effort to refactor module internals, simplify the architecture and make the whole suite more robust. While every precaution has been taken to make the new version as much backwards compatible as possible, still the scale of the internal changes was so big that some things may have been unintentionally broken and not caught by unit tests. If you encounter any regressions, please file a bug report.

Here is the list of things to keep in mind while upgrading to 3.0, in no particular order:

Configuration

In RPC::ExtDirect 1.x and 2.x, the preferred way to change certain parts of the module behavior was to use package global variables. One example was $RPC::ExtDirect::DEBUG variable that turned on global debugging; there were several other variables as well.

All these are now deprecated and strongly discouraged from being used. RPC::ExtDirect::Config module is now used to hold configuration options, both global and local.

To turn on global debugging, use the following approach:

    RPC::ExtDirect->get_api->config->debug(1);

In case you only need to turn on detailed exceptions but not the actual debugging mode, use verbose_exceptions Config option instead:

    RPC::ExtDirect->get_api->config->verbose_exceptions(1);

For every deprecated package global variable that has a non-default value, a warning will be issued. There is no way to turn these off; change your code not to use package globals instead.

New Serializer

In 3.0, the old "RPC::ExtDirect::Serialize" and "RPC::ExtDirect::Deserialize" classes have been deprecated in favor of the new "RPC::ExtDirect::Serializer" that is intended to be used in an instance based fashion instead of the old class based way.

Both modules are still provided, with their respective class methods changed to stubs that will provide backwards compatibility. A warning will be issued if these methods are called.

This change may cause possible issues if you have relied on specific exception output in your unit tests.

API tree handling

In 1.x and 2.x, the Ext.Direct API tree was held in disjointed hash variables in RPC::ExtDirect module. In 3.0, the API is held in an instance of RPC::ExtDirect::API; it is now possible to initialize the API from a hashref instead of "ExtDirect" attributes, and have more than one API tree per application server.

This change should not affect your code directly, unless you were doing something funky with RPC::ExtDirect internals.

Actions, Methods, and Hooks are now objects

Besides the API tree itself, the handling of Actions, Methods, and Hooks also changed in 3.0. Instead of hash entries they are now objects, with behavior fully overridable in subclasses. A new Config option now exists for each of these, to supply your class name instead of the default RPC::ExtDirect::API::Action, RPC::ExtDirect::API::Method, and RPC::ExtDirect::API::Hook, respectively.

Conditional API generation

In 1.x and 2.x, there was no way to affect Ext.Direct API generation; it was always created from the defined set of Actions and Methods. In 3.0, the API JavaScript chunk is generated by walking the API tree and asking every Method to return their declaration.

This happens in "get_api_definition" in RPC::ExtDirect::API::Method method, which also receives an environment object when called. It is also possible to exclude any particular Method from being declared in the API by returning "undef", which makes per-user personalized API declarations possible.

Action naming

Before Ext JS 4.2.1, it was not possible to declare nested Ext.Direct Action names. This construct would not work properly:

    package Foo::Bar;
    use RPC::ExtDirect Action => 'Foo.Bar';
    
    sub baz : ExtDirect(0) {}

Rather, the method stub on the client side would have to be called in an ugly fashion:

    window['Foo.Bar'].baz()

This issue has been addressed in Ext JS 4.2.1 and later versions, and support for this feature has now been added to RPC::ExtDirect. You can set api_full_action_names global Config option to make Action names default to full package name instead of the old behavior.

Note that Sencha Touch 2.x does not support this feature, as well as Ext JS versions before 4.2.1. This is the reason why Action name generation defaults to using only the last portion of the namespace, as it was in RPC::ExtDirect since 1.x.

Method code invocation

Before 3.0, the actual Method code invocation happened in a private method of a "RPC::ExtDirect::Request" object, making any changes to Method behavior to be very hard to implement. This has been changed to a more open way of doing things; "run" in RPC::ExtDirect::API::Method is calling the code and can be easily overridden in a subclass to add application specific checks or enhancements.

Besides changing the place where the Method code is called, the way it is called was also changed to be more compatible with class inheritance.

Method argument preparation

Another change has been made to the way Method arguments are processed; the methods that are doing this for ordered, named, and formHandler arguments are public and overridable now.

Another addition is the new lazy parameter check feature for named Methods; it allows passing all arguments to a Method instead of only declared ones.

See "prepare_method_arguments" in RPC::ExtDirect::API::Method for more information.

Hook definition

Starting with 3.0, it is now possible to define a Hook with a 'Package::sub' string instead of a coderef. This makes lazy hook code binding possible.

See "new" in RPC::ExtDirect::API::Hook for more detail.

Hook invocation signature

A hook subroutine used to receive several parameters that described the Method that was about to be invoked, as well as the other Hooks involved for the Method. These disjointed parameters are now deprecated, and the corresponding RPC::ExtDirect::API::Method and RPC::ExtDirect::API::Hook objects are passed instead, which makes it easier to get the information.

The old parameters are still passed to Hook subroutines, but users are advised to change their code to take advantage of the new approach. See "CALLING CONVENTION" in RPC::ExtDirect::API::Hook for more detail.

Environment objects optional for Methods

When Environment objects were introduced in RPC::ExtDirect 2.0, the default behavior was to pass them to both Methods and Hooks. This has caused problems with Moose generated accessors exposed through RPC::ExtDirect; a getter would expect exactly 0 arguments and freak out on receiving an env object. Besides that, passing env objects to every Method has proved to be less useful than thought initially.

Starting with 3.0, a Method will receive an env object only when requested with env_arg option.

Event constructor signature

RPC::ExtDirect::Event used to accept arguments only by position; this has been changed to accepting both ordered and named arguments for the sake of easier integration with Moose and other environments with established calling conventions.

See "new" in RPC::ExtDirect::Event for more detail.