Net::Appliance::Session::APIv2(3pm)			User Contributed Perl Documentation		       Net::Appliance::Session::APIv2(3pm)

NAME

       Net::Appliance::Session::APIv2 - Back-compatibility with API version 2

VERSION

       version 3.121640

INTRODUCTION

       Version 3 of Net::Appliance::Session is a complete rewrite of the previous version and so all client code will need updating. This is not
       ideal, but is important for the module to survive, and have some much-requested features implemented.

       You can choose either to keep things just as they are on your system, with version 2 API client code and version 2 of the library. Or you
       can modify your code to be compatible with version 3 and install that newer version (recommended). Finally there is the option to have
       version 3 installed but use a simple compatibility layer to interface from version 2 client code.

APIv2 Back-Compat Module
       If you have installed version 3 of the library but don't wish to update client code, this APIv2 Back-Compat Module might be sufficient for
       your application to keep working. In your code, wherever you have "use Net::Appliance::Session", replace it with:

	use Net::Appliance::Session::APIv2;

       The effect is that a wrapper is placed around the version 3 API such that your version 2 client code should continue to work. Be aware that
       the author is not planning to add any features to this compatibility layer, and in fact some features are missing (those which cannot be
       mapped into the new API). The list of missing features is:

       o   Custom phrasebooks cannot be loaded (i.e. the "Source" param to "new()" doesn't work)

       o   The "error()" method is not implemented

       o   Error strings in output from the device are not acted upon

       o   All exceptions are of class "Net::Appliance::Session::Exception"

       o   Exceptions probably don't contain the same amount of useful information

   A note on error handling
       A large part of the philosophy of earlier versions was that the module could identify certain error conditions at the CLI by the syntax
       used in output messages, and act accordingly. Together with that, client code was encouraged to capture exceptions and check for various
       conditions, exception types, and messages.

       When automating a CLI, this doesn't really make much sense. If a human makes a mistake, the CLI shows an error. A computer-driven script
       should never make a mistake - it will have been tested and developed. It's unnecessary overhead to check for errors all the time and
       attempt to recover. Of course, the remote device might still have a problem and report it, or die, but in that case version 3 of the module
       will still itself "die" with an error message.

       So any version 2 code you have which handles exceptions by class, and checks for Net::Appliance::Session::Exception will be okay, but other
       classes used in earlier versions are not supported in the compatibility layer.

Porting to API Version 3
       The changes are not too severe - you should recognise all the method calls.  Some features have been removed, and you will need to rewrite
       any custom phrasebooks. You should go through each of the following sections and make changes as required.

   Method Parameter Passing
       You must provide parameters to the "new", "connect", and "begin_privileged" methods as a hash reference with named parameters. There is no
       longer the option to have unnamed parameters as a bare list. Here is an example of how things must be, for each of these methods:

	my $s = Net::Appliance::Session->new({
	    personality => 'ios',
	    transport => 'SSH',
	    host => 'hostname.example',
	});

	eval {
	    $s->connect({ name => 'username', password => 'loginpass' });

	    $s->begin_privileged({ password => 'privilegedpass' });

	    # etc.....

   Parameters to "new"
       As shown above, you can no longer provide a bare device host name, and nothing else, to "new". You must provide the "hostname", "transport"
       and "personality".

       The "personality" parameter is the direct equivalent of "Platform" in the previous version 2 API. The Transports on offer are the same
       (except they now work on Windows natively - no cygwin required).

   Parameters to "cmd"
       As before, you can pass in a single string statement which will be issued to the connected CLI, followed by a carriage return. The method
       returns the complete response either in one Perl Scalar or an Array, depending on what you assign the result of the method call to:

	my $config     = $s->cmd('show running-config');
	my @interfaces = $s->cmd('show interfaces brief');

       In addition, you can pass a Hash Reference as the second parameter, with some additional options. This includes a custom timeout for the
       command, custom Regular Expressions to match the completed response, and the option to suppress addition of a carriage return. See the
       Net::CLI::Interact::Role::Engine manual page for further details.

   Custom Phrasebooks
       Sadly it has not been possible to automatically import existing version 2 custom phrasebooks into the version 3 module. The built-in
       phrasebook is however still included, just as before.

       Please see the comprehensive documentation for Net::CLI::Interact::Phrasebook and the "add_library" method of this module, to see how to
       construct and install your custom phrasebook. There's also the Cookbook which gives examples of the new language.

   Error and Exception Handling
       As explained above, there are no longer any fancy exception objects, and instead just simple Perl "die" calls when things go wrong.
       Typically this will be a timeout in communications at the connected CLI, or a bug in the module code. Check out the example script included
       with this distribution for a demonstration of handling these errors.

   Troubleshooting
       Whereas before you used the "input_log" method, please use the "set_global_log_at" method instead, for similar dumping of communications
       (and more). There's actually much more powerful logging, if you check out the main Net::Appliance::Session manual pages.

	$s->set_global_log_at('debug');

   Useful New Features
       See the extensive documentation of Net::Appliance::Session or the underlying Net::CLI::Interact module for details. You have a lot more on
       offer with the version 3 API.

AUTHOR

       Oliver Gorwits <oliver@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by Oliver Gorwits.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

perl v5.14.2							    2012-06-12				       Net::Appliance::Session::APIv2(3pm)