=pod

=head1 NAME

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

=head1 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:

=head2 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 C<$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.
L<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
L<verbose_exceptions|RPC::ExtDirect::Config/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.

=head2 New Serializer

In 3.0, the old C<RPC::ExtDirect::Serialize> and
C<RPC::ExtDirect::Deserialize> classes have been deprecated in favor
of the new C<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.

=head2 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 L<RPC::ExtDirect::API>; it is now possible to
initialize the API from a hashref instead of C<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.

=head2 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 L<RPC::ExtDirect::API::Action>, L<RPC::ExtDirect::API::Method>,
and L<RPC::ExtDirect::API::Hook>, respectively.

=head2 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 L<RPC::ExtDirect::API::Method/get_api_definition> method,
which also receives an L<environment object|RPC::ExtDirect/"ENVIRONMENT OBJECTS">
when called. It is also possible to exclude any particular Method from
being declared in the API by returning C<undef>, which makes per-user
personalized API declarations possible.

=head2 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 L<api_full_action_names|RPC::ExtDirect::Config/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.

=head2 Method code invocation

Before 3.0, the actual Method code invocation happened in a private
method of a C<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; L<RPC::ExtDirect::API::Method/run>
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.

=head2 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
L<lazy parameter check|RPC::ExtDirect::API/"Lazy parameter checking">
feature for named Methods; it allows passing all arguments to a
Method instead of only declared ones.

See L<RPC::ExtDirect::API::Method/prepare_method_arguments> for
more information.

=head2 Hook definition

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

See L<RPC::ExtDirect::API::Hook/new> for more detail.

=head2 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 L<RPC::ExtDirect::API::Method> and
L<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 L<RPC::ExtDirect::API::Hook/"CALLING CONVENTION"> for more detail.

=head2 Environment objects optional for Methods

When L<Environment objects|RPC::ExtDirect/"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 L<env_arg|RPC::ExtDirect::API::Method/env_arg> option.

=head2 Event constructor signature

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

See L<RPC::ExtDirect::Event/new> for more detail.

=cut
