NAME

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

INHERITANCE

This is the base class

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.

Subroutines

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

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:

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

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

Arguments:

• The name of this class/package.

• A hash reference containing the following possible arguments:

  • site_id => 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;

  • dev_id => 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.

  • app_id => 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.

  • cert_id => 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.

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

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

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

  • api_ver => 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().

  • proxy => 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 * # #debug => Boolean. TRUE means we'll want debugging for the #request/response. FALSE means no debugging.

    # Deprecated #=item * # #err_lang => 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().

  • compatibility_level => 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().

  • sequential => 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().

  • timeout => 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();

Returns:

• success Object reference to the eBay::API::XML::Session class.

• failure undefined

setLogHeader()

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

Arguments:

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

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

Returns:

• The boolean value to be set for this attribute.

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:

• Reference to an object of type eBay::API.

• Scalar data to be logged.

Returns:

• True if message was logged; otherwise undef.

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:

• Reference to an object of type eBay::API.

• Scalar data to be logged.

Returns:

• True if message was logged; otherwise undef.

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:

• Reference to an object of type eBay::API.

• Scalar data to be logged.

Returns:

• True if message was logged; otherwise undef.

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:

• Reference to an object of type eBay::API.

• Scalar log level.

• Scalar data to be logged.

Returns:

• True if message was logged; otherwise undef.

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

  <?xml version="1.0" encoding="utf-8" ?>

and will DELETE them from the message.

Arguments:

• Reference to an object of type eBay::API.

• Scalar log level.

• Scalar data to be logged.

Returns:

• True if message was logged; otherwise undef.

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:

• Object reference of type eBay::API.

• Reference to a logging handler subroutine, provided by user

Returns:

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

• error undefined

getLogSubHandle()

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

Arguments:

• Object reference of type eBay::API.

Returns:

• success The current value of $LOG_SUB_HANDLE

• error undefined, not currently possible to get this

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:

• Reference to object of type eBay::API.

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

Returns:

• success 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.)

• error undefined

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:

• success The current value of $LOG_FILE_HANDLE

• error undefined, not currently possible to get this

testLogEntry()

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

Arguments:

• Reference to object of type eBay::API.

• Scalar representing some test data to log.

Returns:

• success TRUE

• error undefined

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:

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

• Optional object or hash reference.

Returns:

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

• error Whatever _logThis() returns.

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.

• eBay::API::BaseApi::LOG_DEBUG Full debugging information is logged, along with all log messages of higher levels.

• eBay::API::BaseApi::LOG_INFO Informational and all higher logging level messages are logged.

• eBay::API::BaseApi::LOG_WARN Warnings and all higher logging level messages are logged.

• eBay::API::BaseApi::LOG_ERROR Errors and all higher logging level messages are logged.

• eBay::API::BaseApi::LOG_FATAL Only errors which causes immediate termination of the current transaction are logged.

Arguments:

• Reference to object of type eBay::API.

• Scalar constant logging level.

Returns:

• success: The logging level requested.

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

getLogLevel()

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

Arguments: none

Returns:

• success: The current logging level.

• error: undefined

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:

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

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

Returns:

• success The value of the dev id.

• error undefined

getDevID()

Gets the current dev id setting.

Arguments:

• Reference to a session object.

Returns:

• success The value of the dev id.

• error undefined

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:

• Reference to a session object.

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

Returns:

• success The value of new app id.

• error undefined

getAppID()

Get the current app id for the session.

Arguments:

• Reference to a session object.

Returns:

• success The value of the app id.

• error undefined

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:

• Reference to a session object.

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

Returns:

• success The cert id just set.

• error undefined

getCertID()

Gets current cert id.

Arguments:

• Reference to session object.

Returns:

• success The value of the cert id.

• error undefined

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:

• Object reference of type eBay::API.

• Scalar site id.

Returns:

• success Site id given as argument.

• error undefined

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:

• Object reference of type eBay::API.

Returns:

• success Site id given for the current session.

• error undefined

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:

• Object reference of type eBay::API.

• Scalar user name.

Returns:

• success User name given as argument.

• error undefined

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:

• Object reference of type eBay::API.

Returns:

• success User name given for the current session.

• error undefined

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:

• Object reference of type eBay::API.

• Scalar user password.

Returns:

• success User password given as argument.

• error undefined

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:

• Object reference of type eBay::API.

Returns:

• success User password given for the current session.

• error undefined

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:

• Reference to an object of type eBay::API.

Returns:

• success: 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.

isSuccess()

Indicates general 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:

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

• failure 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.

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:

• Object reference of type eBay::API.

• Scalar user auth token.

Returns:

• success User auth token given as argument.

• error undefined

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:

• Object reference of type eBay::API.

Returns:

• success User auth token given for the current session.

• error undefined

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:

• Object reference of type eBay::API.

• Scalar compatibility level.

Returns:

• success Compatibility level given as argument.

• error undefined

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:

• Object reference of type eBay::API.

Returns:

• success Compatibility level for the current session.

• error undefined

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:

• Reference to an object of type eBay::API.

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

Returns:

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

• error undefined

getVersion()

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

Arguments:

• Reference to an object of type eBay::API.

Returns:

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

• error undefined

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:

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

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

Returns:

• The boolean value to be set for this attribute.

isCompression()

Indicates if gzip compression has been requested from the API.

Arguments:

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

Returns:

• True if compression is enabled; false if it is not

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:

• The name of this class/package.

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

Returns:

• Undefined.

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:

• The name of this class/package.

Returns:

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

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:

• The name of this class/package.

• (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.

Returns:

• Undefined.

getCallRetry()

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

Arguments:

• The name of this class/package.

Returns:

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

getApiReleaseNumber()

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

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:

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

Returns:

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

cpanm eBay::API

perl -MCPAN -e shell
install eBay::API