File Coverage

blib/lib/eBay/API/BaseApi.pm

Criterion	Covered	Total	%
statement	16	18	88.8
branch			n/a
condition			n/a
subroutine	6	6	100.0
pod			n/a
total	22	24	91.6

#!/usr/bin/perl

#########################################################################
#
# Module: ............... /eBay/API
# File: ................. BaseApi.pm
# Original Authors: ..... Jeff Nokes / Bob Bradley
# Last Modified By: ..... Jeff Nokes
# Last Modified: ........ 03/15/2007 @ 14:46
#
#########################################################################


=pod

=head1 NAME

eBay::API::BaseApi - Logging, exception handling and authentication frameworks
for eBay::API objects.

=head1 INHERITANCE

This is the base class

=head1 DESCRIPTION

This top-level module encapsulates all the functionality for the eBay
API.  This library is really a parent class wrapper to the sub-classes of
eBay::API--mainly sessions and api call objects.

The main purpose of this framework is to provide event logging,
exception handling, and management eBay API certification information.

Users of eBay::API can use this facility to debug requests to the eBay
API and responses from the eBay API. Unless the user overrides the
default behavior, all logging will go to stderr.

=cut



# Package Declaration
# ---------------------------------------------------------------------------
package eBay::API::BaseApi;


# Required Includes
# ---------------------------------------------------------------------------
use strict;                     # Used to control variable hell.
use Exporter;                   # For Perl symbol export functionality.
use Data::Dumper;               # Used for logging support.
use eBay::Exception qw(:try);   # eBay Exceptions framework
use Params::Validate qw(:all);  # CPAN validate subroutine parameters
use XML::Tidy;                  # CPAN module to format XML

use eBay::API::XML::Release;    # Defines API release attributes
                                #  Api release number
                                #  Api release type

# Variable Declarations
# ---------------------------------------------------------------------------
# Constants
use constant TRUE    => scalar 1;
use constant FALSE   => scalar 0;

use constant LOG_DEBUG => scalar 1;             # Pre-defined log levels
use constant LOG_INFO => scalar 2;
use constant LOG_WARN => scalar 3;
use constant LOG_ERROR => scalar 4;
use constant LOG_FATAL => scalar 5;

use constant DEFAULT_API_COMPATIBILITY_LEVEL =>
                                    eBay::API::XML::Release::RELEASE_NUMBER;
use constant DEFAULT_EBAY_API_VERSION =>
                                    eBay::API::XML::Release::RELEASE_NUMBER;
use constant DEFAULT_EBAY_SITE_ID => '0';
use constant DEFAULT_EBAY_URI => 'urn:ebay:apis:eBLBaseComponents';
use constant DEFAULT_EBAY_ERROR_LANGUAGE => 'en_US';
use constant DEFAULT_LOG_LEVEL => LOG_ERROR;
use constant DEFAULT_EBAY_API_TIMEOUT => 20;



# Global Variables
our $VERSION = $API::VERSION;    # The version of this class/module, as well as the entire pkg.
our $ERROR;                      # Most recent errors.

our @ISA = ("Exporter");   # Need to sub the Exporter class, to use the EXPORT* arrays below.

# :DEFAULT exported symbols
our @EXPORT = qw(
                   $VERSION
                   $ERROR
                );

# Script Lexical Variables
my $this_mod = 'eBay::API::BaseApi';    # Used for logging only.

my $LOG_SUB_HANDLE = undef;        # User-provided subroutine to use as a logging handler.
my $LOG_FILE_HANDLE = *STDERR;     # File handle for writing log info.
my $LOG_LEVEL = DEFAULT_LOG_LEVEL; # Current logging level for the package
my $LOG_HEADER = 0;                # Display context along with log message

my $CHECK_PARAMETERS = 1;

=head1 Subroutines

Below is a list of public methods accessed through child classes.

=cut

# Subroutine Prototypes
# -------------------------------------------------------------------------------
# Method Name                              Accessor Priviledges      Method Type
sub new($;$);                         #         Public                Class
sub _log_it(;$$);                     #         Private               Local
sub _logThis($;$$);                   #         Protected             Instance
sub logMessage($$$;);                 #         Protected             Instance
sub logXml($$$;);                     #         Protected             Instance
sub logDebug($$;);                    #         Protected             Instance
sub logInfo($$;);                     #         Protected             Instance
sub logError($$;);                    #         Protected             Instance
sub setLogHeader($$;);                #         Public                Instance
sub setLogSubHandle($$;);             #         Public                Instance
sub getLogSubHandle($;);              #         Public                Instance
sub setLogFileHandle($$;);            #         Public                Instance
sub getLogFileHandle($;);             #         Public                Instance
sub testLogEntry(;$);                 #         Public                Local
sub dumpObject($;$);                  #         Public                Instance
sub setLogLevel($$;);                 #         Public                Instance
sub getLogLevel($;);                  #         Public                Instance
sub _setError($$;);                   #         Private               Instance
sub setDevID($$;);                    #         Public                Instance
sub getDevID($;);                     #         Public                Instance
sub setAppID($$;);                    #         Public                Instance
sub getAppID($;);                     #         Public                Instance
sub setCertID($$;);                   #         Public                Instance
sub getCertID($;);                    #         Public                Instance
sub setSiteID($$;);                   #         Public                Instance
sub getSiteID($;);                    #         Public                Instance
sub setUserName($$;);                 #         Public                Instance
sub getUserName($;);                  #         Public                Instance
sub setUserPassword($$;);             #         Public                Instance
sub getUserPassword($;);              #         Public                Instance
sub setAuthToken($$;);                #         Public                Instance
sub getAuthToken($;);                 #         Public                Instance
sub setErrLang($$;);                  #         Public                Local
sub getErrLang($;);                   #         Public                Local
sub isSuccess($;);                    #         Public                Instance
sub getError($;);                     #         Public                Instance
sub setCompatibilityLevel($$;);       #         Public                Instance
sub getCompatibilityLevel($;);        #         Public                Instance
sub setVersion($$;);                  #         Public                Local
sub getVersion($;);                   #         Public                Local
sub setCompression($$;);              #         Public                Instance
sub isCompression($;);                #         Public                Instance
sub _check_arg($$;);                  #         Public                Package
sub enableParameterChecks(;$);        #         Public                Package
sub getApiReleaseNumber();            #         Public                Package
sub getApiReleaseType();              #         Public                Package
sub setCallRetry($$;);                #         Public                Instance
sub getCallRetry($;);                 #         Public                Instance
sub setTimeout($$;);                  #         Public                Instance
sub getTimeout($;);                   #         Public                Instance

# Main Script
# ---------------------------------------------------------------------------


# Subroutine Definitions
# ---------------------------------------------------------------------------

=head2 new()

Object constructor for the eBay::API::XML::Session class.  This is
basically a wrapper around the CPAN LWP::Paralle module.

  my $call = eBay::API::XML::Session->new(
      site_id => 0,
      proxy   => 'https://api.ebay.com/ws/api.dll',
      dev_id  => __DEVELOPER_ID__,
      app_id  => __APPLICATION_ID__,
      cert_id => __CERT_ID__,
      user_auth_token => __AUTH_TOKEN__,
  );

  or

  my $call = eBay::API::XML::Call::GeteBayOfficialTime->new(
      site_id => 0,
      proxy   => 'https://api.ebay.com/ws/api.dll',
      dev_id  => __DEVELOPER_ID__,
      app_id  => __APPLICATION_ID__,
      cert_id => __CERT_ID__,
      user_auth_token => __AUTH_TOKEN__,
  );

  $call->execute();
  print $call->getEBayOfficialTime();

Usage:

=over 4

=item *

eBay::API::XML::Session->new({args})

=item *

eBay::API::XML::Session::new("eBay::API::XML::Request", {args} )

=back

Arguments:

=over 4

=item *

The name  of this class/package.

=item *

A hash reference containing the following possible arguments:

=over 8

=item *

B => Scalar representing the eBay site id of the XML API
calls.  Setting the site id at the session level will provide a
default site id for all API calls bundled into a session.  The site id
for individual calls may still be overridden when the respective
request objects are instantiated.

If this value is not provided, it will attempt to use
the value in the environment variable $EBAY_API_SITE_ID;

=item *

B => Scalar representing the Developer ID provided to the user
by eBay.  The developer ID is unique to each licensed developer (or
company). By default this will be taken from the environment variable
$EBAY_API_DEV_ID, but it can be overridden here or via the setDevID()
class method.

=item *

B => Scalar representing the Application ID provided to the
user by eBay.  The application ID is unique to each application
created by the developer. By default this will be taken from the
environment variable $EBAY_API_APP_ID, but it can be overridden here
or via the setAppID() class method.

=item *

B => Scalar representing the Certification ID provided to the
user by eBay.  The certificate ID is unique to each application
created by the developer. By default this will be taken from the
environment variable $EBAY_API_CERT_ID, but it can be overridden here
or via the setCertID() class method.

=item *

B => Scalar representing the application level user name
for this session.  This may be overriden for each bundled call in the
session.

=item *

B => Scalar reprsenting the application level user
password for this session.  This may be overriden for each bundled
call in the session.

=item *

B => Scalar representing the auth token for the
application level user.

=item *

B => Scalar representing the eBay webservices API version the
user wishes to utilize.  If this is not set here, it is taken from the
environment variable $EBAY_API_VERSION, which can be overridden via
the class method setVersion().

=item *

B => Scalar representing the eBay transport URL needed to send
the request to.  If this is not set here, it must be set via the
setProxy() class method, prior to object instantiation.

# Deprecated
#=item *
#
#B => Boolean.  TRUE means we'll want debugging for the
#request/response.  FALSE means no debugging.

# Deprecated
#=item *
#
#B => Value for the error language you would like returned to
#you for any XML/webservice errors encountered.  By design, if this
#value is not provided, eBay will return en-US as the default error
#language value.  This can be set at the class level via the
#setErrLang() method, and retrieved from the getErrLang() method.  It
#can also be set for a particular instance with the instance
#getter/setter method errLang().

=item *

B => This value is defined as a default in each
release of the api.  But if you need to override the default value,
you can do this either when you instatiate your session object, or by
using the setter method setCompatibilityLevel().

=item *

B => Boolean value to indicate if the requests should be
issued sequentially if true, and in parallel if false (default).  This
may also be set with the setter method setExecutionSequential().

=item *

B => Scalar numerical value indicating the number of seconds to
wait on an http request before timing out.  Setting this to 0 will cause
the requests to block.  Otherwise the default is that of LWP::UserAgent.
This may also be set with the instance setter method setTimeout();

=back

=back

Returns:

=over 4

=item *

B  Object reference to the eBay::API::XML::Session class.

=item *

B  undefined

=back

=cut

sub new($;$) {

  # Get all arguments passed in.
  my($class, $arg_hash) = @_;

  # Validation
  eBay::API::BaseApi::_check_arg($class, Params::Validate::SCALAR);


  # Local Variables
  my $self = {};          # This object to be blessed.

  # We want to immediately bless ourselves into this __PACKAGE__ so we
  # can start setting object attributes right away, and use any
  # available instance methods.
  bless($self, $class);


  if (defined $ENV{EBAY_LOG_LEVEL} && $ENV{EBAY_LOG_LEVEL} && $ENV{EBAY_LOG_LEVEL} > 0 ) {
    $LOG_LEVEL = $ENV{EBAY_LOG_LEVEL};
  }# end if

  if (defined $::RALF and $::RALF) {
    $LOG_FILE_HANDLE = $::RALF;
  }# end if

  if ( $ENV{EBAY_API_COMPATIBILITY_LEVEL} ) {
    $self->{compatibility_level} = $ENV{EBAY_API_COMPATIBILITY_LEVEL};
  } else {
    $self->{compatibility_level} = DEFAULT_API_COMPATIBILITY_LEVEL;
  }

  if ( $ENV{EBAY_API_SITE_ID}) {
    $self->{site_id} = $ENV{EBAY_API_SITE_ID};
  } else {
    $self->{site_id} = DEFAULT_EBAY_SITE_ID;
  }

  $self->{dev_id} = $ENV{EBAY_API_DEV_ID};
  $self->{app_id} = $ENV{EBAY_API_APP_ID};
  $self->{cert_id} = $ENV{EBAY_API_CERT_ID};
  $self->{user_name} = $ENV{EBAY_API_USER_NAME};
  $self->{user_password} = $ENV{EBAY_API_USER_PASSWORD};
  $self->{user_auth_token} = $ENV{EBAY_API_USER_AUTH_TOKEN};
  $self->{proxy} = $ENV{EBAY_API_XML_TRANSPORT};

# Deprecated
#  if ($ENV{EBAY_API_XML_ERR_LANG}) {
#    $self->{err_lang} = $ENV{EBAY_API_XML_ERR_LANG};
#  } else  {
#    $self->{err_lang} = DEFAULT_EBAY_ERROR_LANGUAGE;
#  }

# Deprecated
#  if ($ENV{EBAY_API_URI} ) {
#    $self->{xml_uri} = $ENV{EBAY_API_URI};
#  } else {
#    $self->{xml_uri} = DEFAULT_EBAY_URI;
#  }

  if ($ENV{EBAY_API_VERSION} ) {
    $self->{api_ver} = $ENV{EBAY_API_VERSION};
  } else {
    $self->{api_ver} = DEFAULT_EBAY_API_VERSION;
  }

  if ($ENV{EBAY_API_TIMEOUT} ) {
    $self->{timeout} = $ENV{EBAY_API_TIMEOUT};
  } else {
    $self->{timeout} = DEFAULT_EBAY_API_TIMEOUT;
  }

  # Before we start setting local variables assuming we have an
  # $arg_hash, validate that we actaully do have one.  If we have an
  # argument but it's not a hash reference, set/log $ERROR and return
  # failure to the caller.  If we have a valid hash reference argument,
  # attempt to set the appropriate object attributes.
  if (defined($arg_hash) ) {
    eBay::API::BaseApi::_check_arg($arg_hash, Params::Validate::HASHREF);
  }# end if

  if    (defined($arg_hash)  &&  (ref($arg_hash) =~ /HASH/o))
    {
      if ($arg_hash->{site_id})         {$self->{site_id}     = $arg_hash->{site_id};}
      if ($arg_hash->{dev_id})          {$self->{dev_id}      = $arg_hash->{dev_id};}
      if ($arg_hash->{app_id})          {$self->{app_id}      = $arg_hash->{app_id};}
      if ($arg_hash->{cert_id})         {$self->{cert_id}     = $arg_hash->{cert_id};}
      #if ($arg_hash->{xml_uri})         {$self->{xml_url}     = $arg_hash->{xml_uri};}               # Deprecated
      if ($arg_hash->{user_name})       {$self->{user_name}   = $arg_hash->{user_name};}
      if ($arg_hash->{user_password})   {$self->{user_password} = $arg_hash->{user_password};}
      if ($arg_hash->{user_auth_token}) {$self->{user_auth_token} = $arg_hash->{user_auth_token};}
      if ($arg_hash->{api_ver})         {$self->{api_ver}     = $arg_hash->{api_ver};}
      #if ($arg_hash->{err_lang})        {$self->{err_lang}    = $arg_hash->{err_lang};}              # Deprecated
      if ($arg_hash->{proxy})           {$self->{proxy}       = $arg_hash->{proxy};}
      if ($arg_hash->{debug})           {$self->{debug}       = $arg_hash->{debug};}
      if ($arg_hash->{timeout})         {$self->{timeout}     = $arg_hash->{timeout};}
      if ($arg_hash->{compatibility_level}) {
         $self->{compatibility_level}  = $arg_hash->{compatibility_level};
      }# end if

    }# end if


  # Else-if we have an $arg_hash but it isn't a hash reference,
  # set/log $ERROR and return failure to the caller.
  elsif (defined($arg_hash)  &&  (ref($arg_hash) !~ /HASH/o)) {
    return(undef());
  }# end elsif

  # Else, assume the caller doesn't want to set any object attributes.
  else  {}  # end else

  # Add an error attribute to always contain the most recent error data in scalar form.
  $API::ERROR = $self->{error} = '';


  # If we've gotten this far, we have a class (we hope), return success to the caller.
  return($self);

}# end sub new()

=head2 setLogHeader()

Instance method to enable or disable additional context information
to display with log messages.  This information includes date, time,
and logging level.

Arguments:

=over 4

=item *

A reference to object of type eBay::API.

=item *

Boolean value (0 = false; non-zero = true);

=back

Returns:

=over 4

=item *

The boolean value to be set for this attribute.

=back

=cut



sub setLogHeader($$;) {
  my $self = shift;
  my $bool = shift;
  # Validation
  eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
  eBay::API::BaseApi::_check_arg($bool, Params::Validate::BOOLEAN);
  $LOG_HEADER = $bool;
  return $bool;
}


# _log_it()
#
# Description:  Local method used to support logging functionality.  This sub will allow
#               for itself to be a wrapper for another sub handle if $LOG_SUB_HANDLE is
#               set.  Otherwise, it will default to printing to $LOG_FILE_HANDLE.
#
# Access:       Private
#
# Note:         If using the $LOG_SUB_HANDLE, make sure your user sub accepts an
#               argument of type scalar!
#
# Optional arguments:
#
#     A scalar or scalar reference containing the data you want to be logged.
#     A scalar containing the level at which to log.
#
# Returns:      upon success:  TRUE
#               upon failure:  undefined


  sub _log_it(;$$) {

    # Get all arguments passed in
      my($in_data, $log_level) = @_;

    # Local Variables
      my $out_data;   # Used to store the final stringified data to be logged.
      my $rv;         # Used to store a return value

    # First, determine if the $in_data provided is a scalar or a reference to a
    # scalar, and set $out_data to always be a scalar.
      if   (ref($in_data) =~ /SCALAR/og)
           {$out_data = $$in_data;    # Dereference the scalar reference, to get the raw scalar data
           }# end if
      else {$out_data = $in_data;
           }# end else

      my $current_time = time();       # Need this for the log message
      my $delim = '|';
      my $level = '';
      if (defined $log_level) {
	if ($log_level == LOG_DEBUG) {$level='DEBUG'};
	if ($log_level == LOG_INFO) {$level='INFO'};
	if ($log_level == LOG_WARN) {$level='WARNING'};
	if ($log_level == LOG_ERROR) {$level='ERROR'};
	if ($log_level == LOG_FATAL) {$level='CRITICAL'};
      }

      # Construct context for the log message
      my $header = scalar (localtime) . $delim . # Current system date in form of MM-DD-YYYY
               $level . ": ";                                             # Logging level (debug, info, error, etc.)
      if ($LOG_HEADER){
	$out_data = $header . $out_data;
      }

    # Now print the log data.  Either pass it to the handler provided in the lexical
    # var $LOG_SUB_HANDLE or print it to the $LOG_FILE_HANDLE.
      if   ($LOG_SUB_HANDLE)
           {&$LOG_SUB_HANDLE($out_data); # Peform logging with user supplied subroutine reference.
            $rv = 1;                     # Since we don't know anything about the user supplied handler,
                                         # we'll assume success.
           }# end if
      else {$rv = print $LOG_FILE_HANDLE ($out_data);
           }# end else

    # Return success or failure to the caller.
      if   ($rv)                # Success
           {return(TRUE);
           }# end if
      else {return(undef());    # Failure
           }# end else

  }# end sub _log_it()





# _logThis()
#
# Description:  Instance method used as a wrapper for the local subroutine _log_it().
#
# Access:       Private
#
# Arguments:    01 [R]  A refernce to an object of type eBay::API
#               02 [O]  A scalar or scalar reference containing the data you want to be logged.
#               02 [O]  A scalar containing the logging level
#
# Returns:      upon success:  same as _log_it()
#               upon failure:  same as _log_it()

  sub _logThis($;$$) {

    # Get all arguments passed in
      my($self, $in_data, $level) = @_;

    # Local Variables
      my $this_sub = '_logThis()';  # Used for logging
      my $rv;                       # Used to store a return value

    # Just call the local subroutine _log_it to perform the actual logging.
      $rv = _log_it($in_data, $level);

    # Return whaver return code came back from _log_it to the caller.
      return($rv);

  }# end sub _logThis()


=pod

=head2 logDebug()

Public convenience method to log debug messages.  This is the same as doing

  $rc = $api->logMessage(eBay::API::BaseApi::LOG_DEBUG, "This is debug message.\n");

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=item *

Scalar data to be logged.

=back

Returns:

=over 4

=item *

True if message was logged; otherwise undef.

=back

=cut


  sub  logDebug($$;)  {
    my ($self,  $msg) = @_;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($msg, Params::Validate::SCALAR);

    return $self->logMessage(LOG_DEBUG, $msg);
  }



=pod

=head2 logInfo()

Public convenience method to log info messages.  This is the same as doing

  $rc = $api->logMessage(eBay::API::BaseApi::LOG_INFO, "This is an info message.\n");

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=item *

Scalar data to be logged.

=back

Returns:

=over 4

=item *

True if message was logged; otherwise undef.

=back

=cut


  sub  logInfo($$;)  {
    my ($self,  $msg) = @_;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($msg, Params::Validate::SCALAR);

    return $self->logMessage(LOG_INFO, $msg);
  }



=pod

=head2 logError()

Public convenience method to log error messages.  This is the same as doing

  $rc = $api->logMessage(eBay::API::BaseApi::LOG_ERROR, "This is an error message.\n");

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=item *

Scalar data to be logged.

=back

Returns:

=over 4

=item *

True if message was logged; otherwise undef.

=back

=cut


  sub  logError($$;)  {
    my ($self,  $msg) = @_;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($msg, Params::Validate::SCALAR);

    return $self->logMessage(LOG_ERROR, $msg);
  }




=pod

=head2 logMessage()

Description: Instance method to log application events.  This is the
main entry point for logging messages that should be filtered
depending on the setting for the logging level.  If the logging level
of the message is lower than the current default logging level, the
message will NOT be logged.

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=item *

Scalar log level.

=item *

Scalar data to be logged.

=back

Returns:

=over 4

=item *

True if message was logged; otherwise undef.

=back

=cut




  sub logMessage($$$;) {

    my ($self, $loglevel, $msg) = @_;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($loglevel, Params::Validate::SCALAR);
    eBay::API::BaseApi::_check_arg($msg, Params::Validate::SCALAR);

    if ($loglevel >= $LOG_LEVEL) {
      return (_log_it($msg, $loglevel));
    }
    return (undef());
  }





=pod

=head2 logXml()

Description: Instance method to log application xml text.  This is
mainly a wrapper to logMessage() and takes the same arguments.  This
method assumes the message text is valid xml and will use XML::Tidy
to clean it up some before logging it.

If the xml cannot be parsed and cleaned up, it will just be logged 'as
is'.

Warning: XML::Tidy does not handle headers like



and will DELETE them from the message.

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=item *

Scalar log level.

=item *

Scalar data to be logged.

=back

Returns:

=over 4

=item *

True if message was logged; otherwise undef.

=back

=cut




  sub logXml($$$;) {

    my ($self, $loglevel, $msg) = @_;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($loglevel, Params::Validate::SCALAR);
    eBay::API::BaseApi::_check_arg($msg, Params::Validate::SCALAR);

    if ($loglevel >= $LOG_LEVEL) {
      my $t = new XML::Tidy($msg);
      # XML::Tidy trashes things like:  !!!
      # TODO: read up on Tidy some more and see if there is a switch to stop this
      my $tidytext;
      eval {
	$tidytext = $t->tidy()->toString();
      };
      # if tidy croaked just log the message
      if ($@) {
	return (_log_it($msg, $loglevel));
      } else {
	return (_log_it($tidytext . "\n", $loglevel));
      }
    }
    return (undef());
  }



=head2 setLogSubHandle()

Sets the class variable, $LOG_SUB_HANDLE, which allows users to
customize all of its logging features, and those of it's children.
The only required argument is a reference to a subroutine that should
be able to accept a single scalar argument.  By setting this, all
logging normally performed by this and child modules will be tasked to
the user provided handler.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=item *

Reference to a logging handler subroutine, provided by user

=back

Returns:

=over 4

=item *

B The value of $LOG_SUB_HANDLE after setting with user
provided sub reference (should be the same value that was provided by
the user)

=item *

B undefined

=back

=cut


  sub setLogSubHandle ($$;) {

    # Local Variables
    my $this_sub = 'setLogSubHandle';      # Used for logging

    # Get all values passed in
    my ($self, $subref) = @_;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    # Validate that we really have a subroutine reference.
    if (ref($subref) !~ /CODE/o) {
      $LOG_SUB_HANDLE = undef();
       return(undef());
     }# end if

    # If we got this far, must be a valid sub reference, set it.
    $LOG_SUB_HANDLE = $subref;

    # Return success to the caller.
      return($LOG_SUB_HANDLE);

  }# end sub setLogSubHandle()



=head2 getLogSubHandle()

Returns a reference to a subroutine handling logging messages if one
has been set by setLogSubHandle() previously.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=back

Returns:

=over 4

=item *

B  The current value of $LOG_SUB_HANDLE

=item *

B    undefined, not currently possible to get this

=back

=cut




 sub getLogSubHandle ($;) {

   my $self = shift;
    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    # Return success to the caller.
      return($LOG_SUB_HANDLE);

 }# end sub getLogSubHandle()



=head2 setLogFileHandle()

Sets a custom log file handle, which will allow users of this module
to customize all of its logging features, and those of it's children.
The log file handle argument is a typeglob (or reference to a
typeglob; e.g. \*STDOUT) of a file handle that the user wishes all
error/app logging be sent to, instead of the default STDERR.  By
setting this, all logging normally performed by this and child modules
will be sent to the user provided file handle.

Arguments:

=over 4

=item *

Reference to object of type eBay::API.

=item *

Typeglob (or reference to a typeglob) of a user specific file handle

=back

Returns:

=over 4

=item *

B The value of $LOG_FILE_HANDLE after setting with user
provided file handle.  (It should be the same value that was provided
by the user.)

=item *

B    undefined

=back

=cut


  sub setLogFileHandle ($$;) {

    # Local Variables
    my $this_sub = 'setLogFileHandle';      # Used for logging

    # Get all values passed in
    my ($self, $fh) = @_;

    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($fh, Params::Validate::GLOB | Params::Validate::GLOBREF);

    # If we got this far, must be a valid file handle, set it.
    $LOG_FILE_HANDLE = $fh;

    # Return success to the caller.
    return($LOG_FILE_HANDLE);

  }# end sub setLogFileHandle()



=head2 getLogFileHandle()

Returns the current log file handle.  If this had not been previously
set by the user of the module, it should return STDERR.

Arguments:    none

Returns:

=over 4

=item *

B  The current value of $LOG_FILE_HANDLE

=item *

B    undefined, not currently possible to get this

=back

=cut



  sub getLogFileHandle ($;) {

    my $self = shift;

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    # Return success to the caller.
    return($LOG_FILE_HANDLE);

  }# end sub getLogFileHandle()



=head2 testLogEntry()

Testing any user-specific overrides to default log output file or logging handler
subroutine.

Arguments:

=over 4

=item *

Reference to object of type eBay::API.

=item *

Scalar representing some test data to log.

=back

Returns:

=over 4

=item *

B  TRUE

=item *

B    undefined

=back

=cut



  sub testLogEntry (;$) {

    # Local Variables
      my $this_sub = 'testLogEntry';      # Used for logging
      my $rv;                             # Used for storing return codes

    # Get any values passed in.
      my($self, $test_data) = @_;

    # Attempt to print the test data using the internal class method _log_it().
      chomp($test_data);
      $rv = _log_it($this_mod . '::' .
		    $this_sub . ': Test Log Entry = ' . $test_data . "\n");

    # Return success/failure to the caller.
      if   ($rv)
           {return(TRUE);
           }# end if
      else {return(undef());
           }# end else

  }# end sub testLogEntry()



=head2 dumpObject()

Instance method use mostly for debugging.  It will dump the entire
structure of an object.  If an object is supplied as an argument,
that object will be dumped; otherwise the instance of the class
calling this method will be dumped in its entirety.

By design, the dump will use the protected logging method _logThis(),
so whatever settings the user has to override the default logging,
that where it will go, hopefully ...

You need to have log level DEBUG set for this to actually log
anything.

Arguments:

=over 4

=item *

Object reference of type eBay::API::* or lower.

=item *

Optional object or hash reference.

=back

Returns:

=over 4

=item *

B Whatever _logThis() returns. (Note: It will however dump
the entire structure of the object at this point in time.)

=item *

B    Whatever _logThis() returns.

=back

=cut



  sub dumpObject($;$) {

    # Get all values passed in.
      my($self, $object) = @_;

    # Local Variables
      my $this_sub = 'dumpObject()';    # Used for logging.
      my $rv;                           # Stores a return value.

#     Set the indentation for Data::Dumper.

#     Description taken from Data::Dumper:

#       Controls the style of indentation. It can be set to 0, 1, 2 or
#       3. Style 0 spews output without any newlines, indentation, or
#       spaces between list items. It is the most compact format
#       possible that can still be called valid perl. Style 1 outputs a
#       readable form with newlines but no fancy indentation (each
#       level in the structure is simply indented by a fixed amount of
#       whitespace).  Style 2 (the default) outputs a very readable
#       form which takes into account the length of hash keys (so the
#       hash value lines up). Style 3 is like style 2, but also
#       annotates the elements of arrays with their index (but the
#       comment is on its own line, so array output consumes twice the
#       number of lines). Style 2 is the default.


        $Data::Dumper::Indent = 1;

# Since 5.8.1 Dumper randomizes the order of hash keys for security
# reasons.  We don't want that if we need to diff output results from
# different versions of the software for unit test purposes.  So
# turn key sorting back on.

        $Data::Dumper::Sortkeys = 1;

    # Dump the entire object
      if (defined $object) {
	$rv = $self->_logThis($this_mod . '::' . $this_sub . "\n" .
			      'Dump of current object of type \'' . ref($object) . "'\n" .
			      "--------------------------------------------------------------------------------\n" .
			      Dumper($object) . "\n", eBay::API::BaseApi::LOG_DEBUG
			     );
      } else {
	$rv = $self->_logThis($this_mod . '::' . $this_sub . "\n" .
			      'Dump of current object of type \'' . ref($self) . "'\n" .
			      "--------------------------------------------------------------------------------\n" .
			      Dumper($self) . "\n",eBay::API::BaseApi::LOG_DEBUG
			     );
      }

    # Return success to the caller.
      return($rv);

  }# end sub dumpObject()






=head2 setLogLevel()

Setter method for setting the logging level of eBay::API and all child
classes.  Log levels may be set with any of the following constants.

=over 4

=item *

B Full debugging information is logged, along
with all log messages of higher levels.

=item *

B Informational and all higher logging level
messages are logged.

=item *

B Warnings and all higher logging level messages
are logged.

=item *

B Errors and all higher logging level messages
are logged.

=item *

B Only errors which causes immediate termination
of the current transaction are logged.

=back

Arguments:

=over 4

=item *

Reference to object of type eBay::API.

=item  *

Scalar constant logging level.

=back

Returns:

=over 4

=item  *

B:  The logging level requested.

=item  *

B: Undef if an invalid logging level is requested.  In this
case the logging level is left unchanged from the current logging
level.

=back

=cut



  sub setLogLevel($$;) {


    # Get all values passed in.
    my ($self, $level) = @_;

    # Validate the arguments.
    # Sub prototype deals with case of missing required argument

    # Validate the arguments
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($level, Params::Validate::SCALAR);

    $LOG_LEVEL = $level;

    # Return success to the caller
    return($LOG_LEVEL);

  }# end sub setLogLevel()



=head2 getLogLevel()

Get the current logging level.  See setLoglevel() for details on the
logging levels supported.

Arguments:    none

Returns:

=over 4

=item *

B:  The current logging level.

=item *

B:    undefined

=back

=cut



  sub getLogLevel($;) {

    # Local Variables
    #my $this_sub = 'getDebug';    # Used for logging

    my $self = shift;

    # validate that first argument is blessed object
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    # Return success to the caller
    return($LOG_LEVEL);

  }# end sub getLogLevel()

=head2 setDevID()

Sets the dev id for api certification. This variable is set to default
to the value of $ENV{EBAY_API_DEV_ID}. You can override this either
when constructing a session object or by using this method after
construction of the session.

Arguments:

=over 4

=item *

Reference to object of type eBay::API::XML::Session.

=item *

Scalar representing the eBay Developer ID of the eBay API request.

=back

Returns:

=over 4

=item *

B  The value of the dev id.

=item *

B    undefined

=back

=cut



  sub setDevID($$;) {

    # Local Variables
    #my $this_sub = 'setDevID';

    # Get all values passed in.
    my($self, $devid) = @_;

    # Some validation of the existence of the argument is done implicitly via the sub prototype.
    # validate the arguments for existence and data type
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($devid, Params::Validate::SCALAR);


    $self->{dev_id} = $devid;

    # Return success to the caller.
    return($devid);

  }# end sub setDevID()



=head2 getDevID()

Gets the current dev id setting.

Arguments:

=over 4

=item *

Reference to a session object.

=back

Returns:

=over 4

=item *

B  The value of the dev id.

=item *

B    undefined

=back

=cut



  sub getDevID($;) {

    # Local Variables
    #my $this_sub = 'getDevID';

    my $self = shift;

    # validate the arguments for existence and data type
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);


    # Return success to the caller.
    return($self->{dev_id});

  }# end sub getDevID()



=head2 setAppID()

Sets the app id for ebay certification.  This value defaults to
$ENV{EBAY_API_APP_ID}, and is overridden either by calling this method
or if it is specified when constructing a session object.

Arguments:

=over 4

=item *

Reference to a session object.

=item *

Scalar representing the eBay Application ID of the eBay API request.

=back

Returns:

=over 4

=item *

B  The value of new app id.

=item *

B    undefined

=back

=cut




  sub setAppID($$;) {

    # Local Variables
    #my $this_sub = 'setAppID';

    # Get all values passed in.
    my($self, $appid) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($appid, Params::Validate::SCALAR);

    # Set the proxy
    $self->{app_id} = $appid;

    # Return success to the caller.
    return($appid);

  }# end sub setAppID()



=head2 getAppID()

Get the current app id for the session.

Arguments:

=over 4

=item *

Reference to a session object.

=back

Returns:

=over 4

=item *

B  The value of the app id.

=item *

B    undefined

=back

=cut



  sub getAppID($;) {

    # Local Variables
    #my $this_sub = 'getAppID';

    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);


    # Return success to the caller.
    return($self->{app_id});

  }# end sub getAppID()



=head2 setCertID()

Sets the cert id for the session.  This overrides any default in
$ENV{EBAY_API_CERT_ID}, or any value specified when the session was
originally constructed.

Arguments:

=over 4

=item *

Reference to a session object.

=item *

Scalar representing the eBay Certification ID of the eBay API request.

=back

Returns:

=over 4

=item *

B The cert id just set.

=item *

B    undefined

=back

=cut




  sub setCertID($$;) {

    # Local Variables
    #my $this_sub = 'setCertID';

    # Get all values passed in.
    my($self, $certid) = @_;
    # Validation of the existence of the argument is done implicitly via the sub prototype.

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($certid, Params::Validate::SCALAR);


    # Set the proxy
    $self->{cert_id} = $certid;

    # Return success to the caller.
    return($certid);

  }# end sub setCertID()



=head2 getCertID()

Gets current cert id.

Arguments:

=over 4

=item *

Reference to session object.

=back

Returns:

=over 4

=item *

B  The value of the cert id.

=item *

B    undefined

=back

=cut



  sub getCertID($;) {

    # Local Variables
    #my $this_sub = 'getCertID';

    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);


    # Return success to the caller.
      return($self->{cert_id});

  }# end sub getCertID()




=head2 setSiteID()

Instance method to set the site id for the current session.  This will override
any global setting of the site id that was set at the package level by the
environment variable $ENV{EBAY_API_SITE_ID}, or when a Session object is
first constructed.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=item *

Scalar site id.

=back

Returns:

=over 4

=item *

B Site id given as argument.

=item *

B undefined

=back


=cut




  sub setSiteID ($$;) {
    my ($self, $site_id) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($site_id, Params::Validate::SCALAR);


    $self->{site_id} = $site_id;
    return $site_id;
  }




=head2 getSiteID()

Returns the current site id for the current session.  Note that this may
be different than the global site id for the package.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=back

Returns:

=over 4

=item *

B Site id given for the current session.

=item *

B undefined

=back


=cut



  sub getSiteID ($;) {
    my $self = shift;
    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    return $self->{site_id};
  }



=head2 setUserName()

Instance method to set the application user name for the current
session.  This will override any global setting of the user name that
was set at the package level by the environment variable
$ENV{EBAY_API_USER_NAME}, or when a Session object is first
constructed.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=item *

Scalar user name.

=back

Returns:

=over 4

=item *

B User name given as argument.

=item *

B undefined

=back


=cut




  sub setUserName ($$;) {
    my ($self, $user_name) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    $self->{user_name} = $user_name;
    return $user_name;
  }

=head2 getUserName()

Returns the current application user name for the current session.
Note that this may be different than the global user name for the
package.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=back

Returns:

=over 4

=item *

B User name given for the current session.

=item *

B undefined

=back


=cut



  sub getUserName ($;) {
    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    return $self->{user_name};
  }


#########



=head2 setUserPassword()

Instance method to set the application user password for the current
session.  This will override any global setting of the user password that
was set at the package level by the environment variable
$ENV{EBAY_API_USER_PASSWORD}, or when an API object is first
constructed.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=item *

Scalar user password.

=back

Returns:

=over 4

=item *

B User password given as argument.

=item *

B undefined

=back


=cut




  sub setUserPassword ($$;) {
    my ($self, $user_password) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($user_password, Params::Validate::SCALAR);

    $self->{user_password} = $user_password;
    return $user_password;
  }

=head2 getUserPassword()

Returns the current application user password for the current session.
Note that this may be different than the global user password for the
package.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=back

Returns:

=over 4

=item *

B User password given for the current session.

=item *

B undefined

=back


=cut



  sub getUserPassword ($;) {
    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    return $self->{user_password};
  }



# Deprecated
#=pod
#
#=head2 setErrLang()
#
#Local setter method for setting the class attribute $EBAY_ERR_LANG.
#This variable is set to default to the value of
#$ENV{EBAY_API_XML_ERR_LANG}.  If you want to override the value, make
#sure to use this method before object instantiation.
#
#Arguments:
#
#=over 4
#
#=item *
#
#Scalar representing the desired locale representation of the error
#language you would like to have returned to you from XML responses.
#
#=back
#
#Returns:
#
#=over 4
#
#=item *
#
#B The value of $EBAY_ERR_LANG (should be the same value that
#was provided by the user)
#
#=item *
#
#B    undefined
#
#=back
#
#=cut
#
#
#
#
#  sub setErrLang($$;) {
#
#    # Get all values passed in.
#    my($self, $errlang) = @_;
#
#    # Validation of the existence of the argument is done implicitly via the sub prototype.
#    # Validation
#    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
#    eBay::API::BaseApi::_check_arg($errlang, Params::Validate::SCALAR);
#
#    # Set the api error language
#    $self->{err_lang} = $errlang;
#
#    # Return success to the caller.
#      return($errlang);
#
#  }# end sub setErrLang()




# Deprecated
#=pod
#
#=head2 getErrLang()
#
#Local getter method for getting the current value of $EBAY_ERR_LANG.
#
#Arguments:    none
#
#Returns:
#
#=over 4
#
#=item *
#
#B  The value of $EBAY_ERR_LANG
#
#=item *
#
#B    undefined
#
#=back
#
#=cut
#
#
#
#  sub getErrLang($;) {
#
#    my $self = shift;
#
#    # Validation
#    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
#
#    # Return success to the caller.
#    return($self->{err_lang});
#
#  }# end sub getErrLang()









# _setError()
#
# Description:
#
# Private instance setter method for setting the latest
# error message encountered during an eBay API call.
#
# Access:  private
#
# Arguments:    Reference to an object of type eBay::API
#
# Returns:   Error message being set

  sub _setError($$;) {

    # Local Variables
    my $this_sub = '_setError';      # Used for logging

    # Get values passed in
    my($obj, $error) = @_;

    # Validate arguments
    # Argument existence enforced from sub prototype.

    # Validation
    eBay::API::BaseApi::_check_arg($obj, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($error, Params::Validate::SCALAR);

    # Set the error
    $ERROR = $obj->{error} = $error;

    # Return success to the caller.
    return($ERROR);

  }# end sub _setError()



=head2 getError()

Instance getter method for retrieving the generic error for currrent
state of the session.  Consult the other information such as the logs,
or the status of other api objects such as api call objects for more
detailed error information.  If all requests have completed
successfully, there will be no error information.  If any of the
requests have had an error, then there will some message to this
effect.

Arguments:

=over 4

=item  *

Reference to an object of type eBay::API.

=back

Returns:

=over 4

=item  *

B: Last error encountered during while executing an eBay::API
call.  undef if no errors were encountered.

Note: An empty error value can return this as well, which in this case
would be success.

=back

=cut

  sub getError($;) {

    # Get values passed in
    my($obj) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($obj, Params::Validate::OBJECT);

    # If we pass validation, return success to the caller.
    return( $obj->{error} || undef() );

  }# end sub getError()





=head2 isSuccess()

Indicates B status of the eBay::API object (usually a
session, or an API call itself).  Call this after execute() to see if
errors were encountered.

Arguments: none

Returns:

=over 4

=item *

B Boolean true if all reponses for the request(s) were returned
without problems by the eBay API.

=item *

B Boolean false if there was either a general problem with
getting response(s) back from the eBay API, or if there was a failure on
one or more of the bundled request.  Consult the error status of each
response for more information.

=back

=cut


  sub isSuccess($;) {
    my $obj = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($obj, Params::Validate::OBJECT);

    return (defined $obj->{error} && $obj->{error}) ? 1 : 0;
  }




=head2 setAuthToken()

Instance method to set the application user auth token for the current
session.  This will override any global setting of the user auth token that
was set at the package level by the environment variable
$ENV{EBAY_API_AUTH_TOKEN}, or when an API object is first
constructed.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=item *

Scalar user auth token.

=back

Returns:

=over 4

=item *

B User auth token given as argument.

=item *

B undefined

=back


=cut




  sub setAuthToken ($$;) {
    my ($self, $user_auth_token) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);


    $self->{user_auth_token} = $user_auth_token;
    return $user_auth_token;
  }



=head2 getAuthToken()

Returns the current application user auth token for the current session.
Note that this may be different than the global user auth token for the
package.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=back

Returns:

=over 4

=item *

B User auth token given for the current session.

=item *

B undefined

=back


=cut



  sub getAuthToken ($;) {
    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);


    return $self->{user_auth_token};
  }





=head2 setCompatibilityLevel()

Instance method to set the XML API compatibility level for the current
session.  This will override any global default setting at the package
level.

Note that the compatibility level is defaulted with each release of
the API.  However you can override that default with the environment
variable, $ENV{EBAY_API_COMPATIBILITY_LEVEL}, when you construct a
session object, or by using this setter method.


Arguments:

=over 4

=item *

Object reference of type eBay::API.

=item *

Scalar compatibility level.

=back

Returns:

=over 4

=item *

B Compatibility level given as argument.

=item *

B undefined

=back


=cut




  sub setCompatibilityLevel ($$;) {
    my ($self, $level) = @_;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($level, Params::Validate::SCALAR);

    $self->{compatibility_level} = $level;
    return $level;
  }

=head2 getCompatibilityLevel()

Returns the XML API compatibility level for the current session.  Note that this may
be different than the global default for the package.

Arguments:

=over 4

=item *

Object reference of type eBay::API.

=back

Returns:

=over 4

=item *

B Compatibility level for the current session.

=item *

B undefined

=back


=cut



  sub getCompatibilityLevel ($;) {
    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    return $self->{compatibility_level};
  }




=head2 setVersion()

Instance method to set the api version to something other than the default value, or the
value specified when an eBay::API object was instantiated.

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=item *

Scalar representing the version of the the eBay webservices API you
wish to use.

=back

Returns:

=over 4

=item *

B The value of API version (should be the same value
that was provided by the user)

=item *

B    undefined

=back

=cut



  sub setVersion($$;) {

    # Get all values passed in.
    my($self, $apiver) = @_;

    # Validation of the existence of the argument is done implicitly via the sub prototype.
    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($apiver, Params::Validate::SCALAR);

    # Set the proxy
    $self->{api_ver} = $apiver;

    # Return success to the caller.
    return($apiver);

  }# end sub setVersion()



=head2 getVersion()

Instance getter method for getting the current ebay api version level
to be used.

Arguments:

=over 4

=item *

Reference to an object of type eBay::API.

=back

Returns:

=over 4

=item *

B  The value of the current ebay api version to be used.

=item *

B    undefined

=back

=cut

  sub getVersion($;) {

    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    # Return success to the caller.
    return $self->{api_ver};

  }# end sub getVersion()




=head2 setCompression()

Enables/disables compression in the HTTP header.  This tells the API
whether the client application can accept gzipped content or not.
Do not set this unless you have CPAN module Compress::Zlib.

Arguments:

=over 4

=item *

A reference to object of type eBay::API.

=item *

Boolean value (0 = false; non-zero = true);

=back

Returns:

=over 4

=item *

The boolean value to be set for this attribute.

=back

=cut




  sub setCompression($$;) {
    my $self = shift;
    my $bool = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    eBay::API::BaseApi::_check_arg($bool, Params::Validate::BOOLEAN);

    $self->{compression} = $bool;
    return $bool;
  }


=head2 isCompression()

Indicates if gzip compression has been requested from the API.

Arguments:

=over 4

=item *

A reference to an object of type eBay::API.

=back

Returns:

=over 4

=item *

True if compression is enabled; false if it is not

=back

=cut



  sub isCompression($;) {
    my $self = shift;

    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);

    return $self->{compression};
  }

=pod

=head2 setTimeout()

Call this instance method to set the number of seconds a session or a call should wait
for the eBay XML API web services to respond to a request.  This parameter
controls the behavior of the call retry logic.

Arguments:

=over 4


=item *

The name  of this class/package.

=item *

(Required) A scalar integer value indicating the number of seconds to
wait for a web service request to return with a response.

=back

Returns:

=over 4

=item *

Undefined.

=back

=cut


  sub setTimeout($$;) {
    my $self = shift;
    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    $self->{'timeout'} = shift;
  }


=pod

=head2 getTimeout()

Call this instance method to get the number of seconds a session or a call should wait
for the eBay XML API web services to respond to a request.  This parameter
controls the behavior of the call retry logic.

Arguments:

=over 4


=item *

The name  of this class/package.

=back

Returns:

=over 4

=item *

The number of seconds the call or session should currently wait for a response
from a web service.

=back

=cut


  sub getTimeout($;) {
    my $self = shift;
    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    return $self->{'timeout'};
  }


=pod

=head2 setCallRetry()

Call this instance method to set the number of times a session or a call should
retry an eBay XML API web service before giving up.  This parameter
controls the behavior of the call retry logic.

Arguments:

=over 4


=item *

The name  of this class/package.

=item *

(Required) A reference to an object of type eBay::API::XML::CallRetry.  This
object contains parameters controlling how to retry a call if there is an
error, including number of times to retry, delay in milliseconds between retries,
a list of errors that will permit a retry.  See CallRetry documentation
for more details.

=back

Returns:

=over 4

=item *

Undefined.

=back

=cut


  sub setCallRetry($$;) {
    my $self = shift;
    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    $self->{'callRetry'} = shift;
  }


=pod

=head2 getCallRetry()

Call this instance method to get any eBay::API::XML::CallRetry object
that has previously been set to control retry behavior.

Arguments:

=over 4


=item *

The name  of this class/package.

=back

Returns:

=over 4

=item *

The number of times the call or session should currently retry for a response
from a web service.

=back

=cut


  sub getCallRetry($;) {
    my $self = shift;
    # Validation
    eBay::API::BaseApi::_check_arg($self, Params::Validate::OBJECT);
    return $self->{'callRetry'};
  }


=pod

=head2 getApiReleaseNumber()

Modifier: static
Access:   public
Note:     Returns the SDK's release number

=cut

sub getApiReleaseNumber() {
   return eBay::API::XML::Release::RELEASE_NUMBER;
}

# _check_arg()

#  Protected package method to validate arguments to subroutines.  Uses
#  CPAN module Params::Validate.  Will throw exceptions if parameters
#  are not correct.

#  Returns false if the parameter check occurred and it failed; otherwise
#  returns true.

sub _check_arg ($$;) {
  if ($CHECK_PARAMETERS) {
    my $argvalue = shift;
    my $argtype = shift;
    my @args;
    push(@args, $argvalue);
    eval {
      validate_pos(@args, { type => $argtype });
    };
    if ($@) {
      my ($package, $filename, $line) = caller;
      $argvalue = (defined $argvalue) ? $argvalue : 'null';
      ebay_throw eBay::API::UsageException(error => 'Invalid argument type: ' . $argvalue,
					   package  => $package,
					   file  => $filename,
					   line => $line);
      return 0;
    }
  }
  return 1;
}


=pod

=head2 enableParameterChecks()

Public package method to enable run-time validation of arguments to
subroutines in the eBay::API package.  Checking is enabled by default,
but you may want to disable checking in production to reduce overhead.
Having checking enabled is probably most useful during development of
your application.

This method is both a getter and a setter.

Usage:


  if (eBay::API::BaseApi::enableParameterChecks()) {
    eBay::API::BaseApi::enableParameterChecks(0);
  }

Arguments:

=over 4

=item *

(Optional) A scalar boolean value to enable (non-zero) or disable (0)
run-time parameter checking in the eBay::API package.

=back

Returns:

=over 4

=item *

True if checking is enabled; false if it is not.

=back

=cut

sub enableParameterChecks(;$) {
  my $bool = shift;
  if (defined $bool) {
    $CHECK_PARAMETERS = $bool;
  }
  return $CHECK_PARAMETERS;
}

1;