eBay::Exception(3)

eBay::Exception
Ebay exception handling framework.

DESCRIPTION
This module provides a framework to users of the eBay::API packages to throw, catch and handle severe runtime exceptions gracefully.

The eBay::API exceptions inherit the functionality of CPAN modules Exceptions::Class and Error, including such informational fields as message, error, time, package, etc. See

  http://search.cpan.org/~drolsky/Exception-Class-1.23/lib/Exception/Class.pm

for a description of Exceptions::Class details.

As an end user you have the option of enabling exception handling or not. To enable exceptions you must include eBay::Exception and then enable exceptions by calling the Exception class method ebay::Exception::enableExceptions();

Exceptions include the following:

•   eBay::Exception Base class for all API exceptions.

•   eBay::API::XmlParseException Exceptions encountered while parsing XML content. This class has an additional informational field: schema.

•   eBay::API::UsageException Exceptions with using subroutines, including the wrong number of parameters, the wrong types of parameters, or inconsistent values in parameters. This exception has an additional informational field: argnumber.

Not all eBay applications errors may be reported as exceptions. You should always check the individual call responses for other application level error information such as failure to list an item for a user because that user does not have enough feedback to list an item of that type.

SYNOPSIS
  use eBay::API::XML::Session;
  use eBay::Exception qw(:try);

  # Uncomment this line to enable the catch block below
  # eBay::Exception::enableExceptions();

  try {
    # Example of bad argument to Session constructor
    my $apisession = eBay::API::XML::Session->new('yo');
  } catch Error with {
    my $error = shift;
    print $error->{argnumber};  # specific to usage errors
    print $error->{package};    # package where error trapped
    print $error->{trace};      # stack trace
    print $error;               # exception type
    print "\n\nCATCHING THE EXCEPTON!\n";
  } finally {
    #optional cleanup code;
    print "\nIN FINALLY BLOCK.\n";
  };  # Don't forget the semicolon, this is not a block, but a statement!

EXTENDING EXCEPTION HANDLING
It is simple to extend the framework to use it in your own application code. You can define exception classes that inherit from any pre-existing Extension::Class and then use and throw these classes in your own application code. If you extend from an eBay exception class, then any exceptions you throw will also be logged to the eBay logging facility if you throw the exception with the instance method ebay_throw(). Whether the exception will actually be thrown, of course, depends on whether you have enabled exceptions. If you just throw() the exception, it will always be thrown, and there will be no message to the eBay API logging.

Example:

  package myException;

  use eBay::Exception;

  use base qw(eBay::Exception);

  sub foo {
    print "I AM IN FOO.\n";
  }

  1;

  package main;

  use eBay::Exception qw(:try);
  # Comment out following to disable the catch block
  eBay::Exception::enableExceptions();

  try {
    myNewThrow();
  } catch Error with {
    print "CATCHING myNewThrow().\n";
    my $error = shift;
    if ($error->isa('myException') ) {
      print "myException ERROR: " . $error->error . "\n";
      $error->foo();
    }
  } finally {
    #optional cleanup code;
    print "I AM CLEANING UP.\n";
  };

  sub myNewThrow {
    # log and (maybe) actually throw
    myException->ebay_throw( error => "This is a foo error." );
    # or just throw and always throw regardless
    # myException->throw( error => "This is a foo error." );
  }

  1;

  enableExceptions()
When called tells the exception framework to throw exceptions. This has the effect of activating any exception handling logic in catch portion of a try/catch statement.

  disableExceptions()
This reverses the effect of calling enableExceptions(). The default for the exception handling framework is for it to be disabled.

  ebay_throw()
Extract information from the exception being thrown, including a stack trace, and log this information with the API logging framework. If exceptions are enabled, then call Exception::Class::throw() to throw the exception. This will cause the exception handling logic in the catch portion of the try/catch statement to execute.